Writing a skill
Write the trigger, the operating rules, and the references.
Keep local commands, product facts, and team policy in the consuming repo.
- 01Trigger
- 02Rules
- 03References
- 04Scope
Use a small folder
A simple skill has one `SKILL.md`. Add references only when the body would become too long.
- Entry
- SKILL.md
- Optional
- references/
- Keep out
- repo policy
# minimal
skills/write-feature/
SKILL.md
# with one reference
skills/write-feature/
SKILL.md
references/
task-template.md
Write the trigger first
The description decides whether the skill loads. Make it direct.
- Start with the work: Implement, Review, Audit, Research, Write.
- Name when the skill applies.
- Name what the agent must not do.
- Name when to skip it.
---
name: write-feature
description: Implement a feature from a spec. ALWAYS apply when the task adds behavior. Do not refactor in passing. Skip fixes, migrations, and test-only work.
---
Keep the body actionable
The body tells the agent what to do after the skill loads.
Use numbered rules
Give the agent a small checklist it can follow.
Keep it self-contained
Do not depend on a sibling skill being installed.
Force visible proof
When a rule matters, make the agent leave output the next reader can inspect.
Use references sparingly
Put long templates or examples in `references/`. Keep them one hop away from `SKILL.md`.
Add a task template only when useful
Use a template for long work that needs state: plans, evidence, attempts, decisions, and follow-up.
Keep repo knowledge out
A Suspec skill must work in any repo. Put local commands and product knowledge in that repo's AGENTS.md.
stack-specific engineering advice
internal product runbooks
automation scripts
always-on instructions
shared core skills that every other skill imports
business logic that belongs in the consuming repo
Read the source
The same file shape is used in both tiers. Framework-free examples live in the suspec-skills catalog; the write-* family used above (write-feature, write-fix, ...) lives in the Suspec kit.