| name | writing-skills |
| description | Authors, structures, and audits Claude agent skills (SKILL.md + scripts/references/assets) to Anthropic best-practices, the agentskills.io spec, and local Claude Code conventions. Use when creating a new skill, refactoring one for progressive disclosure, or auditing a skill's metadata/structure. Do not use for README/user docs, non-agentic library code, or MCP-server implementation — for a runbook-style domain skill, model it on a sibling under `.claude/skills/`. |
| allowed-tools | Read, Write, Edit, Bash |
Writing Skills
Build a skill a zero-context mid-level engineer or Sonnet-class model can load and execute correctly on the first try. Discoverable metadata, lean body, deterministic scripts. Ground truth only: verify every path/command against disk before writing it — a wrong runbook is worse than none.
Before you scaffold
Write a skill when the same instructions get pasted into chat repeatedly, or a CLAUDE.md section has grown into a procedure rather than a fact — a skill's body loads only when triggered, so it costs nothing until used. Don't write one for a single unrepeated task, or to store a fact with no procedure attached (that's a references/ note inside an existing skill, or CLAUDE.md itself, not a new skill).
Variables — instantiate before writing
| var | fill with | constraint |
|---|
<name> | the skill id | ^[a-z0-9]+(-[a-z0-9]+)*$, ≤64, == its directory basename, no anthropic/claude |
<desc> | the trigger sentence | 3rd person, ≤1024, what + "Use when …" + "Do not use for …" |
<dir> | .claude/skills/<name> (project) or ~/.claude/skills/<name> (personal) | the two discovery roots |
<freedom> | low | medium | high per step | fragile/safety → low · preferred-pattern → medium · open-ended → high |
<body_max> | 500 | hard line ceiling for SKILL.md |
<ref_depth> | 1 | references stay this many hops from SKILL.md |
<folders> | scripts references assets | the only subdirs, each one level deep |
Loading model — earn every token
| level | loaded | budget | holds |
|---|
| 1 metadata | always | ~100 tok/skill | <name>+<desc>, the trigger |
| 2 body | on trigger | <<body_max> lines | workflow + the few rules a smart model can't infer |
3 <folders> | on read/run | ~∞ (scripts: only stdout costs tokens) | schemas, long docs, deterministic tools |
Bulk lives in Level 3; SKILL.md is its table of contents. Full model + surface differences: references/architecture.md.
Procedure
- [ ] 1. <name>+<desc> pass validate_metadata.py
- [ ] 2. <dir>/<folders> scaffolded, name==dir
- [ ] 3. body written: imperative, <ref_depth>-deep refs, <<body_max> lines
- [ ] 4. every fragile step → a scripts/ CLI (args in, stdout/stderr out)
- [ ] 5. every references/checklist.md item passes
1 · Metadata — the highest-leverage field. <desc> is how a model picks this skill from 100+. State what it does, the concrete trigger phrases a user would say, and the negative trigger + which sibling to use instead. Gate it:
python3 scripts/validate_metadata.py --name "<name>" --description "<desc>" --dir "<dir>"
→ SUCCESS proceeds; any NAME/DESC/STYLE/DIR/DISCOVERY line → fix that field only, re-run. Discovery patterns + worked examples: references/best-practices.md §Discovery. Restricting tools? add allowed-tools: (e.g. Read, Write, Bash(git status:*)).
2 · Scaffold. <dir>/{<folders>}, each one level deep. No README/INSTALLATION/CHANGELOG inside a skill — those are the tell of a human doc masquerading as one.
3 · Body. Start from assets/SKILL.template.md. Third-person imperative. Pick <freedom> per step: low → exact command + "do not modify"; medium → parameterized script; high → goal only, trust the model. Over <body_max> lines, or carrying a large schema? Move it to references/ and command the read at point of need ("Read references/api.md to pick the endpoint"), never deeper than <ref_depth> — a nested reference gets head-previewed and half-read. Picking a workflow shape (sequential steps, MCP-tool coordination, iterative refinement, decision-tree tool selection, embedded domain expertise): references/patterns.md.
4 · Scripts. One fragile task (regex, parsing, multi-step, safety-critical) per CLI. Takes args. Solves, never punts — handle the error in the script, don't fail to Claude. No magic constants. Specific stdout on success, specific stderr on failure so the agent self-corrects. State intent in the body: "Run x.py" (execute) vs "See x.py for the algorithm" (read).
5 · Audit. Every item in references/checklist.md. Quality-critical skill? Evaluation-first: run the task with no skill, capture the exact failure, then write only enough to close it — never pad docs against imagined needs. Three-tier test framework (triggering / functional / performance-comparison) and the under/over-triggering fix table: references/evaluation.md.
Claude Code frontmatter/runtime beyond the basics (context: fork, dynamic !command injection, string substitutions, skill stacking, nested/monorepo discovery, skillOverrides): references/claude-code-extensions.md.
When NOT to use
Not for README/user docs, library code, or MCP-server code. For a domain runbook, don't start from scratch — copy the closest sibling skill's shape.
Bootstrapping a whole library
Different job from the rest of this skill: an existing project has no skill library yet, and the ask is the whole set (10+ skills), not one. Discover-then-parallel-author-then-adversarial-review workflow: references/bootstrap-library.md.
Provenance and maintenance
Re-verify when the environment drifts:
- discovery roots:
ls -d ~/.claude/skills <project>/.claude/skills 2>/dev/null
- validator still green on this skill:
python3 scripts/validate_metadata.py --file SKILL.md --dir "$(pwd)"
- rule sources, distilled into
references/ (never cited live from the gitignored staging dir they arrived in) — re-distill if these change, and re-check the live doc first since Anthropic's guides are versioned and this is a point-in-time snapshot:
references/best-practices.md, references/architecture.md, references/checklist.md, the "Before you scaffold" heuristic above: Anthropic's Agent Skills overview + authoring best practices, and the agentskills.io skill-creator spec, absorbed as of 2026-07-09.references/claude-code-extensions.md: Anthropic's Extend Claude with skills doc, absorbed 2026-07-10.references/evaluation.md: the testing chapter of a third-party PDF skill-authoring guide (unknown author/license — ideas only, no text retained verbatim) plus Anthropic's evaluation-driven-development section, absorbed 2026-07-10.references/bootstrap-library.md: a one-shot "bootstrap a whole skill library" mega-prompt found alongside the PDF (unknown author/license — same idea-only treatment), absorbed 2026-07-10.references/patterns.md: the "Patterns and troubleshooting" chapter of the same third-party PDF (idea-only, same treatment), absorbed 2026-07-10.
- This distillation is a snapshot, not a live mirror. For anything not covered here, or to confirm a rule still holds, read the source directly rather than assuming this file caught everything: Agent Skills overview · authoring best practices · Extend Claude with skills · agentskills.io.
