# Skill Style > Use when writing, auditing, or trimming a SKILL.md, especially for bloated bodies, weak descriptions, or plugin-wide sweeps. - Skill: `tony/skill-style-2` (Agent Skill) - Install (CLI): `npx skillmds@latest add tony/skill-style-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/tony/skill-style-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tony (https://skillmd.com/u/tony) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tony/skill-style-2 --- # 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 `AskUserQuestion`. 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: ```console $ 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 `AskUserQuestion` before writing. Skip under `--audit` or `--diff-only`. 6. **Diff.** ```console $ git diff --stat -- ``` 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.