Include only what a capable model gets wrong without the skill. Write each item as the mistake, the correct action, and a short reason, in one to three lines. Delete anything the model already does reliably. Test this by asking what an agent would do without the line.
Put the critical rules at the top of the body as specific checks, not advice. "Run tsc --extendedDiagnostics before changing tsconfig" is followable. "Measure first" is not. Claude Code re-attaches only the first 5,000 tokens of an invoked skill after compaction.
A skill that changes code ends with the command that proves the change, and tells the agent to name each check it skipped. Without it, agents report done on unverified work.
Keep gotchas in the body. A reference may never be opened, so it holds only material for one sub-case, such as one language or one tool.
Give each reference a load condition in the body, such as "Read the Rust reference when the code is Rust", with a link to the file. A bare index of files does not get read.
Keep references one level deep and linked directly from SKILL.md. Agents may preview a file reached through another file with only its first lines. A reference over 100 lines starts with a ## Contents list of heading links.
Leave out routing tables that repeat headings, "when to use" sections in the body, persona text, completion-report boilerplate, emoji, and horizontal rules. The description already routes, and the rest carries no instruction.
Write in a calm imperative with the reason attached. Reserve capitals and "must" for real hard stops. Several model vendors report that shouted rules cause overtriggering and rigid behavior.
Do not state model names, prices, versions, or benchmark numbers without a source and date. They go stale and the agent repeats them as fact.
Move deterministic, fragile, or repetitive work into a script. A model recalling a number or rebuilding a parser each run is a bug. Do not wrap a tool that already does the job, such as gitleaks or benchstat.
Label host- and OS-specific parts, such as "Claude Code only" or "POSIX sh; Git Bash on Windows".
A risky step (deploy, publish, push, delete, registry or issue writes) names the action and its consequence and says to ask the user first. A step that sends data out names the data and the service, and the local alternative when one exists. Invoke Python scripts through python3, not the shebang, and say once that Windows uses py -3.
Name the skill as an explicit verb and object that says the job, such as write-justfile or bump-semver. Vague nouns such as helper, utils, or quality match everything and say nothing.
Split skills by job, not by language or tool. Near-identical skills side by side hurt selection, so variants of one job become references in one skill. Before adding a skill, search the catalog for its trigger words and extend the skill that owns the job. When two must coexist, give each a "Not for" clause naming the other.
Keep evals outside the installed skill directory, such as evals/<skill>/ at the repository root. Installers copy the whole skill directory, so evals inside it ship to every user.

Description

The description is the only text a host reads before choosing a skill.

Form: trigger words first (the tools, file names, and nouns users type), then "Use when" with phrasings that never name the skill, then "Not for" the nearest neighbor. Third person.
State when to use the skill, never its workflow. An agent that reads a summarized process follows the summary and skips the body.
Keep it within 300 characters, with the trigger words in the first 200. Claude Code cuts each listing entry at 300 characters, and hosts shorten descriptions from the end when the listing overflows.
Do not use when_to_use. Claude Code appends it to the description inside the same 300 characters, and Codex ignores it.
Plain words only. No colon, semicolon, double quote, backtick, slash, parenthesis, bracket, $, or |. Product names such as C++, C#, and .NET stay as written. An unquoted colon breaks YAML, and the rest reads as markup.

Read descriptions when a skill does not trigger, triggers on the wrong requests, or the catalog overflows its listing budget.

Workflow

Collect evidence: real prompts, the failures agents make without the skill, and primary documentation for the domain. Write eval_queries.json and evals.json in the eval directory first.
Draft the body in this order: one or two sentences of purpose, ## Rules, ## Workflow only when the order of steps matters, ## Scripts with each script's usage, and the reference load conditions. Start from assets/SKILL.template.md. Aim for about 120 lines.
Write each script with --help, exit 0 clean, 1 findings, 2 usage error, one finding per line, and a test next to it. Use .py with the standard library or .mjs run by bun; use .sh only for a POSIX-only task, labeled.
Write the description last, from the evals.
For Codex, write agents/openai.yaml with display_name, short_description of 25 to 64 characters, and a default_prompt containing $<skill-name>. Read host metadata for invocation policy, Claude Code frontmatter extensions, and install paths.
Validate: skills-ref validate <dir> if installed (else report it skipped), then python3 scripts/check_reference_structure.py <dir>, then the repository's own checks.
Paired evals are paid runs that send prompts and fixtures to the model API; ask before running them, else say that no trials ran. Static checks do not show that a skill changes behavior. Read evaluation before writing evals or when a revision did not help.

To audit an existing skill, cut first: delete every line the model would follow anyway, then merge overlapping skills, then fix the description. Read the audit checklist.

Scripts

python3 scripts/check_reference_structure.py SKILL_DIR... checks that every reference is linked from SKILL.md, long references have a linked ## Contents, relative links and anchors resolve, and the name and description are valid. Exit 0 clean, 1 problems, 2 bad input.

write-agent-skill

Write Agent Skill

Rules