Appearance

Language

Mastering AI agents

How to Write a Skill for Claude Code and Codex: SKILL.md Triggers, Stop Rules and Dry Runs (2026)

Which repeated jobs are worth turning into a skill, how to write a description that fires at the right time, how to put stop rules and dry runs into the steps, and how one copy serves both Claude Code and Codex. With two of my own skills as examples.

Kelvin Wang · · 13 min read

Key points

  1. Write a skill for procedures you keep repeating, that have several steps, and that only some tasks need; rules every task needs stay in AGENTS.md.
  2. A description says what the skill does, what the user actually says, and what it is not for, with the main use first.
  3. Default to read-only; a step that changes things asks first, has a lint or --dry-run before it, and has a checkable definition of done.
  4. Keep the canonical copy in a git repo, symlink it into ~/.claude/skills and ~/.agents/skills, and run a check that catches drift.

A skill is a folder with one SKILL.md in it. The description at the top decides when the AI pulls it in; the body lists the steps, when to stop, and which step needs a human first. I write mine in the same order every time: confirm the job is worth a skill, write the description, split read-only steps from steps that change things, put a dry run in front of anything that writes, then have a fresh agent that has never seen the skill try it. Where to find skills and what to check before installing one is in Claude Code Skills: Where to Find Them and How to Choose; this post is only about writing your own. Spec details follow the official docs as checked on November 17, 2026.

Which jobs are worth turning into a skill?

I write one when all three are true:

  • I keep explaining the same procedure in chat. If every session needs “look here first, then check that, and this number means X”, it should be written down.
  • It has several steps, and the order or the reading of results matters. A one-line rule goes in the rules file. A skill earns its place when the checks must run in order and each result needs interpreting.
  • Only some tasks need it. Both tools read just each skill’s name and description up front and load the full file only when a task matches 12. Things every task needs go in AGENTS.md or CLAUDE.md; occasional procedures go in a skill and cost less context.

My threshold is simple: once I notice I’ve been doing the same thing three days in a row, I turn it into a skill.

WhereWhat belongs thereExample
AGENTS.md / CLAUDE.mdShort rules every task needsThe test command; ask before pushing
skillOccasional multi-step procedures with an order and judgment callsSocial post draft pipeline; scheduler health check
script, test, hookRules that must always hold and a program can checkLength limits; no numbers the source never gave

Two of my skills sit right in that range:

  • kw-studio-new-post. I use it to turn an idea into Threads and X drafts. Every run produces the same four files (my own words, notes for me, the X thread, the Threads thread). The two platforms count length differently, and the result lands in my site’s back office as a draft.
  • qn-monitor-cron. A quant trading project has a scheduled job that syncs a ledger, and “is the scheduler running properly?” is a question I asked many times. Each time the answer came from the same few places, checked in the same order, and a couple of the numbers are easy to misread.

What does a SKILL.md look like?

The smallest skill is frontmatter plus some instructions. Claude Code skills follow the Agent Skills open standard 13, and Codex requires name and description 2, so write both and the skill works in both tools:

---
name: deploy-check
description: Checks a service after a deploy: version, health check, error rate. Use when the user says "deploy is done" or "check prod after the release". Not for running the deploy itself.
---

# deploy-check

Read-only. Go in order; if any step fails, stop and report. Do not fix things.

1. ...
2. ...

Which folder holds personal and project skills, and how to call one directly, is in the table in the post on finding skills. The differences that matter when writing one are these:

ItemClaude CodeCodex
Required fieldsAll optional; description recommendedname, description
Stop the AI calling it on its owndisable-model-invocation: trueallow_implicit_invocation: false in agents/openai.yaml
Description lengthdescription plus when_to_use is cut at 1,536 characters in the listingthe whole skill list defaults to 2% of the context window
Body lengthkeep SKILL.md under 500 lines; move detail into side fileskeep each skill to one job
SymlinksSupportedFollows symlinks to the real folder

Sources: Claude Code skills docs [1], Codex Build skills docs [2].

How do you write a description that fires at the right time?

The description is the most important part of a skill. Both tools match the task against it first and read the body only on a match 12. A weak description means a carefully written body never gets read.

Mine always say three things:

  1. What it does, in the first sentence. Both tools’ docs say to front-load the main use case 12, and Claude Code’s listing cuts description plus when_to_use at 1,536 characters.
  2. The words the user really says. kw-studio-new-post lists the phrases I use, such as “make it a thread”, “post draft”, “revise the draft”. qn-monitor-cron lists “did the cron run”, “reconciliation status”, “is the monitor schedule OK”, plus one trigger no person says: when the alert fires.
  3. What it is not for. The last sentence of kw-studio-new-post rules out PR and commit text, specs, READMEs, review reports and internal company documents. That line came from a review on September 28, 2026. The first version said to use it for any prose meant for a human audience, research write-ups and weekly reports included, so any writing task could pull it in. The new version covers only public pieces for my own channels and names the easy-to-confuse cases.

In the body I add one more line: “If you are not sure this skill applies, ask.” The description decides whether the AI thinks of the skill at all; that line handles the gray zone.

For skills that change outside systems and that you want to start only yourself (deploys, publishing), turn automatic use off: disable-model-invocation: true in Claude Code 1, allow_implicit_invocation: false in Codex’s agents/openai.yaml 2.

How do you write stop rules and “ask first” into the steps?

A skill describes how to do something, but for an AI, when not to act matters just as much. qn-monitor-cron is my most complete one, and its layout works as a pattern:

  1. One line on permissions at the top: “Read-only, runs on its own. Query the database first; go to the machine only if needed.” The AI knows straight away that nothing changes by default.
  2. Queries ordered by cost. Step one reads a heartbeat table that needs no extra login. Step two checks reconciliation in the same database. Only step three connects to the machine running the scheduler to read system logs, because that needs a separate login; if the login has expired, it stops and asks me to log in instead of looking for a way around.
  3. How to read each result. Which numbers are normal, and which look like trouble but are not. For example, the “last trade time” lagging by hours is normal: it means the market is quiet, not that the job died. Whether the job is alive is judged by the heartbeat alone.
  4. The step only a human can answer, spelled out. Some conclusions cannot come from the data, such as whether a position was closed by hand. The skill says: do the first two checks yourself, the third can only be asked of the operator, and nothing gets recorded or concluded before that answer.
  5. The single write action in its own section, marked “ask first”. Backfilling missing data is the only thing in this skill that changes anything. Its heading says it is the only write and the user must be asked first, and it says to remove the temporary settings afterward.
  6. Done is defined as data. After a backfill, a green light is not enough: re-run the reconciliation, and the missing record must be found by name with matching quantities.
  7. A closing “Never” section. Things it must not do, such as widening a threshold to make an alert go away.

kw-studio-new-post puts its stop rules in a failure table: on a 5xx from the server, tell me and do not retry in a loop; show any other error and retry at most once. Without stop rules, the most common thing an AI does on an error is try another way and keep going.

How do you check before you run?

Any skill that sends, writes or publishes gets a step where the result can be checked before it is real. kw-studio-new-post has three layers:

  1. lint checks post length, and that the link post holds only a short label and the URL. X allows 280 per post with weighting (Chinese characters, full-width punctuation and emoji count 2, a URL counts 23); Threads allows 500 characters. It names the post that fails.
  2. submit --dry-run prints exactly what would be sent, and sends nothing.
  3. submit checks length again and also refuses any number in a post that is not in my own notes.

SKILL.md fixes the order: rewrite, run lint, fix what it names, lint again, then submit. Even when everything passes, what goes out is a draft: the database keeps anything an AI sends in the “AI draft” state, and publishing waits for me to approve it in the back office.

One principle I keep coming back to: when a written rule doesn’t hold, turn it into a program check. “Don’t write numbers the source never gave” started as one sentence in SKILL.md; after testing, I made submit refuse it outright. Codex’s docs draw the same line: use instructions by default, scripts when you need deterministic behavior or external tools 2.

You don’t need a whole tool to do this in your own skills:

  • With a script, add a --dry-run or lint subcommand and have SKILL.md require it first.
  • With a list of commands, have the steps show the exact commands first and run them only after you reply.
  • When editing files, produce a diff first and apply it after review.
Go deeper How to Write AGENTS.md and CLAUDE.md: One Rules File for Every AI Coding Tool (2026) Where the rules every task needs belong, and how two tools read the same file.

How do you test a skill once it’s written?

Claude Code’s docs suggest a baseline: in a fresh session, run realistic requests with and without the skill and compare whether it triggers at the right time and whether the output is right; turn the skill off for the baseline with skillOverrides 1. Codex’s docs suggest testing prompts against the description to confirm the trigger behavior 2.

I do the same, with two habits on top:

  • Test with a new agent. The session that wrote the skill already knows all the background, so it cannot show what SKILL.md left out. Every major change to kw-studio-new-post gets a fresh agent that follows it from scratch, all the way to a passing submit --dry-run.
  • Add a request that pushes the wrong way. Something like “make it more persuasive”, to see whether the rules hold under pressure. A rule that doesn’t hold gets turned into a program check, per the previous section, not another paragraph of explanation.

Where should the canonical copy of a skill live?

My rule is one canonical copy per skill, in a git repo, with every other location a symlink:

  • Personal skills: ~/ai-config/skills/<name>/, 15 of them right now.
  • Project skills: the canonical copy stays in that project’s repo, with one line in ~/ai-config/skills.manifest: name, GitHub repo, path inside the repo. Personal ones not meant for colleagues end with optional, so they are skipped when that repo isn’t cloned.

Why I insist on this: on October 12, 2026, while tidying skills, I found six project skills that existed only as real folders under ~/.claude/skills, with no version control and no backup. That day they moved into the project repo as the canonical copy, and the old location became a symlink. qn-monitor-cron was one of them.

One more thing to watch: project skills are read from .claude/skills/ by Claude Code and .agents/skills/ by Codex 12. Keep real copies in both folders of the same repo and they will drift apart. Keep one, and symlink the other or let the script below link it.

How does one skill serve both Claude Code and Codex?

~/ai-config/setup.sh does three things:

  1. Links every skill in skills/ and vendor/ into ~/.claude/skills (Claude Code) and ~/.agents/skills (Codex).
  2. Reads skills.manifest and links the project skills listed there into the same two places.
  3. Mirrors skills that exist on only one side (say, an installer put one into only one tool) to the other side, still with a single real copy.

If a same-named real folder (not a symlink) already exists, the script doesn’t overwrite it. It reports CONFLICT and leaves it for me to move after checking.

setup.sh --check only checks and changes nothing. I run it after installing or removing any skill, and the job is done when it says ok:

ReportMeaning
UNLINKEDThe canonical copy exists but isn't linked into one of the tools
MISSINGA repo in the manifest hasn't been cloned
ONLY-CLAUDE / ONLY-CODEXOnly one tool can see this skill
DIVERGEDSame name on both sides, pointing at two copies with different content
DUP-CODEXCodex's installer folder has another copy, so Codex sees two
DANGLINGA symlink points at a folder that no longer exists

DUP-CODEX exists because Codex doesn’t merge skills with the same name; both can show up in its selectors 2. Claude Code lets a personal skill win over a project skill of the same name 1. Either way, duplicate copies cause confusion, and the easy fix is never to have them.

Without the full setup, one folder under git plus two symlinks is enough; the commands are under “How I manage my own skills” in the post on finding skills.

Go deeper What Is an AI Harness? 7 Parts That Keep AI Agents Reliable (2026) Skills are one part: how rules, tests, MCP, memory, subagents and verification fit together.

A SKILL.md template to copy

Save this as ~/my-skills/<name>/SKILL.md and fill it in for your own procedure:

---
name: <name>
description: <One sentence: what it does>. Use when the user says "<phrase one>" or "<phrase two>". Not for <task it gets confused with>.
---

# <name>

Read-only, runs on its own. If you are not sure this skill applies, ask first.

## Read first
- <doc with known issues and current state>

## Steps (read-only)
1. <cheapest query, no extra login>
   - Reading it: <what is normal; what looks wrong but isn't>
2. <second-level query>
3. <query that needs a login or the machine; if the login expired, stop and ask the user>

## Only a human can answer
- <conclusion the data can't give>. Don't conclude before asking.

## The only write action (ask the user first)
- Run <lint / --dry-run / print the commands> and show the user.
- Execute only after the user agrees; remove temporary settings afterward.

## Done means
- <checkable data, not "looks fine">

## On failure
- <error message> → <what to do>; show any other error and retry at most once.

## Never
- <things it must not do>

FAQ

How is a skill different from a rule in AGENTS.md?

AGENTS.md and CLAUDE.md load in full every session; a skill loads only its name and description until a task matches 12. Rules every task follows go in the rules file; procedures for one kind of task go in a skill.

Can a skill include scripts?

Yes. Claude Code suggests keeping reference files and scripts in the skill folder and pointing to them from SKILL.md so they load or run only when needed 1; Codex skills can have scripts/, references/ and assets/ folders 2. Checks that need a definite answer (length, format) go in a script; judgment and order go in SKILL.md.

Why doesn’t the AI call my skill on its own?

Check the description first: does it include what users actually say, and is the main use in the first sentence? Then make sure the tool can see the skill at all: type /name in Claude Code, or $name or /skills in Codex. If it can’t be called directly, the location or symlink is wrong. Codex usually picks up changes on its own; if not, restart it 2.

Sources

  1. 1. Extend Claude with skills · Claude Code Docs · checked 2026-11-17
  2. 2. Build skills · OpenAI Codex Docs · checked 2026-11-17
  3. 3. Agent Skills Overview · Agent Skills · checked 2026-11-17

About the author

Kelvin Wang

Electrical engineer building tools with AI agents, sharing hands-on notes on engineering and investing.

More about me