writing-great-skills

Hard Rules

1. Comments ≤20 characters, clear per item, no repetition, no extra spaces for alignment—formatting is for humans; models only read content.
2. Sentences that don’t change behavior when removed = no-op sentences, delete the entire sentence, don’t rewrite it. Assume the model is already smart: for each paragraph, ask yourself "Is this sentence worth its token?"
3. Write the same meaning only once (single source of truth); modify behavior in only one place.
4. Write positive instructions, not prohibitions—"Don’t do X" makes the model fixate on X; clarify what to do, and X won’t happen naturally. Except for hard constraints, which must be paired with "What to do instead."
5. Use leading terms: Pick a compact concept already in the model’s pre-training (e.g., wrap-up, inflection point, probe) as an anchor, replacing a long explanation with one word.
6. Automate anything that can be enforced mechanically with regex/validation/scripts; don’t write it into documentation—documentation is for judgment-based tasks.

Structure & Budget

• SKILL.md

  only contains content used by every branch: rules + common commands/steps. Steps must include completion criteria—checkable, clear distinction between done and not done.
• Budget: SKILL.md body <500 lines (official upper limit recommendation); high-frequency resident skills kept under 200 words. If exceeded, move details to

  references/xx.md

  .
• For pointers, clarifying "when to read it" is more important than "where it is"; reference chains are only one level deep (SKILL.md → references, no further drilling).
• Trade-off criteria: How many branches use this content. Piling everything at the top = bloated; hiding commonly used content in pointers = poor usability.

frontmatter

• name

  (required): 1-64 characters, lowercase letters/numbers/hyphens, must match the directory name.

• description

  (required): ≤1024 characters, see the next section for writing guidelines.
• Optional:

  compatibility

  (environment requirements),

  metadata

  (key-value pairs, e.g.,

  requires.bins

  ),

  allowed-tools

  (pre-approved tools, experimental),

  license

  .
• To prevent automatic invocation by models, set

  disable-model-invocation: true

  (only responds to human calls), and the description becomes a human-readable sentence.

description (Trigger Surface)

• Structure = what to do (one sentence) + when to use it (trigger conditions), in the third person.
• Never summarize the workflow—actual testing shows: if the description includes the workflow, the agent will follow the summary instead of reading the body (e.g., "Do code review between tasks" made the agent turn a two-stage review into a single stage). This renders the body useless.
• Trigger terms describe symptoms and scenarios (e.g., "race condition, timing dependency, intermittent issues"), one per branch; synonymous rewrites = writing the same branch twice, delete them.
• Naming starts with gerunds/verbs (e.g.,

  creating-skills

  instead of

  skill-creation

  ).

Flexibility (Match Instruction Strength to Task Fragility)

• High flexibility (written guidelines): Multiple valid paths, relies on judgment—e.g., code review.
• Medium flexibility (parameterized templates): Recommended patterns allowed with variations—e.g., report generation.
• Low flexibility (precise scripts/commands): Fragile operations, strict sequence required—e.g., database migration. Write it verbatim and note "Do not modify the command, do not add parameters."
• Analogy: Guardrails for narrow bridges over cliffs (low flexibility), directions for open fields (high flexibility). Choosing the wrong level = either overly restrictive or high-risk.

Validation (Mandatory After Writing, Otherwise It’s Unfinished)

1. Baseline (Red) : Run the agent in real scenarios without the skill installed, record how it fails and how it rationalizes its mistakes.
2. Write the skill (Green) : Only write for the observed failure patterns, reinstall and re-run to confirm compliance.
3. Fix vulnerabilities (Refactor) : Re-test with alternative phrasings, fix any new loopholes found until no more can be exploited.

Common Issues (For Diagnosis)

• Premature completion: Tries to finish before steps are done. First refine the completion criteria; if that doesn’t work, hide subsequent steps from view.
• Redundancy: Same meaning written in multiple places, double maintenance and token cost.
• Accumulation: Dead layers built up from only adding content and never deleting—the default outcome of skills without pruning discipline.
• Bloat: Every line is useful but the whole is too long. Fix with structure (references / pointers / splitting).
• No-op sentences: See Hard Rule 2.
• Prohibitions: See Hard Rule 4.
• Summary replaces body: See the Description section—root cause is writing workflows in the trigger surface.

Sources