mtk-agent-toolkit: Skill for Claude Code

Writing Skills

Overview

A skill is a reusable behavior contract that shapes how an agent approaches a category of work. Writing a good skill requires observing baseline failures first, then writing the minimum documentation that closes those gaps, then testing that the skill resists pressure.

When To Use

• Adding a new skill to the toolkit
• Substantially rewriting an existing skill

When NOT To Use

• One-off project-specific conventions (put those in CLAUDE.md)
• Mechanical constraints better handled by automation (put those in hooks or settings)

Workflow

Phase 1: Observe Baseline Failures

Before writing any skill content:

1. Run 2-3 representative scenarios without the skill.
2. Document what went wrong:
   • What steps were skipped?
   • What rationalizations were used to skip them?
   • What outcomes were produced?
3. This creates the "RED" baseline — the specific gaps the skill must close.

Phase 2: Write The Minimum Skill

1. Follow the anatomy defined in docs/skill-anatomy.md:

   • Required: frontmatter (name, description, type: skill — or type: tech-stack for tech stack skills), # Title, ## Overview, ## When To Use, ## Workflow, ## Verification
   • Recommended: ### When NOT To Use, ## Rules
   • Do not add rationalization tables, red-flag lists, or ALL-CAPS emphasis. Current models follow instructions literally and over-trigger on pressure language; state each rule once, in plain words, in the step it governs.

2. Apply the CSO principle: The description in frontmatter must trigger on conditions, not summarize the workflow.

   • Bad: "Create implementation plans with acceptance criteria and dependency ordering"
   • Good: "Use after a spec is approved and before multi-file implementation begins"
   • Why: Workflow summaries cause the agent to follow the description instead of reading the full SKILL.md

3. Put field-earned rules in the workflow: When a baseline failure shows a step being skipped, close it with one plain sentence in that step (what to do and, if it is not obvious, why). Do not restate it in a separate table or list.