Lesson Content

Diagnosing activation failures.

If a Skill is not activating when expected:

1. Trigger check: Is the request phrasing matching any of the defined triggers? Test with the exact phrases in the trigger list.
2. File location check: Is the Skill file in the correct directory for its intended scope (project vs. personal)? Verify the path against current documentation.
3. Format check: Is the frontmatter valid YAML? An invalid frontmatter silently prevents the Skill from loading.
4. Claude Code restart: Skill changes sometimes require a Claude Code restart to take effect.

For intermittent activation failures – the Skill works sometimes but not always – the trigger list may be too narrow. Add phrasings that cover the range of requests that should activate the Skill.

Diagnosing unintended activation.

If a Skill is activating when it should not:

1. Review the trigger list for overly broad terms
2. Test by phrasing requests that should NOT activate the Skill
3. Narrow triggers to more specific phrasings
4. Add explicit exclusion context in the Skill's description if supported

Updating Skills for workflow changes.

Skills become stale when the workflow they describe changes:

• Team adopts a new testing framework – update the testing Skill triggers and instructions
• Security review process adds new criteria – update the security review Skill checklist
• API documentation format changes – update the docs generation Skill template

Stale Skills are actively harmful: Claude follows outdated instructions that produce work the team then has to correct. Schedule a quarterly Skill review alongside any major workflow changes.

Skill maintenance in team practice.

• Assign a Skill "owner" for each team Skill – responsible for updates when the workflow changes
• Add Skill review to the team's quarterly process review
• When a PR is rejected because Claude followed an outdated Skill instruction – that is the trigger to update the Skill immediately
• Track Skill effectiveness anecdotally: are the Skills saving time and improving consistency? If not, investigate.