writing-skills

How it is organised

What’s inside

The skill’s top-level sections, in order. The bar is each section’s share of the 1,792 words, so you can see where the weight sits before reading.

1. 11. Decide whether it should be a skill151 words
2. 22. Start from real uses64 words
3. 33. Write the description251 words
4. 44. Write the body513 words
5. 55. Test it318 words
6. 66. Editing an existing skill110 words
7. 77. Diagnosing a misbehaving skill125 words
8. 8Before you ship94 words

The skill itself

Read it before you install it

---
name: writing-skills
description: Write, edit or review an agent skill (a SKILL.md file) so it triggers when it should and changes what the agent does. Covers deciding whether guidance belongs in a skill at all, the description, the body, testing against a no-skill baseline, tuning triggers, and editing an existing skill safely. Use when the user says "write a skill", "make this a skill", "turn this workflow into a SKILL.md", "my skill never triggers", "improve or review this skill", or asks how to word a skill description. Not for project instruction files, one-off prompts, or performing the task a skill describes.
license: MIT
---

# Writing skills

A skill is a folder with a `SKILL.md` (a `name`, a `description`, a body) and optional supporting files. The host keeps every skill's name and description in view and reads the body only after it decides the skill applies. So the description decides whether the skill is used, the body decides whether it works, and every line of both costs context on every run.

**How far to trust this advice.** It is distilled from public skill-writing guides. Most of it is the authors' experience, not published measurements. Where a rule rests on one anecdote, or on a claim about how one host behaves, it is marked "reported". Treat those as defaults and test your own skill (section 5).

## 1. Decide whether it should be a skill

| The guidance is | It belongs in |
|---|---|
| A method, check or body of knowledge the agent lacks by default, reused across tasks or projects | a skill |
| True only in one repository (paths, branch rules, ticket prefixes, CI job names) | that project's instruction file |
| Needed on every turn | standing instructions, not something that must be triggered |
| A rule that must hold even if the agent ignores it, or that a tool can check | a validator, script, hook or test |
| A one-off task, or the story of how you solved something once | nothing durable |

Portability test: does the text stay true in another repository? Concrete paths, names and prefixes say no.

If a capable agent already does the job correctly without the guidance, there is nothing to write. Section 5 shows how to find out.

## 2. Start from real uses

Collect a handful of requests people would actually type that should trigger the skill, and a few near-misses that share its words but should not. If the conversation already contains the workflow ("turn this into a skill"), mine it first: the steps taken, the corrections the user made, the formats seen. Ask the user only about the gaps, a few questions at a time.

## 3. Write the description

The description is the main trigger. Rules:

- Third person, at most 1,024 characters. It says what the skill does and when to use it.
- Name the outcome in a clause, not the procedure. A description that lists the skill's steps can stand in for the body: the agent reads the summary, feels it has the rule, and never opens the file. Reported: one anecdote in one guide, repeated by copies and one other guide, no data. Cheap to avoid, so avoid it.
- Include the words a person would type, and the situation as well as the task ("a test fails", "the build is red"). Three guides report under-triggering as the common failure. Give each distinct trigger once; stacking synonyms for one branch only spends context.
- Add a "not for" clause where a neighbouring skill or task invites confusion.
- Lead with the main case. Hosts may shorten long descriptions or cap the total listing (reported, by two guides, for one host), and the tail is what gets cut.
- "When to use" belongs here, not in the body. The body is not read until the skill is chosen.

Weak: `Helps with release notes.`
Narrates steps: `Lists merged pull requests, groups them by label, then writes a paragraph per group.`
Better: `Draft release notes from merged changes, grouped by user-visible impact. Use when the user says "write release notes", "what changed since the last tag" or "summarize this release". Not for per-commit changelogs or deciding what to ship.`

## 4. Write the body

- **Add only what the agent lacks.** Assume it is capable. For each sentence ask whether the agent would do the right thing without it; delete the whole sentence if so, rather than trimming words.
- **Match specificity to fragility.** Principles and heuristics where many approaches work. Exact steps or a bundled script where the task is error-prone or order matters.
- **Explain why.** A reason lets the agent handle cases the rule did not foresee. Capital-letter MUST and NEVER are a flag that the reason is missing; keep emphasis for real hard limits.
- **Choose the form by the failure you saw.** The agent breaks a rule it knows, under pressure: state the rule, forbid the specific workarounds, and add a table of excuses with their rebuttals plus a short list of red flags. The output has the wrong shape: describe what the output is, its parts in order, instead of listing prohibitions (reported: prohibitions on shape get negotiated away). A required element is missing: put a required slot for it in the template. Behavior depends on a condition: write the condition on something observable. Whichever form you pick, state what to do, and pair any prohibition with the alternative.
- **End each step with a checkable completion criterion**, such as "every changed file is accounted for", so the agent can tell done from nearly done. If a sharper criterion does not stop the agent rushing a step, move the later steps into a separate file or skill so they are out of view.
- **Say each thing once.** Duplicated rules drift apart. When editing, remove contradictions; do not stack an override on an obsolete rule.
- **Examples.** Make examples complete and realistic. One or two usually suffice; add more only when testing shows the agent generalizing wrongly, and make them differ from each other. Sources disagree on how many, so this is unsettled.
- **Length.** The published Agent Skills specification recommends keeping the body under about 500 lines (fewer than about 5,000 tokens). Move long reference material to separate files, link each by plain relative path (not syntax that loads the file automatically) with a line saying when to read it, and keep links one level deep.
- **Scripts.** Bundle one when every run would otherwise rewrite the same code, and run it before shipping. Name the interpreter in the instructions (`bash scripts/check.sh`), since packaging may drop the executable bit (reported).
- **Self-contained.** Depend on no other skill, unshipped file, plugin prefix or one host's tool names. Say "the user" and "the agent". Leave out README, changelog and setup notes.
- **No numbers without a basis.** A statistic, timing or success rate needs a source or a measurement you can state. Otherwise state the qualitative point or drop it.
- **Safe by default.** A skill must not surprise the user: no hidden actions, no exfiltration, no skipping confirmation for irreversible steps. Anything destructive (deleting, overwriting, force-pushing, publishing) happens only on the user's explicit request, and the skill says so. Never write "delete it and start over" about work the user owns.

## 5. Test it

A validator shows a skill is well-formed; only a run shows it changes behavior.

1. **Baseline.** Give a fresh agent, with no access to the skill, a realistic task that tempts the failure. Record what it does and the reasons it gives, verbatim. If it already behaves well, stop: there is no skill to write.
2. **Write the smallest guidance** aimed at what you saw, not at hypothetical cases.
3. **Rerun the same task with the skill.** Run each variant more than once; one sample misleads. Widely differing results mean the wording does not yet bind.
4. **Close what leaks.** For a discipline skill, combine pressures in the scenario (a deadline, hours of sunk work, a senior saying skip it, fatigue), give concrete options and a forced choice, and ask "what do you do?". Each new excuse gets a row in the table and a line in the red flags. Test a technique on a new case; test a reference by whether the right entry is found and used.
5. **Test the triggers.** Write realistic prompts, some that should trigger the skill and some near-misses that should not. Tune the description on part of them and check it on the rest, so you do not fit it to the prompts you tuned on. A trivial one-step request may not trigger any skill; use substantive prompts (reported, one guide).
6. **Read transcripts, not only outputs.** If the skill makes the agent waste effort, cut that part. If every run rewrites the same helper, bundle it. Generalize from the feedback instead of patching for the specific examples.

For style and taste skills, have the user read the outputs.

**Report only what you ran.** Reading a skill through is not a test, and imagining a scenario is not running it. If you cannot start a fresh agent, say the skill is untested and offer the user the baseline task to run.

## 6. Editing an existing skill

- Read it, and whatever calls or names it, before changing anything.
- Keep a copy of the current version first. It is your baseline and your way back. Do not delete or overwrite the user's version without asking.
- Keep the name and folder unless the user asks to rename; a rename breaks everything that refers to it.
- Re-run the baseline on the part you changed. Guidance written for weaker models may no longer be needed, so after a model change test whether removing lines helps before adding any (reported, one guide).
- Installing, publishing or changing global configuration is a separate step that needs the user's say.

## 7. Diagnosing a misbehaving skill

| Symptom | Likely cause |
|---|---|
| Never fires | Description lacks the user's own words, is abstract, or buries the main case |
| Fires on the wrong tasks | Terms too broad; no "not for" clause |
| Fires, but the body is skipped | Description narrates the procedure |
| A step is rushed | Vague completion criterion |
| A known rule is dropped under pressure | Soft wording, no reason, no rebuttal for the excuse |
| Output has the wrong shape | Prohibitions where a recipe is needed |
| Long, partly ignored | Dead lines the agent obeys anyway; reference material that belongs in a separate file |
| Rules disagree | Layers of edits; consolidate |

## Before you ship

- [ ] `name` equals the folder: lowercase letters, digits and single hyphens, at most 64 characters, no leading or trailing hyphen.
- [ ] `description` is at most 1,024 characters and has what, when, the typed phrases and a "not for".
- [ ] No link, skill or file is referenced that is not in the folder.
- [ ] Every number and claim has a stated basis or is gone.
- [ ] Destructive steps run only on the user's explicit request.
- [ ] Tested against a baseline, or marked untested.

The second audit

What we found in the sources

It combines three lines of source that all teach authoring a SKILL.md: the test-against-a-baseline method (obra/superpowers and its forks), the concise-body and progressive-disclosure guide (the skill-creator text in langfuse/skills and netlify/context-and-tools), and the pruning and failure-mode reference (rengwu/wayfinder-maps). Most advice in these sources rests on the authors' experience, and the rewrite marks that advice as reported. Every source below was read at the commit the auditor recorded. Nothing was taken from a source without a permissive license.

What each source contributed

• obra/superpowers ↗ · Primary basis · MIT

  The method of testing a skill by first running a fresh agent without it and recording what it does and the reasons it gives, writing the smallest guidance aimed at that, and rerunning; stopping if the agent already behaves; combined-pressure scenarios for rules the agent breaks under pressure; an excuse table and red-flag list; the table that matches the form of the guidance to the failure (rule broken under pressure, wrong output shape, omitted element, condition-dependent behavior); the advice that a description should not narrate the procedure; the create-or-not test (not for one-offs, project conventions or what a tool can enforce); the rule against narrative examples; and not using link syntax that loads a file automatically.

• langfuse/skills ↗ · Primary basis · MIT

  The body-writing guidance from the Anthropic-style skill-creator text: be concise and add only what the agent lacks, match specificity to how fragile the task is, three-level loading (name and description, body, supporting files), keep references one level deep and say when to read each, bundle a script when the same code would be rewritten each time and run it, keep stray documentation out of the folder, and put the when-to-use information in the description because the body is not read before the skill is chosen. Start from concrete examples of use.

• netlify/context-and-tools ↗ · Added ideas · MIT

  From the longer, evaluation-oriented version of the same skill-creator: mine the current conversation when asked to turn a workflow into a skill, the tendency of descriptions to under-trigger, a with-skill versus without-skill comparison (or against a snapshot of the old version when editing), trigger tests made of realistic prompts including near-misses, tuning on part of the prompts and checking on held-out ones, explaining why instead of using capital-letter commands, generalizing from feedback instead of patching for the test examples, reading transcripts and bundling a helper that every run rewrites, the "lack of surprise" principle, subjective skills judged by a person, keeping the name when updating, and copying before editing.

• rengwu/wayfinder-maps ↗ · Added ideas · MIT

  From writing-great-skills: describe each distinct trigger once, give each step a checkable completion criterion, sharpen the criterion before splitting a sequence, say each thing once, delete whole no-op sentences, and the failure modes (premature completion, duplication, sediment, sprawl, no-op, negation), which informed the body rules and the diagnosis table. Its coined vocabulary and the invocation-mode mechanics were left out.

• vadimvitvickiy/vv-agent-kit ↗ · Added ideas · MIT

  The table that decides whether guidance belongs in a skill, an instruction file, a hook or a validator (its agent row was left out) and the portability test (does the text stay true in another repository), every claim needs a basis you can state, name the interpreter when telling the agent to run a bundled script, test behavior and not only structure, and lead the description with the main case. Its listing-budget figures are mentioned only as reported.

• lsy041015/orchestra ↗ · Added ideas · MIT

  Do not invent a rule for a problem the baseline did not show, do not claim a scenario was run when it was only read or imagined, distinguish static inspection from behavioral evidence, read the existing skill and whatever calls it before changing it, remove contradictions instead of appending an override, and treat installing or publishing as a separate user-authorized step.

• jdforsythe/forge ↗ · Added ideas · MIT

  That a description should use the words people actually type, including situation phrasing, and say what it is not for; that guidance written for older models may be unnecessary on current ones, so removals deserve testing (used in the editing section, marked as reported); and its practice of saying which numbers are design choices and not measurements, which the rewrite follows by marking advice as reported. Its vocabulary-payload and watchlist machinery was left out.

What changed

• The description says what the skill does and when to use it, lists the phrases a person would type, and adds a "not for" clause. The shared obra text says a description should state only when to use the skill and never what it does; the Agent Skills specification page (read during this refactor through a fetch tool that summarizes pages) says it should describe both. The rewrite names the outcome in a clause and keeps the procedure out, which satisfies both.
• "Write skill before testing? Delete it. Start over. Delete means delete" became "keep a copy of the current version; do not delete or overwrite the user's version without asking". Taken literally the original destroys the user's own edits.
• Rewritten as one self-contained file. The TDD mapping, the dependence on a separate test-driven-development skill, the sibling files, the packaging and evaluation scripts, host directory paths and plugin prefixes were removed.
• The Graphviz flowcharts, custom XML-style tags and good-or-bad markup became tables, lists and plain labels.
• Numeric targets that the sources give without a basis (word counts per skill type, 3 to 5 examples, 5 or more repetitions, 20 trigger queries, a 60/40 split, 3 runs per query, 5 iterations, 15 to 30 vocabulary terms) were replaced with qualitative statements. The kept figures are the 1,024-character description limit, the 64-character name limit, and the roughly 500-line, roughly 5,000-token body recommendation, which the Agent Skills specification page states.
• Advice that rests on one anecdote, or on a claim about one host's behavior, is marked "reported" in the skill. A short paragraph near the top tells the reader how far to trust the advice.
• Added by the rewriter, from reading across the sources: a symptom-to-cause diagnosis table; "never write 'delete it and start over' about work the user owns"; and "destructive steps happen only on the user's explicit request" in the checklist.

Problems found in the sources

• !obra/superpowers: Depends on files that are not in the download: codex-tools.md and gemini-tools.md (under ../using-superpowers), anthropic-best-practices.md, testing-skills-with-subagents.md, persuasion-principles.md, graphviz-conventions.dot and render-graphs.js; it uses the superpowers: prefix, a Graphviz block and <Good>/<Bad> tags, and tells the reader to create a todo for each checklist item. It gives "50-100x context savings", "15 min testing saves hours" and "200k+ context" (for @ links) with no basis, and says wording tests produced "fully separated distributions" without giving data. The claim that a workflow-summarizing description makes the agent skip the body rests on one anecdote of a review that ran once instead of twice. "Write skill before testing? Delete it" applies to edits of existing skills as well, so followed literally it deletes a user's work. Its rule that a description states only when to use the skill differs from the Agent Skills specification page, which says the description should say what the skill does and when to use it.
• !langfuse/skills: The frontmatter says license: Complete terms in LICENSE.txt, but no LICENSE.txt is in the downloaded file, and the identical bytes are labeled MIT in this repository and Apache-2.0 in neondatabase/postgres-skills, so the original license of the text is unclear from these files. It tells the author to run init_skill.py and package_skill.py and to read references/workflows.md and references/output-patterns.md, none of which are in the download. It says only name and description are read and "Do not include any other fields in YAML frontmatter" while the same file describes license, metadata and compatibility as optional fields and uses license itself.
• !netlify/context-and-tools: Relies on files and tools that are not in the download (eval-viewer/generate_review.py, agents/grader.md, agents/comparator.md, agents/analyzer.md, references/schemas.md, assets/eval_review.html, scripts for benchmarking, the description loop and packaging) and on specific hosts (Claude.ai, Cowork, Claude Code, a claude -p command, a present_files tool). Its numbers (20 queries, a 60/40 split, 3 runs per query, 5 iterations) are procedure settings with no stated basis. It warns that capital-letter ALWAYS or NEVER is a yellow flag, yet uses "ALWAYS use this exact template" in an example and "GENERATE THE EVAL VIEWER *BEFORE*..." in capitals later. It states that the agent only consults skills for tasks it cannot easily handle itself without giving a basis. It also contains an aside about creating "billions a year in economic value" that bears on nothing the skill asks.
• !rengwu/wayfinder-maps: Defers the meaning of its bold coined terms to GLOSSARY.md, which is not in the download, so a lone copy cannot be fully understood. The frontmatter sets disable-model-invocation, so the skill is meant to be typed by hand. Its "Negation" rule (prohibitions backfire; state the positive) differs from obra/superpowers, which scopes prohibitions to rules the agent breaks under pressure; which is right for a given case is unclear. The leading-words advice is the author's claim, with no test given.
• !vadimvitvickiy/vv-agent-kit: Written for one plugin: it refers to references/frontmatter.md, hooks/using-vvkit.md, ./scripts/validate.sh, claude plugin validate and a vvkit: prefix, none of which are in the download. It states a listing budget of about 1% of the context window and that about the first 5,000 tokens of a skill are kept after compaction, with no source in the file. Its example "200 owners produced 209 initialisations and 201 distinct objects" is given without context.
• !lsy041015/orchestra: Tied to its own edition: it uses the orchestra: prefix, points to anthropic-best-practices.md (not in the download), and forbids creating evaluator or analyst agents, so its baseline step is written around that restriction.
• !jdforsythe/forge: Points to references/skill-principles.md and skill-template.md (not in the download) and to its own Mission Planner, Agent Creator and library index. It states platform facts (a 1,536-character truncation, a listing budget of about 1% of the context window, about 5K tokens kept after compaction, and that a reasoning-echo instruction can trigger a refusal on a named model) with no source in the file. It does state that its numeric ranges are design standards and not measured thresholds.
• !gzupark/claude-plugin-pack: A condensed fork of the langfuse skill-creator text that adds an Evolution Score with a recommended threshold of 7+, a 6-lens framework and regression-questioning rounds (stop after 3 empty rounds or 7 rounds), none with a stated basis. It also adds a run.sh wrapper and references (analysis-lenses.md, regression-questioning.md and others) that are not in the download.
• !gylove1994/superpowers-deepseek-v4: An older-looking variant of the obra text (about 89% similar by word comparison) without its "Match the Form to the Failure" and micro-test sections. It adds an instruction to invoke a confirming-worktree-before-edit skill that is not part of this skill, renames the prefix to superpowers-deepseek-v4:, and links two files with @ while the same text says @ links force-load files and should not be used.
• !miroo93/dev-workflows: The same older-looking variant of the obra text (about 89% similar by word comparison), vendored with an attribution comment that says its cross-references resolve only when the superpowers plugin is installed. It also uses @ links in the sections that say not to.
• !thepragmaticbear/bearpaws: Recasts a condensed obra text in a custom XML tag set with a closed whitelist, which most hosts will not render as structure, and uses a bp: prefix. It says agents treat an include tag as advisory (a finding it labels Phase 1) without giving the evidence.

What was dropped

• The TDD-for-documentation framing, the iron law, and the persuasion-principles citations (Cialdini 2021, Meincke et al. 2025) whose supporting file is not in the download, from obra/superpowers.
• The "50-100x context savings" and "15 min testing saves hours" statements from obra/superpowers, which have no stated basis.
• The Graphviz conventions, the render script, the discovery-workflow section and the skill-types taxonomy from obra/superpowers.
• Packaging into a .skill archive, init and package scripts, the evaluation viewer, benchmark aggregation, the description-optimization loop and the Claude.ai and Cowork instructions from netlify/context-and-tools and langfuse/skills, because their scripts and helper files are not in the download.
• The coined vocabulary (context load, cognitive load, leading words and the rest), the invocation-mode mechanics, and the suggestion to replace restatements with single pretrained words, from rengwu/wayfinder-maps. The glossary it defers to is not in the download and the sources give no test of the leading-words idea.
• Plugin-specific parts of vv-agent-kit (its validators, version bump, skill namespaces and hook file), the worker restrictions of lsy041015/orchestra, and the library index and usage log of jdforsythe/forge.
• The Evolution Score, the 6-lens framework and the regression-questioning rounds in gzupark/claude-plugin-pack, which come with invented thresholds.

Same text, wherever you work

Use it where you work

git clone https://github.com/nikbearbrown/skills
cp -R skills/skills/writing-skills ~/.claude/skills/