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
- 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.
- A description says what the skill does, what the user actually says, and what it is not for, with the main use first.
- 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.
- 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.
| Where | What belongs there | Example |
|---|---|---|
| AGENTS.md / CLAUDE.md | Short rules every task needs | The test command; ask before pushing |
| skill | Occasional multi-step procedures with an order and judgment calls | Social post draft pipeline; scheduler health check |
| script, test, hook | Rules that must always hold and a program can check | Length 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:
| Item | Claude Code | Codex |
|---|---|---|
| Required fields | All optional; description recommended | name, description |
| Stop the AI calling it on its own | disable-model-invocation: true | allow_implicit_invocation: false in agents/openai.yaml |
| Description length | description plus when_to_use is cut at 1,536 characters in the listing | the whole skill list defaults to 2% of the context window |
| Body length | keep SKILL.md under 500 lines; move detail into side files | keep each skill to one job |
| Symlinks | Supported | Follows 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:
- 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_useat 1,536 characters. - The words the user really says.
kw-studio-new-postlists the phrases I use, such as “make it a thread”, “post draft”, “revise the draft”.qn-monitor-cronlists “did the cron run”, “reconciliation status”, “is the monitor schedule OK”, plus one trigger no person says: when the alert fires. - What it is not for. The last sentence of
kw-studio-new-postrules 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:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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:
lintchecks 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.submit --dry-runprints exactly what would be sent, and sends nothing.submitchecks 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-runorlintsubcommand 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.
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-postgets a fresh agent that follows it from scratch, all the way to a passingsubmit --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 withoptional, 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:
- Links every skill in
skills/andvendor/into~/.claude/skills(Claude Code) and~/.agents/skills(Codex). - Reads
skills.manifestand links the project skills listed there into the same two places. - 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:
| Report | Meaning |
|---|---|
UNLINKED | The canonical copy exists but isn't linked into one of the tools |
MISSING | A repo in the manifest hasn't been cloned |
ONLY-CLAUDE / ONLY-CODEX | Only one tool can see this skill |
DIVERGED | Same name on both sides, pointing at two copies with different content |
DUP-CODEX | Codex's installer folder has another copy, so Codex sees two |
DANGLING | A 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
Kelvin Wang
Electrical engineer building tools with AI agents, sharing hands-on notes on engineering and investing.
More about me