---
alwaysApply: false
globs: ["**/*.md"]
description: "Progressive disclosure, trigger-rich descriptions and eval-first validation for agent skills. Use when writing or editing a SKILL.md or rule source."
---

# Agent Skill Authoring

- Build skills in three disclosure levels: metadata that is always loaded and
  costs a few tokens; a body under 500 lines loaded on trigger; reference
  files loaded only on demand with an explicit "read X when Y" pointer.
- The description is the routing contract. Write it for discovery: name the
  task moments that should trigger the skill and, when useful, the moments
  that should not.
- Keep one skill per trigger moment. Two skills competing for the same moment
  means neither reliably fires; merge them or sharpen their triggers.
- Start from evaluation, not from prose: run the agent on representative
  tasks, find the recurring gap, write the skill that closes it, and keep the
  failing task as the skill's test case.
- After shipping, watch real trajectories for the two failure modes:
  the skill not firing when it should, and the agent leaning on it when it
  should not. Fix the description first; it is the cheapest lever.
- Write instructions as imperatives with concrete examples. A skill is
  executable guidance, not an essay.
- State limits inside the skill: what it must never do, and when the agent
  must stop and ask a human instead.
- Version and review skills like code. A skill edit changes agent behavior
  everywhere the skill installs, so it deserves the same review gate.