A skill is an index, not a manual. It teaches the agent to do things your way, consistently.

Description + body

A description (in the third person: "creates invoices and sends reminders") is what the agent reads to decide whether to use the skill. The body puts the most important rules at the top, followed by the steps and links to the rest. Keep it short: include only what the model can’t infer on its own.

Details on demand

Pricing, terms, formats, input and output examples: one file per topic, each linked directly from SKILL.md. Long files start with a table of contents, so even a partial read shows everything they cover.

What must not vary

Where a mistake costs money, deletes data, or publishes something, make the step an exact script. Where a rule must apply on every run, move it out of the text and make it a hook, which Claude Code runs automatically, whether or not the skill is followed.

Keep SKILL.md short and one level deep

Keep the body under 500 lines; put the rest in files linked directly from SKILL.md. A file reachable only through another file may be previewed (the first few lines only), and the rules further down get missed.

Put a table of contents at the top of long files

References over 100 lines start with a list of what they contain. That way, even if the agent reads only the beginning, it knows that "discounts" are at the end and can go there.

Set the level of freedom based on risk

High: simple instruction (brainstorming). Medium: model with room for variation (weekly report). Low: exact script (invoice, tax, migration). A skill combines all three; ask: "What if the agent does this step differently?"

Test on every model you’ll use

Haiku: does the skill provide enough guidance? Sonnet: is it clear and concise? Opus and Fable: does it avoid overexplaining? Test the skills you rely on; testing the rest isn’t worth the cost.

Only include what the model doesn’t know

Context is a public good. Don’t explain what an invoice is; keep your prices, terms, and internal rules. Write the description in the third person, using the words people type.

Use a checklist with a "go back" line

For a multi-step task, give the agent a list to copy into its response and check off, with a "done when…" for each step and a line like "if the total doesn’t match, go back to step 2".

Verification loop

Run it, fix what failed, and repeat until it passes. The check doesn’t have to be code: comparing the draft with the style guide and listing each deviation works just as well. For long tasks, a verifier with a clean context beats self-critique.

Patterns for defined outputs

Use a template that states how strict it is; include two or three input and output pairs when style matters; use a conditional flow when there’s a branch. One standard and one fallback, never a menu of five options.

Make it shareable

Don’t assume your colleague has the library installed: list the exact packages and the installation command next to the script that needs them. The Claude API doesn’t install anything.

Turn rules that must never break into hooks

"Never send an invoice over R$ 50 mil without approval" in all caps is followed almost every time. A hook is followed every time: declared in the skill’s frontmatter, it runs before every command and stays active for the rest of the session.

Test before deleting

Step-by-step explanations of what the model already knows, long lists of behaviors, and repeated common sense are often dead weight. Only a run with the line and one without it can prove this.

Ask for the answer

Instructions to “write out the reasoning step by step” may be refused by models 5.5. Ask for the answer, a brief explanation, or a summary of the actions.

A rule with a why

“Under 1,536 characters, because Claude Code truncates the listing there” lets the model handle a case the rule didn’t anticipate and tells the next editor when the rule no longer matters.

Use all caps only for hard rules

“Start with the result, then the details” works as well as listing every unwanted behavior. When everything is shouting, nothing stands out.

Say how and when to check

For long-running or risky tasks, a subagent that didn’t do the work checks it against the specification. It’s the same method used in the Long-Running Execution area.

A folder in ~/.claude/skills

git clone https://github.com/inematds/auditar-skills && cp -r auditar-skills/skill-creator-plus ~/.claude/skills/

In Codex, the same folder in ~/.agents/skills. On claude.ai, zip SKILL.md, references/, and scripts/.

All skills at once

python3 ~/.claude/skills/skill-creator-plus/scripts/validate_skill.py --all ~/.claude/skills

One table per skill: errors, warnings, and violated rules (FM, DS, ST, CT, WF, SC, NM, HK, TS, LB). --json to process.

AUDIT · NEW · REFINE

“Audit my deployment skill” produces the report, with failures first, including file and line. “Turn this into a skill” writes three test prompts before creating the folder. “The skill forgets the date filter; fix it” rewrites the rule around the reason, usually making it shorter.

skill-creator (Claude Code)

Included with Claude Code: creates, measures, and optimizes a skill’s description, with evaluations and variant comparisons. It’s the starting point; /skill-doctor points out unused skills.

writing-skills (Superpowers)

The Superpowers kit skill for writing and testing skills with documentation TDD: baseline without a skill, pressure scenario, then the skill. Covered in INEMA’s Superpowers course.

Skills For Real Engineers (Matt Pocock)

The names for the failure modes (no-op, duplication, sediment, dispersion, premature completion) come from here. INEMA course below.