references/design-principles.md
Skill Design Principles
Use this guide to keep skill instructions dense, scannable, and worth their token cost.
Core Rule
- 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:
| Action | Use when |
|--------|----------|
| replace | an existing rule is vague, stale, or pointing at the wrong behavior |
| narrow | the current rule is mostly right but over-triggers or invites extra work |
| move | the content belongs in SOURCES.md, SPEC.md, or a routed reference |
| delete | the content repeats another rule or no longer changes behavior |
| add | no existing rule can cover the new behavior without becoming less precise |
Do not add a new section, reference, or checklist until replacement, narrowing, moving, and deletion have been considered.
Keep Vs Cut
| Keep | Cut |
|------|-----|
| project-specific conventions | generic background the agent already knows |
| non-obvious gotchas | motivational filler |
| exact commands, schemas, and templates | repeated restatements of the same rule |
| branch logic and defaults | long essays where a table would work |
| one strong example | multiple weak examples saying the same thing |
| behavior-changing constraints | source notes that belong in SOURCES.md |
Match Structure To Fragility
| Fragility | Preferred structure | Avoid | |-----------|---------------------|-------| | high | exact steps, strict templates, validation gates | open-ended guidance | | medium | short checklist plus examples | long rationale-heavy prose | | low | brief goals and constraints | overspecified playbooks |
Preferred Instruction Shapes
| Need | Preferred shape | |------|-----------------| | choose a path | decision table | | do a repeatable task | numbered checklist | | enforce output structure | template or schema | | show style or tone | input/output examples | | diagnose failures | symptom/cause/fix matrix | | communicate exact facts | compact reference table |
Description Rules
- Keep
descriptionin 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.mdshort 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.