How to Write Your Own Codex Skills Workflow: From Repeated Prompts to Reusable SKILL.md

How do you write your own Codex skills workflow? The simplest answer: take the instructions you repeatedly paste into Codex and turn them into a discoverable, maintainable SKILL.md.

If a task is one-off, just write the prompt. A skill is worth creating only when the workflow repeats, has stable steps, reads similar files, runs similar commands, or produces similar output.

Quick Answer

A useful Codex skill usually has four traits:

description says when to use it, not just what it is.
SKILL.md describes workflow, boundaries, inputs, outputs, and verification.
Long references go in references/; repeatable commands go in scripts/; templates go in assets/.
After every change, test it with a real task to confirm it triggers when it should and stays quiet when it should not.

Good skill candidates include:

1
2
3
4
5


turn a Chinese source post into a publishable blog article
turn logs into a daily report
review a PR for security, regressions, and missing tests
deploy a site through build, sync, purge, and submit steps
normalize product images into a fixed format

The right unit for a skill is not a knowledge topic. It is a repeatable way of working.

Skill, AGENTS.md, Hooks, and MCP

Before writing a skill, put the rule in the right place.

Need	Better place
One-off task requirement	Current prompt
Repository conventions, test commands, commit rules	`AGENTS.md`
Reusable task workflow	Skill
Mechanical rule before or after tool use	Hook
External systems, databases, private services	MCP server or app connector
Scheduled checks or reports	Automation
Installable bundle of multiple capabilities	Plugin

For example, “always format after editing” is more like a hook. “Review PRs by checking security, edge cases, and test gaps” is more like a skill. “This repo uses pnpm, not npm” belongs in AGENTS.md.

Minimal Directory Structure

A minimal skill can be one file:

1
2


my-workflow/
  SKILL.md

A larger one can be:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


my-workflow/
  SKILL.md
  references/
    checklist.md
    examples.md
  scripts/
    validate.ps1
    collect-data.py
  assets/
    report-template.md

Common roles:

SKILL.md: entry instructions, when to use, how to run, how to verify.
references/: long background, examples, rubrics, terminology tables.
scripts/: stable mechanical commands.
assets/: templates, sample files, prompt fragments, report formats.

Do not create folders just to look professional. Start small.

Basic SKILL.md Template

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


---
name: my-workflow
description: Use when the user asks to <specific trigger>. Handles <input>, produces <output>, and verifies <completion criteria>.
---

# My Workflow

## Purpose

Explain what repeated task this skill solves and what it does not solve.

## When To Use

- Use when the user explicitly mentions this task.
- Use when the task needs fixed steps, fixed output, or fixed validation.
- Do not use for ordinary Q&A.

## Inputs

- What must the user provide?
- What can be discovered from the repository?
- What should be assumed or asked if missing?

## Workflow

1. Check current state.
2. Read required files.
3. Perform the core task.
4. Run lightweight validation.
5. Report results and remaining work.

## Constraints

- Which files must not be changed?
- Which commands must not be run?
- Which fields must be preserved?
- How should conflicts be handled?

## Verification

- Check output files.
- Check format.
- Check commands.
- Check residual risks.

## Reporting

Final response should include:

- what changed
- what did not change
- validation result
- risks for the user

You do not need every heading, but the skill should answer these questions.

The Description Is the Key Line

Weak:

1

description: Help with reports.

Better:

1

description: Use when the user asks to create a weekly engineering report from Git commits, issue updates, or work notes. Produces a concise report with completed work, impact, blockers, and next actions.

The description should include trigger, input, output, and boundary. If natural-language tasks do not trigger the skill, the description is probably too vague.

Turn Prompts into Workflow

A prompt is often a one-off instruction:

1

You are a senior engineer. Please review this change and focus on edge cases and tests.

A skill should be a procedure:

1
2
3
4
5
6
7
8


## Workflow

1. Run `git status --short`.
2. Read the relevant diff.
3. Identify behavior changes before style issues.
4. List findings by severity.
5. Prioritize bugs, regressions, security issues, and missing tests.
6. If no issues are found, say so and list residual test gaps.

Procedures are easier to execute and easier to audit.

When to Split References

Move long material to references/ when it includes:

long style guides;
many output examples;
terminology tables;
API field descriptions;
scoring rubrics;
translation maps;
domain rules;
background not needed every time.

Keep SKILL.md as the router:

1
2
3
4
5


## References

- Read `references/report-rubric.md` only when judging report quality.
- Read `assets/weekly-report-template.md` when generating a full report.
- Do not load the full example library for a short summary.

This reduces context waste.

When to Add Scripts

Script a step if it is stable, mechanical, and easy to get wrong.

Good script candidates:

scanning files and generating an inventory;
validating front matter;
converting JSON to Markdown tables;
downloading fixed-source data;
running fixed build commands;
batch image conversion;
checking links, slugs, dates, or language files.

Keep judgment in Codex. Put mechanical execution in scripts.

Example: Weekly Report Skill

1
2
3
4
5
6


weekly-report/
  SKILL.md
  assets/
    weekly-report-template.md
  scripts/
    collect-git-summary.ps1

SKILL.md:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


---
name: weekly-report
description: Use when the user asks to create a weekly work report from Git commits, notes, issue updates, or chat summaries. Produces a concise Chinese report with completed work, impact, blockers, and next week plan.
---

# Weekly Report

## Workflow

1. Confirm the report date range. If missing, use the current week.
2. Use user-provided notes first.
3. If the user asks to include Git work, run `scripts/collect-git-summary.ps1`.
4. Group work by project or theme, not raw commit order.
5. Produce a concise Chinese report using `assets/weekly-report-template.md`.
6. Mark uncertain items as uncertain instead of inventing progress.

## Constraints

- Do not expose private commit hashes unless asked.
- Do not claim shipped work if the source only shows drafts.
- Keep blockers separate from completed work.

## Reporting

Return the report and list sources used.

The value is the fixed process, not just “write a report.”

Example: Code Review Skill

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


---
name: focused-code-review
description: Use when the user asks for a code review of the current working tree, a commit, or a pull request. Prioritize bugs, regressions, security risks, and missing tests; do not rewrite code unless asked.
---

# Focused Code Review

## Workflow

1. Inspect `git status --short`.
2. Read the relevant diff.
3. Identify behavior changes before style issues.
4. List findings first, ordered by severity.
5. Include file and line references when possible.
6. If no issues are found, say so and mention remaining test gaps.

## Constraints

- Do not edit code during review.
- Do not focus on formatting unless it can cause a real bug.
- Do not summarize before findings.

This keeps review posture consistent.

Example: Blog Publishing Skill

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


---
name: blog-post-publish
description: Use when the user asks to create or update a Hugo blog post in this repository. Handles post numbering, front matter, Markdown structure, lightweight validation, and publish-ready reporting.
---

# Blog Post Publish

## Workflow

1. Check `git status --short`.
2. If creating a new post, find the next numeric directory.
3. Create only the requested language file.
4. Preserve slug and date for existing posts.
5. Validate front matter, code fences, links, and encoding.
6. Do not run a full Hugo build unless requested.

## Constraints

- Do not overwrite the active article when the user asks for a new post.
- Do not generate translations unless explicitly asked.
- Do not change published URL fields casually.

This prevents expensive mistakes such as writing to the wrong directory or changing a public URL.

Test Your Skill

After writing a skill, test three things.

First, can it be selected?

1

$weekly-report create a report from this week's commits

Also test natural language:

1

Create a weekly report from this week's git commits.

Second, are the steps clear after selection? Watch whether Codex reads the right files, runs the right scripts, and follows the constraints.

Third, does it avoid false triggers? If ordinary Q&A triggers the skill, narrow the description.

Common Mistakes

Turning a Skill into an Encyclopedia

A skill is not a knowledge base. Put background in references/; keep the entry file focused on doing the work.

Vague Description

Keywords like “Codex, workflow, automation” are not enough. Codex needs to know when to use it, what input it handles, and what output it produces.

No Completion Criteria

Without verification, Codex may say it is done too early. Write how to check files, commands, format, or results.

Dangerous Scripts

Do not default to deleting, overwriting, publishing, paid API calls, or mass renames. High-risk actions need confirmation.

One Giant Skill

“My universal workflow” is hard to maintain. Split into small skills: writing, translation, deployment, SEO, review, weekly report.

Maintenance

Change one small thing after each failure:

missed trigger -> improve description;
triggered but unstable -> improve Workflow;
output format drifts -> improve Reporting or templates;
repeated command -> move it to scripts/;
SKILL.md too long -> move background to references/.

Treat skills like code: small, testable, and maintained.

References

Summary

Codex skills are not just saved prompts. They turn repeatable workflows into discoverable, executable, verifiable project assets.

Start small. Write a specific description, define inputs and outputs, list the workflow, document constraints, script mechanical steps, and test both triggering and non-triggering cases.