Claude Agent Skill (SKILL.md) Authoring Brief

Write a SKILL.md that teaches an agent a specific workflow, and nothing adjacent. SKILL Name (kebab-case): [NAME] What the agent should do when this skill applies: [WORKFLOW] When it should NOT trigger: [NEAR MISSES] Inputs the user will have: [FILES, TICKETS, COMMANDS] Definition of done: [CHECKS] Tools or commands it may run: [LIST] Commands it must not run: [LIST] Repo conventions to respect: [TEST COMMAND, LINT, BRANCH RULES] Example request that should trigger it: [SENTENCE] Example request that should not: [SENTENCE] WRITE THESE FILES 1) SKILL.md with YAML frontmatter (name, description). The description is the trigger: include the phrases a user would actually say, and the negative cases, because the agent uses it to decide whether to load the skill. 2) Body sections: - Preconditions (what to read first) - Steps in order, each with the command or the file to edit and the check that the step worked - Output the user should see - Failure modes and the one recovery action for each - A stop rule: when to ask the user instead of guessing 3) A references/ excerpt only if a detail is long — otherwise keep it in SKILL.md. Say which choice you made and why. 4) A 10-line eval: 3 prompts that should trigger, 3 that should not, and what "pass" means for each. Keep the skill under 500 lines. Procedures, not a style guide for the whole company. Do not instruct the agent to skip tests, force-push, or edit secrets.