Design Principles

• Every line should help the agent decide, do, or verify something.
• Prefer tables, checklists, templates, and input/output examples over explanatory prose.
• Keep rationale to one short sentence unless the agent is likely to make the wrong choice without it.

Precision Before Addition

Before adding instructions, choose one:

Do not add a new section, reference, or checklist until replacement, narrowing, moving, and deletion have been considered.

Keep Vs Cut

Match Structure To Fragility

Preferred Instruction Shapes

Description Rules

• Keep description in third person.
• Put trigger language in description, not the body.
• Front-load what the skill does and when to use it.
• Do not spend description space on internals unless they improve triggering.

Runtime Writing Rules

• Use imperative voice.
• State one default path before mentioning alternatives.
• Use one term per concept; do not rotate synonyms.
• Put universal rules in SKILL.md; put optional depth in routed refs.
• If a section is mostly explanation, cut it or replace it with a denser structure.

Reference Rules

• Reference filenames should predict their contents.
• Each reference should answer one lookup question.
• Keep runtime references flat under references/.
• For related variant-specific references, use sibling files with a shared prefix and explicit differentiator.
• Every bundled reference should have a direct “open when…” entry in SKILL.md.
• Do not create catch-all files for notes, context, or mixed patterns.

Independence And Portability

• Do not require another skill by name at runtime.
• Use skill-root-relative paths by default.
• Reuse established repo-specific path variables only when the repo already standardizes on them.
• Label provider-specific mechanics explicitly and add portability notes when they matter.

Long Files

• Keep SKILL.md short enough to scan as a router.
• For references over 100 lines, add ## Contents.
• If a reference grows because it mixes multiple lookup needs, split it.