Skill Trigger Doctor: Why a Claude Code Skill Won't Load

    1

    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

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIDeepSeekDeepSeekMuseMuse+22 more

    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.

    #SeverityFile:lineFinding
    1HighSKILL.md:2name does not match folder name
    2MediumSKILL.md:3description says what it does but gives no trigger phrases
    3LowSKILL.md:12body 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.

    SKILL.md

    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.md file name, folder nesting, frontmatter delimiters, name (kebab-case, matches folder), description present 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 workflow
    • scripts/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-doctor folder 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. 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. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 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

    Permissions

    Terminal / Shell
    Read Files
    Write Files
    Listed9 days ago

    What's inside

    Frequently Asked Questions

    This skill addresses silent registration failures where a skill exists in your directory but refuses to load in the CLI, usually due to strict YAML formatting, naming mismatches, or file-system shadowing.

    This tool is specifically designed for the Claude Code CLI environment and its unique `SKILL.md` architecture; it is not intended for generic Anthropic API prompt engineering.

    No complex setup is required; once installed, you simply provide the name or path of the malfunctioning skill and the agent handles the directory scanning and file-system discovery.

    The skill provides an itemized diagnostic report with 'diff-ready' code blocks, allowing you to either review the changes first or authorize the agent to apply the fixes to the file directly.

    The package includes the core diagnostic skill for the Claude Code environment and a specialized Python 3 helper script for offline linting and frontmatter validation.

    The 'doctor' identifies 'shadowing' conflicts, which occur when a project-level skill and a personal-level skill share the same name, causing one to be ignored by the harness.

    New in Prompt & Skill Engineering