---

name: skill-testing-checklist description: Use after writing a new skill or editing an existing one to verify it will be loaded at the right time, followed correctly, and not cause problems in adjacent tasks. Covers the trigger probe, the procedure walk-through, the pitfall audit, the scope test, and the staleness check.

Skill Testing Checklist

Writing a skill is half the job. The other half is checking that it works before you paste it into a real project and an agent does the wrong thing confidently.

When to trigger

You have just written a new skill, updated an existing one, or a skill is behaving unexpectedly (loading when it should not, not loading when it should, or an agent following it incorrectly).

The five tests

Run in order. Fail early = do not continue.

1. Trigger probe - write 3 should-trigger + 2 should-not requests, read the description. Does it match the first group and exclude the second? If not, narrow the description until it does. Field test: drop it in .claude/skills/, fresh session, send a should-trigger request - did it load?

2. Procedure walk-through - run every step in the actual repo, not in your head.

• Every command must be in AGENTS.md > Local Commands
• Every file path must exist right now
• Any git add step: confirm each path exists first (see AGENTS.md > Deployment + Tooling Gotchas - nonexistent path aborts the entire staging silently)
• Any "I'd need to know X to do this step" = missing step or missing pitfall

3. Pitfall audit - for each pitfall: has it actually happened in this codebase? "You might forget to..." is not a pitfall. Each entry needs: concrete wrong action + exact consequence + exact fix.

4. Scope test - answer in one sentence: what does this skill do? Two things = two skills. Check .agents/skills/ for overlap; overlapping triggers both load and may contradict.

5. Staleness check - verify every command against AGENTS.md > Local Commands, every path against the tree, every rule reference against the current AGENTS.md. If a fact could change, add an "as of YYYY-MM-DD" note.

See reference/field-test-guide.md for full failure mode table and live test procedure.

Ready to ship

• All 5 tests pass
• No content duplicated from AGENTS.md
• Exists in both .agents/skills/ and .claude/skills/

Still a draft

• Trigger matches a topic, not a condition
• Procedure step says "appropriately" or "as needed"
• Pitfall says "make sure to..." not "this fails because..."
• Duplicates a rule from AGENTS.md

Pitfalls

• A broad trigger loads the skill for every question in the domain, taxing context on irrelevant jobs. It is the hardest bug to notice - the skill appears to work fine.
• Theoretical pitfalls train agents to over-check. Only real, confirmed failures belong.
• Not syncing .agents/skills/ and .claude/skills/ gives Codex and Claude Code different knowledge.
• Paraphrasing AGENTS.md incorrectly is worse than not mentioning the rule. Point there directly.