writing-skillslisted

# Writing Skills Build effective A Team skills through TDD for documentation: write the skill, watch agents use it, close the gaps. ## What Makes a Good Skill A skill is a **reference guide that agents consult before taking action**. It is NOT: - A tutorial (agents don't need hand-holding on basics) - A checklist of preferences (that's a rule file) - An agent definition (that's `.claude/agents/`) A skill must: - Define WHEN to use it (trigger conditions) - Define WHEN NOT to use it (scope limits) - Define the process (steps, decision points) - Define red flags (patterns that mean you're off-track) - Be verifiable (an agent following it produces measurable output) ## The TDD Process for Skills ### Phase RED — Write the Skill, Watch Agents Fail 1. Write a first draft of the skill 2. Give agents a task that should trigger it 3. Watch them use it — specifically look for: - Where they skip steps - Where they interpret a step differently than intended - Where they think they're done but aren't - Where the skill is silent on an important case 4. **The gaps you find ARE the failing tests** ### Phase GREEN — Close the Gaps For each failure you observed: - Add explicit language that prevents the wrong behavior - Add a red flag for the rationalization the agent used - Add a concrete example if the step was ambiguous - Make the step smaller if the agent couldn't execute it correctly ### Phase REFACTOR — Tighten - Remove content that agents ignored (it's not load-be