A skill is read by agents on every load; trim it to the minimum that still drives the procedure correctly.
When to use
- "make skill improvement, keep succinct - agents use it not humans", "refine the skill concisely"
- A SKILL.md body is wordy, repeats itself, or carries rationale that belongs in a changelog.
Not for: writing a brand-new skill (use the skill template), or changing what the skill does.
Steps
- Read the target
SKILL.md. Note its required procedure and trigger phrases (do not lose these). - Cut: filler sentences, restated context, motivation/rationale prose, duplicated lines.
- Keep: imperative steps, the gate/stop conditions, and the trigger phrases in
description. - Move rationale ("why we chose X") to a
log/changelog-*.mdentry, not the body. - Keep body <~5k tokens; push long reference/data to a sibling file loaded on demand.
- Re-check: the directory-name command still resolves;
description+when_to_use<=1536 chars.
Notes
Terseness is for the agent's token budget, not style. If cutting a line could change behavior, keep it.