skill-trigger-auditor

Skill Trigger Auditor

Layer: validation / routing audit.

Dominant variable

Does the right skill fire on the right input, without collisions? When that is uncertain, settle it before any other check.

Discard if

• The skill's description and triggers are not changing: use a general skill-quality audit instead.
• The change is internal logic only, with no trigger change: use a normal code review.
• This session already completed a trigger audit for that skill.

Key assumptions

1. A routing table or skill index is available, if you keep one (a file that maps intents to skills and names collision winners). If it is missing, collision detection loses precision: say so in the report and audit from the skills' own descriptions.
2. You can list the installed skills (user skills in ~/.claude/skills, project skills in .claude/skills, plus plugin skills). If not, only a partial audit is possible: say so.

Required sequence

1. Apply your safety, permission and truthfulness rules first when the audited skill involves risky actions.
2. Read the current routing table or skill index (if any), the project's agent routing notes (if any), and the list of installed skills.
3. Read the candidate SKILL.md files and only the reference files directly tied to them. If recent failure reports tag a skill as chosen wrongly or applied outside its scope, audit that skill first.
4. Classify each candidate:
   • should_trigger: must fire on this input
   • should_not_trigger: must stay silent on this input
   • ask_clarifying_question: needs clarification before triggering
   • route_to_governance: belongs to a higher-level policy or rule layer
   • blocked_by_risk: stopped at a risk gate
5. When a description or routing field changes, create at least 1 positive and 1 negative case.

Audit axes

1. Description clarity

Does the description state the task type, its boundaries and its collision risk?

• State the "model would do it alone" case. Adapted from addyosmani/agent-skills (evals/README.md). If the model tends to handle an input without the skill (the user pastes code or a diff, the request does not say "test" or "review"), does the description say the skill applies there too? The source reports a single-source measurement on a fixed model: that one phrase raised a review skill from 7/27 to 21/27 activations and a TDD skill from 6/24 to 19/24, while adjacent prompts that must not trigger stayed at 0. Treat it as a Claim. When you add such a phrase, also create the matching negative case (same paste, different skill, for example a diff plus a commit-message request).
• Does it name a verb-form task?
• Does it state hard exclusions?
• Does it state priority against skills it can collide with?
• No procedure words in the description. The description should hold routing language only. An instruction like "always do X first" in a description is loaded all the time, even when the skill is never invoked, and can distort behavior. The body loads only on invocation, so this risk is limited to the description field.