Codex Skills System: How to Build Reusable Markdown Instruction Files for Every Project

One Markdown File That Makes Every Codex Session Smarter

Codex stores reusable instruction files — called skills — in ~/.codex/skills/ globally, or inside your project directory locally. Each skill is just a markdown file. When you invoke it with a slash command, Codex reads the file and follows the instructions exactly, every time. That’s the whole system. No plugins to install, no API keys to configure, no special syntax to learn.

The reason this matters: without skills, you’re re-explaining yourself constantly. Every new chat starts from zero. You describe the output format you want, the tools you prefer, the edge cases to avoid — and then you do it again in the next session. Skills are how you stop doing that.

This post walks through how to build a skill from scratch, where to store it, when to use global versus project-local, and how to call it. The examples come from a real workflow: pulling YouTube comments, analyzing them, and producing an Excel report.

What you get when skills work correctly

Before the mechanics, here’s the concrete outcome worth aiming for.

Nate Herk, in his Codex walkthrough, built a YouTube comment analysis workflow from scratch: connect to the YouTube Data API, pull 200 recent comments across multiple videos, classify them, and produce an Excel workbook with charts, pattern summaries, and content recommendations. That took one session to build.

Then he said: “Turn that into a skill so that every time I say to grab my YouTube comments and give me some insights, you do this exact flow and that makes it more consistent.”

Codex created a skill file, stored it globally in ~/.codex/skills/, and from that point forward, /youtube-comment-insights was a real slash command. The next time he opened a completely different project, that skill was still available.

That’s the outcome: a workflow you built once, callable by name, consistent across sessions and projects.

What you need before you start

You need the Codex desktop app installed and a ChatGPT subscription (the $20/month Plus plan gives you access; Pro gives you higher rate limits). You don’t need to know any programming. You do need to understand what you want to automate — the skill is only as good as the workflow it encodes.

A few things worth knowing about the environment:

The context window is ~256,000 tokens. Codex auto-compacts when it fills up, similar to how Claude Code handles long sessions. Skills help here too: a well-written skill file means Codex doesn’t need to rediscover your preferences mid-session.

Model selection matters for skill creation. Use Medium or High intelligence when building and refining skills. Extra High is for hard bugs, not for writing markdown instructions — it tends to over-engineer simple things and costs more of your session budget. You can check how much session you have left under Settings > Rate Limits Remaining.

Full access vs. default permissions. By default, Codex pauses to ask permission before taking actions. For skill creation, this is fine. For running automations that use skills, you’ll probably want to enable Full Access under Settings > General > Auto Review or Full Access. Just know what you’re enabling.

Building your first skill

Step 1: Build the workflow manually first

Don’t try to write a skill file from scratch. Build the workflow in a normal Codex chat, get an output you’re happy with, then ask Codex to reverse-engineer the skill from what it just did.

This is the right order because the skill file needs to encode real decisions: which API endpoints to hit, what output format to use, what to do when something fails. You can’t write those down accurately until you’ve actually run the workflow and seen what works.

In the YouTube example: the first session connected to the YouTube Data API v3, pulled comments, classified them into categories (questions, feedback, tool mentions, content requests), and produced a multi-tab Excel workbook. Only after seeing that output did the skill get written.

Now you have: a working workflow and a concrete output to point at.

Step 2: Ask Codex to create the skill

Once you have an output you like, say something like:

“What you just did — pulling YouTube comments, analyzing them, and creating the Excel sheet — I want you to turn that into a skill so that every time I ask for YouTube comment insights, you follow this exact flow.”

Codex will create a markdown file. By default, it stores this globally in ~/.codex/skills/, which means it’s available in every project you ever open. If you want it scoped to just the current project, say: “Put that skill locally in this project instead of globally.”

The skill file itself is straightforward markdown. It has a name, a description (which tells Codex when to invoke it automatically), and then step-by-step instructions. Here’s roughly what the YouTube comment insights skill looks like:

## YouTube Comment Insights

**Description:** Use when asked to pull YouTube comments, analyze them, or generate an Excel insights report from channel data.

## Steps

1. Read the YouTube API key from `.env.local`
2. Pull the 200 most recent public comments across the last 5 videos using YouTube Data API v3
3. Classify each comment: question, feedback, tool mention, content request, or other
4. Generate an Excel workbook with tabs: Summary, Creator Insights, Frequent Questions, Content Ideas, Raw Comments
5. Save to `/outputs/youtube-comment-insights.xlsx`
6. Do not duplicate comments already present in the existing workbook — merge new rows only

## Notes

- Use Node.js for API calls (PowerShell TLS issues on this machine)
- Channel ID and playlist ID are in `.env.local`

That last note — about PowerShell TLS — came from a real failure in the session. When Codex hit a TLS error using PowerShell’s built-in web request, it fell back to Node successfully. Writing that into the skill means it never tries PowerShell again for this task.

Now you have: a skill file stored at ~/.codex/skills/youtube-comment-insights.md (or in your project’s local skills folder).

Step 3: Verify the slash command exists

Type / in any Codex chat. You should see your skill listed alongside the built-in commands like /browser-use, /image-gen, /pdf, /skill-creator, and /plan. If you stored the skill globally, it appears in every project. If you stored it locally, it only appears when you’re in that project.

If it doesn’t show up, check that the file is in the right directory and that the filename uses hyphens rather than spaces.

Now you have: a callable slash command that runs your workflow on demand.

Step 4: Set up the agents.md file for project context

Skills handle how to do something. The agents.md file handles what this project is about.

Every time you open a new chat in a Codex project, Codex reads agents.md first. It’s the equivalent of CLAUDE.md in Claude Code — an onboarding document that tells Codex the project goal, the relevant context, and any standing instructions.

Create one at the root of your project:

## YouTube Analytics Demo

## About this project
Nate Herk's YouTube comment intelligence system. Pulls comments via YouTube Data API v3, analyzes patterns, and serves a dashboard on Vercel.

## Key files
- `.env.local` — API keys (never commit this)
- `/outputs/youtube-comment-insights.xlsx` — source of truth for dashboard data
- `/dashboard` — Next.js app deployed to Vercel via GitHub

## Standing instructions
- Use Node.js for all API calls (not PowerShell)
- Always merge new comment rows; never overwrite existing data
- Run browser-use QA before marking any dashboard change complete

Keep agents.md lean. Every line in that file gets loaded into your context window at the start of every chat. If it grows to 500 lines, you’re burning tokens on context that may not be relevant to what you’re doing right now.

Now you have: a project that orients Codex correctly from the first message of every session.

Step 5: Refine the skill after each use

The first version of a skill is never the best version. Each time you run it, you’ll notice something: it duplicated rows it shouldn’t have, it used the wrong date range, it formatted a column oddly. Update the skill file.

This is the compounding value. The skill gets more accurate with each use because you’re encoding real failure modes, not hypothetical ones. Think of it like a recipe that gets annotated every time you cook from it.

You can do this manually (open the file, edit it) or ask Codex: “The skill ran correctly but it duplicated 8 comments that were already in the workbook. Update the skill to check for existing comment IDs before inserting.”

Now you have: a skill that improves over time rather than staying static.

Global vs. project-local: when to use each

Global skills (~/.codex/skills/) are for workflows you use across multiple projects. Image generation prompts, code review checklists, morning planning routines, browser QA procedures — anything that isn’t specific to one codebase.

Project-local skills are for workflows tied to a specific project’s structure. The YouTube comment skill, for example, references specific file paths, a specific API key location, and a specific output format. It only makes sense inside that project.

A practical rule: if the skill references a file path, an API key, or a specific database schema, make it local. If it’s a general procedure that could apply anywhere, make it global.

The built-in skills Codex ships with — /browser-use, /image-gen, /pdf — are all global. Your custom skills can be either.

Troubleshooting the real failure modes

The skill doesn’t appear in the slash menu. Check the filename. Codex expects the file to be in ~/.codex/skills/ (global) or in a skills/ folder inside your project directory (local). The filename becomes the command name, so youtube-comment-insights.md becomes /youtube-comment-insights.

Codex ignores the skill and improvises. This usually means the description field isn’t specific enough. The description is what Codex uses to decide whether to invoke the skill automatically. Make it explicit: “Use when the user asks for YouTube comment analysis, comment insights, or channel analytics.”

The skill runs but produces inconsistent output. The instructions are probably underspecified. Go back to the workflow, run it manually again, and notice where Codex made a decision you didn’t anticipate. Add that decision explicitly to the skill file. “Use 4 tabs in the Excel workbook: Summary, Questions, Ideas, Raw” is better than “create an Excel workbook.”

The agents.md file is getting huge. This is a real problem. When agents.md grows past a few hundred lines, you’re loading irrelevant context into every chat. Split it: keep high-level project context in agents.md and move detailed technical notes into separate files that skills can reference explicitly.

The automation that uses the skill runs on GPT 5.2 instead of 5.5. This happened in the demo — the automation was set up with an older model by default. Check your automations under the Automations tab and verify the model setting. Skills are only as good as the model running them; a skill that works well on GPT 5.5 may behave differently on an older version.

Where to take this further

Once you have a few skills working, the natural next step is automations. The Automations tab in Codex lets you schedule skills to run on a timer — hourly, daily, weekly — by injecting a prompt into a new Codex chat inside your project. The YouTube comment insights skill, for example, gets scheduled to run every Sunday at 5pm: pull new comments, update the Excel sheet, push changes to GitHub, let Vercel auto-deploy the dashboard.

The automation is just a scheduled prompt. The skill is what makes that prompt reliable.

If you’re coming from Claude Code, this pattern will feel familiar — the difference between Claude Code skills and plugins maps almost directly to what Codex is doing here. Skills are specialist playbooks you write once; the slash command system is just how you invoke them.

For more complex projects, you’ll want to think about how skills compose with each other. A browser-use QA pass, for example, can be built into a deployment skill: don’t push to GitHub until browser-use has run and found no critical bugs. Codex found 6 real bugs in a freshly built dashboard during one automated QA pass — including broken YouTube external links — without any human prompting. That kind of check belongs in a skill, not in your head.

The self-evolving memory system approach from Claude Code translates here too: use hooks or automations to capture what went wrong in each session and feed that back into your skill files automatically. The skill gets smarter without you having to remember to update it.

If you’re building toward a full production app rather than just a dashboard, the skill-based approach pairs well with tools that treat the spec as the source of truth. Remy, MindStudio’s spec-driven app compiler, takes annotated markdown and compiles it into a complete TypeScript stack — backend, database, auth, deployment. The skill files you write in Codex and the spec you’d write for Remy are solving the same problem from different angles: encoding intent precisely enough that a machine can execute it consistently.

For teams that need to orchestrate multiple agents across different models and integrations, MindStudio offers a visual builder with 200+ models and 1,000+ pre-built integrations — useful when your skills start needing to talk to HubSpot, Salesforce, or Slack in addition to local files.

The Claude Code content marketing skill system post is worth reading if you want to see how this pattern scales to multi-step publishing workflows — the mechanics are the same even though the tools differ slightly.

One opinion worth stating plainly: the skill file is the most underused feature in Codex. Most people use Codex like a chat interface — describe what you want, get an answer, repeat. Skills are what turn it into a system. The difference between “I use Codex sometimes” and “Codex runs part of my workflow automatically” is usually just a few markdown files.