Skill Style

Skill style

One bar: a line stays only when its removal would change what the agent does.

Two ways in

Routed while authoring

Someone is writing or editing a SKILL.md. Apply the rules below to that draft as it is written. Touch no other file, propose no audit of the rest of the catalog.

Invoked by name with targets

Audit the named skills, edit them in place, print a diff. Never commits, never pushes, never needs a clean tree.

$ARGUMENTS

• paths/globs — skill directories or SKILL.md files. Expand through git ls-files when tracked, else as literal paths.
• --audit — report the ledger and change nothing.
• --diff-only — show the edits without writing them.

Empty $ARGUMENTS with no draft in play: ask which skills via ask-user-choice. Never default to the whole repository.

The deletion test

Read the body one line at a time. For each, name the behavior that changes when it is gone:

• A command that would not run, or would run with wrong arguments.
• A constraint the agent would violate — an ordering, a destructive step, a thing it must never do.
• A trigger that would stop firing.
• An output whose shape or format would drift.
• A fork the agent would take the wrong branch of.

Name one and the line stays. Name none and the line goes. Adds context, reads better, rounds it out, and harmless are not names — they are the absence of one.

Run it on whole blocks too. A section whose every line survives individually still goes when the agent already does that by default; the test asks what breaks, not what is true.

Record a ledger before editing — one row per cut, naming the line and why nothing breaks. The ledger is the review surface, and it is what you show under --audit.

Lines the test never touches

The test judges claims. These are not claims:

• YAML frontmatter. Held to whether it routes, not to whether it changes behavior — the standard below, never the deletion test.
• Fenced code blocks, and every character inside them. Never reflow, reformat, shorten, modernize, or correct a command, path, flag, or snippet. Drop a whole fence only when a sibling fence teaches the same thing — never a line out of a fence's middle.
• Literal commands, paths, and flags in prose. Backtick them and leave them alone.
• Section headings. They are the navigation an agent skims.
• Warnings on destructive or irreversible steps. A cut here is paid for by someone else.

Where a fence and its prose say the same thing, the prose goes.

Sections

Bodies are sections, never a wall.

• One # title, then ## sections. A heading names the step or the decision, not the topic — never Context, Details, Notes, or Misc.
• Steps that must run in order are a numbered list. Otherwise ask whether the items reorder without changing meaning: siblings are bullets, an argument is prose.
• State the rule before its exceptions. Exceptions first leave the agent without the model they qualify.
• Prose runs at most three lines before a heading, a list, or a fence.
• One command per fence, console tag, $ prefix, comments outside it.
• A fence says when to run it and what its result means. Cutting prose that repeats a command is not the same as shipping the fence bare.
• Prefer nested sections over tables. A table earns its place only when the data is genuinely matrix-shaped.

Frontmatter and description

The description is the only text a host sees before deciding. Write it in third person, saying both what the skill does and when to reach for it, in the literal words a user would type.

• name — lowercase letters, numbers, hyphens; 64 characters or fewer. Gerunds and noun phrases both read well; helper, utils, and tools name nothing.
• description — 150 characters or fewer. Front-load the trigger. Never I can help you… or You can use this to….
• Set disable-model-invocation: true when the skill only makes sense asked for by name, so it stays out of the routing corpus.

Body budget

Keep the body under 500 lines. Past that — or for anything a task needs only sometimes — move the detail into a reference file and link it from the body. Keep every reference one level deep from the body: an agent that follows a link to a link reads the second one partially.

Steps

1. Load the rubric and the house voice. Read references/skill-rubric.md, then ./AGENTS.md and ./CLAUDE.md.

2. Fix the description before touching a line of the body.

3. Measure. Line counts locate the bloat:

   $ git ls-files '*SKILL.md' | xargs wc -l | sort -n
   

4. Run the deletion test and build the ledger.

5. Confirm, then edit. Show the ledger and confirm via ask-user-choice before writing. Skip under --audit or --diff-only.

6. Diff.

   $ git diff --stat -- <targets>
   

7. Test the trigger. Write three prompts a user would actually type and confirm the description answers each; write one that must belong to a different skill and confirm it does. A description that fails this is not done.

References

• references/skill-rubric.md — the full rule catalog, the anti-patterns, and the pre-ship checklist.
• references/example-bloated.md — a bloated skill with every defect named.
• references/example-ideal.md — the same skill, rewritten.

While trimming, do not add bloat

Replacements are concrete and shorter than what they replace. Never narrate the edit inside the file — no simplified, no previously, no note that a section used to be longer. The skill states its current instructions and nothing about how it got here.

Portability notes

• ask-user-choice — present the listed options and wait for the user to pick one. Hosts with a structured multiple-choice tool (Claude Code's AskUserQuestion) should use it; otherwise print a numbered list and wait for a numbered reply. Never proceed on an assumed answer.
• $ARGUMENTS — the text the user passed when invoking this skill. If your host does not substitute it, read it as the user's request in the current turn, and ask when there is none.
• Bundled files — every relative path in this skill points at a file shipped inside this skill directory. Read them from here, not from the host's plugin tree.