Turning Repetitive Workflows into Codex Skills: A Guide from Zero to GitHub

If you find yourself feeding the exact same prompt to AI every week, this guide is for you.

Imagine every Friday you have to tell Codex: First, compile this week’s achievements, then extract problems and lessons learned, and finally list action items for next week. Do not fabricate data, and every action item must have a completion criteria.

Doing this once is just a prompt. Doing it every week means you actually have a fixed workflow. Packaging this workflow into a folder—so Codex knows exactly when to take over, what steps to follow, and what standards to meet—is what we call a Skill.

A Skill essentially translates the methodology in your head into a repeatable system. I will use a “Weekly Review” as a running example to walk you through the entire route: finding the workflow, breaking it down, creating the Skill, testing, and uploading to GitHub. You don’t need to know how to code.

What Exactly is a Codex Skill, and How is it Different from a Regular Prompt?

A Skill is a system that solidifies regular prompts. While a prompt solves a single task in one conversation, a Skill solves a category of recurring tasks.

Think of Codex as a highly capable but newly hired colleague. It understands writing, code, spreadsheets, and analysis, but it has no idea:

• Under what circumstances you initiate a specific task.
• Whether you prefer to do step A before step B.
• Which internal company rules are non-negotiable.
• What specific sections the final output must contain.
• What constitutes a “passing” result.

A Skill is the job description, standard operating procedure (SOP), and necessary toolset you hand to this new colleague.

A typical Skill tells Codex four things:

1. When to use it: Which tasks or phrases should trigger it.
2. How to execute: What steps to follow upon receiving the task.
3. What to use: Where to find scripts, reference materials, or templates.
4. What counts as done: The criteria the final output must meet.

Regular prompts serve the current chat window. Skills are saved in a fixed directory. Afterward, you can explicitly call them using $skill-name or let Codex automatically decide whether to use them based on the task. Prompts solve one task; Skills codify a type of task.

How Do You Know If a Workflow is Worth Turning Into a Skill?

Only recurring tasks with stable inputs, outputs, and fixed steps deserve to become Skills. Don’t automate one-off tasks or things you can explain in a single sentence.

Before rushing to create a Skill out of any prompt, run it through these four questions:

1. Does this happen repeatedly?
2. Does it have relatively stable inputs and outputs?
3. Are there fixed steps, rules, or judgment criteria in between?
4. If you switched to a different AI, would you have to re-explain the whole thing?

If you answer “yes” to three of these, it’s usually worth codifying.

Good candidates include:

• Compiling scattered notes into a weekly review and next week’s plan.
• Writing long-form articles using a specific prompt skill or standardized title formatting.
• Running through a fixed checklist before a product release.
• Auditing contracts for the same set of risk factors.
• Replying to customer service messages based on brand guidelines.
• Converting formatted meeting notes into task lists.
• Processing the same type of PDFs, spreadsheets, or API data repeatedly.

Bad candidates are equally clear: one-off temporary tasks, simple operations explainable in one sentence, tasks entirely reliant on spontaneous creativity, or broad goals like “handle all my content.”

The most common mistake I see is trying to build an “omnipotent content assistant” right out of the gate. The broader the scope, the fuzzier the trigger, and the more unstable the execution. “Help me with content operations” is a terrible first Skill. “Turn interview notes into an X long-form post matching a fixed structure” is much better. A good Skill doesn’t do everything; it does one specific thing reliably.

Step 1: How to Document an Implicit Workflow on Paper

Start by filling out a “workflow card” that captures the trigger conditions, user inputs, execution steps, success criteria, and exception handling. Don’t rush to create files yet.

Pick a task you’ve repeated at least twice in the past month, and write out this workflow card:

Workflow Name:

When to trigger:

What the user will provide:

Execution steps:
1.
2.
3.

Final output:

What counts as a passing result:

What to do when information is missing or errors occur:

Here is how it looks for a “Weekly Review”:

Workflow Name:
Compile a week's scattered notes into a review

When to trigger:
User asks for a weekly report, weekly review, weekly summary, or work retrospective.

What the user will provide:
Things accomplished, problems, data, and next week's plan.

Execution steps:
1. Extract facts and data.
2. Categorize into achievements, progress, problems, and lessons.
3. Merge duplicate content.
4. Convert unfinished items into next week's actions.
5. Check for fabricated data or fluff.

Final output:
Structured weekly review and next week's action plan.

What counts as a passing result:
Preserves original data; no fabrications; actions have priorities and completion criteria.

What to do when information is missing or errors occur:
Mark as "To be supplemented," ask a maximum of 3 questions, do not guess.

This card is crucial because the Skill’s description, workflow, and quality standards all stem from it. If you can’t fill it out completely, the workflow isn’t stable yet. Do it manually a few more times, observe how you make decisions, and then come back to build the Skill. Don’t package chaos as a Skill; figure the workflow out first.

Designing Triggers: Why Do You Need Three Real-World Test Cases?

Because a Skill is triggered by natural language, you must test explicit invocation, automatic triggering, and edge cases with incomplete information.

Next, write down three phrases a user might actually say.

The first is an explicit call:

Please use $weekly-review to organize this week's notes.

The second is a natural expression:

Help me turn these raw notes into a weekly report and list priorities for next week.

The third is an edge case with incomplete information:

I was mostly working on the payment feature this week, help me do a review.

These three phrases test whether Codex can execute correctly when called, trigger automatically without being named, and avoid making things up when data is scarce. Many people only write about “what this Skill can do” without considering “how the user will actually ask for it.” The result is a lengthy file that Codex never knows when to use. Trigger cases are not marketing copy; they are the entry tests for your Skill.

Structuring the Skill Folder: What Goes Inside?

The bare minimum is a single SKILL.md file. You can add directories for configurations, scripts, references, and assets as needed.

A minimal Skill looks like this:

your-skill/
└── SKILL.md

A more complete structure looks like this:

your-skill/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
├── references/
└── assets/

Each part solves a different problem:

Directory/File	Necessity	What it solves	When to add it
SKILL.md	Required	Trigger conditions, workflow steps, quality standards	Whenever there is a workflow
agents/openai.yaml	Recommended	Controls UI name, description, and default prompt	When customizing display info
scripts/	As needed	Stable code execution (e.g., format conversion, data validation)	When the same code is rewritten every time
references/	As needed	Long materials like company rules, glossaries, API docs	When background material is long and not always needed
assets/	As needed	Templates, images, fonts for final delivery	When every delivery uses the same template

Don’t create a bunch of empty directories just to look professional. Skills consume context window space, so only keep what is truly necessary to complete the task. Build the minimum viable version first, and add things only when you actually need them.

Initializing the Skill: How to Auto-Generate the Skeleton

Name it using only lowercase letters, numbers, and hyphens. Then, simply let Codex call its built-in skill-creator to generate the framework.

Skill names must use only lowercase English letters, numbers, and hyphens. No spaces or Chinese characters, and the folder name must match the Skill name. Examples: weekly-review, x-article-writer, check-release, or contract-risk-checker.

The easiest approach for beginners is to let Codex use its built-in skill-creator. Send the workflow card you just created to Codex:

Please use skill-creator to turn the following workflow into a Skill.

Skill Name: weekly-review

Workflow:
[Paste your workflow card here]

Requirements:
1. Create it in the current project.
2. Only create files that are actually needed.
3. Validate the Skill upon completion.
4. Tell me how to test and install it.

The skill-creator will run an initialization script and generate a properly structured folder. In this case, it generates:

weekly-review/
├── SKILL.md
└── agents/
    └── openai.yaml

Screenshot key point: After running skill-creator in Codex to initialize weekly-review, the terminal should show the newly created SKILL.md and agents/openai.yaml files.
Image source: Unsplash

Seeing SKILL.md and agents/openai.yaml means initialization is complete. But right now, you just have an empty shell. What you write inside next determines whether the Skill is actually useful.

Core Writing: How to Craft a High-Quality SKILL.md?

SKILL.md is split into a YAML header and a Markdown body. The header determines when the Skill triggers, and the body dictates how it executes once triggered.

The file must start with the YAML header:

---
name: weekly-review
description: Compiles a week's scattered notes into a structured review and next week's action plan. Use when the user mentions weekly reports, weekly reviews, weekly summaries, work retrospectives, learning reviews, or asks to extract achievements, problems, lessons, and next steps from raw notes.
---

The description is the most critical part. It must answer two questions simultaneously: What can this Skill do? And in what scenario should the user use it?

Don’t just write “Helps the user review.” That lacks context. You need to include real trigger phrases like “weekly report,” “weekly review,” “weekly summary,” or “raw notes.” Codex reads the name and description first to decide whether to trigger, before it ever reads the body. Therefore, “when to use it” must live in the description, not buried at the end of the document.

The body doesn’t need to hype up how great the Skill is. It is an execution manual meant for another Codex instance to read. You can use this universal structure:

# Skill Name

State the goal in one sentence.

## Workflow

1. Collect and check inputs
2. Process according to fixed rules
3. Generate results
4. Check results

## When Information is Insufficient or Abnormal

- How to handle missing critical info
- What content cannot be guessed
- When to stop and ask the user

## Output Format

[Fixed sections, order, or templates]

## Quality Standards

- What must be included
- What must not appear
- How to judge if it's complete

For the Weekly Review Skill, the core workflow looks like this:

## Workflow

1. Extract facts: Identify completed items, progress, data, problems, and unfinished items.
2. Categorize: Sort into this week's achievements, key progress, problems & causes, and lessons & insights.
3. Refine: Merge duplicates. Do not fabricate facts the user didn't provide.
4. Formulate actions: Convert unfinished items and problems into next week's actions.
5. Check output: No more than 5 actions, no more than 3 top-priority actions.

## When Information is Insufficient

- If missing dates, data, or owners, mark as "To be supplemented." Do not guess.
- If records are too sparse, output what can be confirmed, then ask up to 3 questions.

## Quality Standards

- Use specific action verbs. Avoid fluff like "continuously optimize" or "actively push forward."
- Distinguish between facts and inferences.
- Every action must have a checkable completion criteria.

Screenshot key point: Viewing SKILL.md content in the terminal, showing the YAML header and body sections like “Workflow” and “Quality Standards.”
Image source: Pexels

Three rules for writing the body:

1. Only write what Codex needs to know to complete the task.
2. The more error-prone a step is, the more specific the rules must be.
3. If you can explain it in 30 lines, don’t write 300.

A Skill is not an encyclopedia; it’s an execution manual.

Validation & Installation: How to Ensure the Skill is Read Correctly

Use skill-creator to validate the format, then copy the entire folder into the ~/.codex/skills/ directory. Don’t declare victory right after writing it.

First, ask skill-creator to validate it:

Please use skill-creator to validate ./weekly-review.
If you find format, naming, or YAML issues, fix them directly and re-validate.

The validator checks if the folder name matches the Skill name, if the YAML format is correct, if name and description exist, and if the name follows the rules. Upon success, you’ll see a message like “Skill is valid!” (exact wording depends on your local skill-creator version).

Next, install the entire Skill folder into Codex’s Skill directory. The default is usually ~/.codex/skills/. (Note: Some Codex versions or docs use .agents/skills. They are functionally the same; pick one and stick with it. This guide uses .codex/skills/.)

On macOS or Linux, you can run:

cp -R ./weekly-review ~/.codex/skills/

Or simply tell Codex:

Please install ./weekly-review into my Codex Skills directory.

Screenshot key point: Terminal output showing skill-creator validation passed, and the directory structure after installing to ~/.codex/skills/weekly-review.
Image source: Pixabay

If it doesn’t appear immediately after installation, start a new Codex task. If it’s still missing, restart Codex. Passing structural validation only proves the file format is correct. It doesn’t prove the workflow is actually good.

Real-World Testing & Troubleshooting: What to Fix When It Breaks

Test the three cases you prepared earlier. Tweak specific configurations based on whether it fails to trigger, scrambles the order, or hallucinates data.

Test 1: Explicit Invocation

Please use $weekly-review to organize the notes below.

Check if it outputs according to the sections and order defined in the Skill.

Test 2: No Explicit Name

Turn these raw notes into a weekly report and list next week's priorities.

Check if the description is clear enough for Codex to trigger automatically.

Test 3: Incomplete Information

I was mostly working on the payment feature this week, help me do a review.

Check if it explicitly flags missing info instead of fabricating dates, data, or owners.

When I tested this, I fed it scattered notes about a homepage launch, a payment integration failure, an expired certificate, bug fixes, and next week’s A/B test. The Skill automatically organized it into:

• This week’s achievements
• Key progress
• Problems & causes
• Lessons & insights
• Next week’s actions (with priorities and completion criteria)
• Information that needs to be supplemented

Screenshot key point: After inputting scattered notes, the weekly-review skill outputs structured categories like “Achievements / Progress / Problems / Lessons / Next Actions.”
Image source: Gratisography

If the results aren’t ideal, don’t scrap the whole Skill. Figure out where the breakdown happened:

Symptom	Troubleshooting direction	Where to edit
Doesn’t auto-trigger	Trigger words aren’t rich enough	Update description
Execution order is unstable	Step descriptions are ambiguous	Update Workflow

• | Keeps producing fluff | Lacks constraints | Add to Quality Standards |
  | Hallucinates when info is missing | Missing boundary rules | Add to exception handling |
  | Same code generated repeatedly | Logic isn’t fixed | Move code to scripts/ |
  | SKILL.md getting too long | Reference material is cluttering the main flow | Move long materials to references/ |

The goal of testing isn’t to prove version 1.0 is perfect. It’s to find out what to fix in version 1.1.

Code Hosting: How to Safely Upload Your Skill to GitHub

Create an empty GitHub repository, scrub all sensitive information, and use Git commands to initialize and push to the remote. Once the Skill works locally, put it on GitHub. GitHub helps you back up workflows, track changes, sync across devices, share with teams, and roll back to older versions if something breaks.

First, create an empty repository on GitHub.

Image source: Unsplash

If your Skill contains company processes, client data, or internal rules, select Private. Before making anything public, check and delete:

• API Keys
• Tokens
• Passwords and accounts
• Customer data
• Internal company addresses
• Unpublished business rules

Then, in your local project directory, run:

git init -b main   # Requires Git ≥ 2.28; older versions use git init && git branch -m main
git add .
git commit -m "feat: add my first Codex skill"
git remote add origin <your-repo-url>
git push -u origin main

For future edits, you just need:

git add .
git commit -m "docs: improve skill workflow"
git push

Before pushing, use git status and git diff --cached to confirm no sensitive information is included in the commit.

Screenshot key point: The GitHub page for the pushed private repo, showing files like SKILL.md and agents/.

At this point, you’ve built something far more substantial than a prompt. You own a personal workflow system that can be installed, tested, modified, synced, and shared.

The 5 Most Common Pitfalls for Beginners

1. Stuffing chat logs directly into SKILL.md: Chat logs are not workflows. Extract the trigger conditions, steps, exception handling, and acceptance criteria first.
2. Trying to solve every problem with one Skill: The larger the scope, the less stable the auto-trigger and output. Start with one clear input and one clear output.
3. Having steps but no completion criteria: “Generate a report” is not an acceptance criteria. “Include 5 fixed sections, with every action having a priority and completion criteria” is.
4. Assuming completion after validation passes: The validator only checks structure. True quality must be tested with normal, fuzzy, and incomplete information.
5. Uploading sensitive info to a public repo: “Public” on GitHub means anyone can see it. If unsure, use Private.

Practical Summary & Actionable Checklist

The core of codifying a Skill is turning “I have to re-explain this every time” into “It knows what to do from now on.”

1. Find a task you’ve repeated at least twice in the past month.
2. Fill out the workflow card (trigger, input, steps, output, passing criteria, exception handling).
3. Write three real-world trigger cases (explicit, natural, missing info).
4. Let Codex use skill-creator to generate the minimum viable skeleton.
5. Write the YAML header and Markdown execution body for SKILL.md.
6. Validate and install to the ~/.codex/skills/ directory.
7. Test with your three cases and troubleshoot based on the results.
8. Scrub sensitive info and push to a private GitHub repository.

Frequently Asked Questions (FAQ)

Q: Do I need to know how to code to create a Skill?
No. As long as you can clearly fill out the workflow card, you can just let Codex call skill-creator to generate the skeleton.

Q: What is the fundamental difference between a prompt and a Skill?
A prompt solves a single task in the current chat. A Skill is saved in a fixed directory to solve a category of recurring tasks, either by explicit call or automatic trigger.

Q: Are there restrictions on the Skill folder name?
Yes. You can only use lowercase English letters, numbers, and hyphens. No spaces or Chinese characters, and it must match the Skill name.

Q: What if Codex doesn’t auto-trigger the Skill?
Check the description in SKILL.md. Make sure you’ve included real trigger phrases and specific scenarios that a user might actually say.

Q: What if the Skill doesn’t show up after installation?
Start a new Codex task, or restart Codex entirely.

Q: How long should the SKILL.md body be?
Only write what is strictly necessary to complete the task. If you can explain it in 30 lines, don’t write 300.

Q: Does passing validation mean the Skill is ready to use?
No. Validation only checks file formatting. You must test it with real-world tasks to see if it’s actually useful.

Q: What must I do before uploading to GitHub?
Check for and delete API keys, passwords, and customer data. If you are unsure, set the repository to Private.

About the Author

Punk | USTC MBA | Chief Designer at HerName | Executive Dean of Stanley Business School. Focuses on AI prompt engineering and “Learn in Public” practices.