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.md procedural 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
--help and tests.
Use skill-checklist.md before opening a PR.
Write and test
- Use Agent Skills-compatible
name and description frontmatter.
- 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.
1---2name: writing-skills3description: Creates or improves an Agent Skill by defining a precise trigger boundary, concise procedural instructions, progressive-disclosure references, deterministic helpers, routing evals, and validation evidence. Use when authoring or reviewing SKILL.md, skill metadata, bundled references, or skill packaging. Not for ordinary project documentation or application code.4---56# Writing Skills78Write a skill for another agent to use under pressure. Context is a shared9budget, so every paragraph must earn its place.1011## Design the boundary12131. Collect concrete prompts that should and should not activate the skill.142. Name the responsibility in plain language and use a short verb-led name.153. Put all activation conditions in frontmatter `description`; the body loads16 only after activation.174. Keep `SKILL.md` procedural and under 500 lines.185. Move detailed rules, variants, schemas, and examples into one-level-deep19 `references/` files.206. Add a script only for deterministic repeated work, with `--help` and tests.2122Use [skill-checklist.md](references/skill-checklist.md) before opening a PR.2324## Write and test2526- Use Agent Skills-compatible `name` and `description` frontmatter.27- State when to use, when not to use, safety boundaries, workflow, handoffs,28 and completion evidence.29- Avoid copying a reference repository's text, names, examples, or scripts;30 rewrite principles and record provenance.31- Add at least three positive and two negative routing cases, including close32 neighbors that must not activate.33- Create two or three realistic behavior cases with observable outputs and34 edge conditions before expanding the suite.35- Run each case in a fresh context with the candidate skill and with no skill or36 a frozen previous version. Keep prompts, fixtures, model settings, and output37 locations identical.38- Capture artifacts, public trace/tool summaries, duration, and usage. Grade39 deterministic assertions first and use blinded rubric or human review for40 judgment-heavy output.41- Optimize description triggering on a training set and choose the final result42 by a held-out validation set; do not paste missed query keywords into the43 description until fixtures pass by accident.44- Run the repository validator and at least one realistic forward test for a45 behavior-changing skill.4647Descriptions should be specific enough to distinguish neighboring skills, but48not so broad that every task activates the skill.4950Use `agent-evaluation` for the baseline/candidate result format and regression51analysis. Read [evaluation-loop.md](references/evaluation-loop.md) before52claiming that a skill improves agent behavior.5354## Completion condition5556A skill is ready when its trigger boundary is understandable, its body is57actionable, its links and helpers work, its routing cases generalize, and a58realistic isolated comparison produces better evidence than the baseline59without an unacceptable cost or protected-metric regression.
thiientv