Writing Skills
Write a skill for another agent to use under pressure. Context is a shared budget, so every paragraph must earn its place.
Design the boundary
- Collect concrete prompts that should and should not activate the skill.
- Name the responsibility in plain language and use a short verb-led name.
- Put all activation conditions in frontmatter
description; the body loads only after activation. - Keep
SKILL.mdprocedural and under 500 lines. - Move detailed rules, variants, schemas, and examples into one-level-deep
references/files. - Add a script only for deterministic repeated work, with
--helpand tests.
Use skill-checklist.md before opening a PR.
Write and test
- Use Agent Skills-compatible
nameanddescriptionfrontmatter. - State when to use, when not to use, safety boundaries, workflow, handoffs, and completion evidence.
- Avoid copying a reference repository's text, names, examples, or scripts; rewrite principles and record provenance.
- Add at least three positive and two negative routing cases, including close neighbors that must not activate.
- Create two or three realistic behavior cases with observable outputs and edge conditions before expanding the suite.
- Run each case in a fresh context with the candidate skill and with no skill or a frozen previous version. Keep prompts, fixtures, model settings, and output locations identical.
- Capture artifacts, public trace/tool summaries, duration, and usage. Grade deterministic assertions first and use blinded rubric or human review for judgment-heavy output.
- Optimize description triggering on a training set and choose the final result by a held-out validation set; do not paste missed query keywords into the description until fixtures pass by accident.
- Run the repository validator and at least one realistic forward test for a behavior-changing skill.
Descriptions should be specific enough to distinguish neighboring skills, but not so broad that every task activates the skill.
Use agent-evaluation for the baseline/candidate result format and regression
analysis. Read evaluation-loop.md before
claiming that a skill improves agent behavior.
Completion condition
A skill is ready when its trigger boundary is understandable, its body is actionable, its links and helpers work, its routing cases generalize, and a realistic isolated comparison produces better evidence than the baseline without an unacceptable cost or protected-metric regression.


