- Home
- Skills
- Prompt & Skill Engineering
- Skill Trigger Doctor: Why a Claude Code Skill Won't Load
Skill Trigger Doctor: Why a Claude Code Skill Won't Load
Diagnose why one Claude Code skill doesn't fire. Ranked findings, exact edits, and test prompts to verify the fix in a fresh session.
$9
Works with the AI Agents you already use
Skill Trigger Doctor: Why a Claude Code Skill Won't Load
Example session with this skill installed
My invoice-helper skill stopped triggering after I renamed its folder.
- Read your context and instructions
- Compiled the trigger doctor
Diagnosis: invoice-helper
Loads from: ~/.claude/skills/invoice-helper-v2/SKILL.md (personal scope)
Most likely cause: the folder was renamed to invoice-helper-v2, but the frontmatter name: still says invoice-helper. The name no longer matches the folder.
| # | Severity | File:line | Finding |
|---|---|---|---|
| 1 | High | SKILL.md:2 | name does not match folder name |
| 2 | Medium | SKILL.md:3 | description says what it does but gives no trigger phrases |
| 3 | Low | SKILL.md:12 | body line says "do not act without being asked" |
Edit 1 (before → after)
- name: invoice-helper
+ name: invoice-helper-v2
(or rename the folder back to invoice-helper)
Edit 2 (description rewrite)
+ description: Creates and formats customer invoices. Use when the user asks to draft, fix, or send an invoice, or mentions billing line items.
Ruled out: missing --- delimiters, tabs, BOM, invalid YAML, same-name skill in project scope.
Test prompts that should trigger: "Draft an invoice for Acme, 3 line items", "Fix the totals on this invoice", "Format my invoice as a table".
Near-misses that should NOT trigger: "Explain how invoices work in accounting", "Summarize this receipt".
Next steps: I have not changed any files. Tell me to apply edits 1 and 2, then start a fresh Claude Code session and run the test prompts.
Connects securely to your tools. The creator never sees your data.
About this skill
What it does Skill Trigger Doctor investigates why ONE specific installed Claude Code skill is not triggering. It reports the exact path the skill loads from (personal, project, or plugin folders), then checks, most likely cause first:
- Structure:
SKILL.mdfile name, folder nesting, frontmatter delimiters,name(kebab-case, matches folder),descriptionpresent and valid YAML, tabs, BOM, line endings. - Description: whether it states what the skill does and when to use it, with concrete trigger phrases. It quotes the weak text and proposes a rewrite.
- Conflicts: same-name skills in other scopes and a few other skills with overlapping trigger words.
- Body: lines that contradict the description or tell the model not to act.
Who it is for Anyone maintaining their own Claude Code skills who hits "my skill doesn't trigger", "Claude ignores my SKILL.md", or "Claude uses the wrong skill", including after renaming or moving a skill folder or installing a plugin.
Example
Request: "My invoice-helper skill stopped triggering after I renamed its folder."
Result: a ranked markdown report (file, line, exact before → after edit, and why), a "ruled out" list, 3 prompts that should trigger the skill, 2 near-miss prompts that should not, and how to verify in a fresh session. Fixes are applied only after you agree.
What is included
SKILL.md— diagnosis workflowscripts/lint_skill.py— optional read-only frontmatter and location linter (Python 3)
Requirements
- Claude Code with local filesystem access
- Python 3 only if you want the optional helper
- Install: copy the
skill-trigger-doctorfolder into~/.claude/skills/or a project's.claude/skills/
Limits Covers one skill plus its direct conflicts, not a full audit. Results are likely causes, not guarantees. Undocumented harness details are flagged "verify against current docs". No network calls, and no edits without your consent.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Prompt & Skill Engineering.
Limited to single-skill diagnosis per run. Precedence rules and plugin folder structures should be verified against the latest Claude Code docs. Requires Python 3 for the optional linting script.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 9 days ago