How to Debug Skills Not Triggering Automatically in Anthropic Financial Services

To debug skills that fail to trigger automatically despite matching conditions, verify the description field in SKILL.md contains explicit user-facing trigger phrases, ensure the skill is registered in the agent's agent.yaml manifest, and run python3 scripts/sync-agent-skills.py to synchronize bundled copies.

In the anthropics/financial-services repository, skills activate automatically when Claude's language model detects that a user request satisfies the skill's trigger description. When you encounter skills not triggering automatically despite apparent condition matches, the issue typically stems from description placement errors, manifest registration gaps, or synchronization drift between source and bundled copies.

How Skill Trigger Evaluation Works

Claude evaluates the description field at the top of each SKILL.md file to determine whether to activate a skill. The body content of the markdown file is lazy-loaded, meaning it is only examined after the skill has already been selected based on the description. If trigger cues exist only in the body and not in the top-level description, Claude never sees them during the decision phase.

Common Causes for Skills Not Triggering Automatically

Vague or Missing Trigger Phrasing in SKILL.md

The description field must explicitly contain the keywords and phrases users naturally utter. If the description is too generic or omits specific command language, the model cannot match it to user requests.

Fix: Edit the description in SKILL.md to list exact trigger phrases. For example, in plugins/vertical-plugins/equity-research/skills/competitive-analysis/SKILL.md, include specific commands like "competitive analysis" or "compare X against peers".

Trigger Words Placed Only in the Body

Placing trigger language exclusively in the body markdown section prevents activation. Since the body is not parsed during the initial selection step, Claude cannot identify the skill as relevant based on body content alone.

Fix: Move all trigger cues to the description field. Add a "When to use this skill" bullet list immediately after the description paragraph, keeping detailed workflows in the body.

Skill Not Indexed in agent.yaml

Each plugin's agent.yaml file must list its skills via a skills array pointing to the skill folder. If the folder is missing from the manifest, the runtime never considers the skill for activation.

Fix: Run the repository linter to verify registration:

python3 scripts/check.py

Inspect the output for errors like skills.path -> ... (not found) and add the missing entry to the skills list in the appropriate agent.yaml.

Bundled Skill Drift from Source

Agent-plugins contain vendored copies of skills from vertical-plugins. When source files update, bundled copies can become outdated, causing mismatched or missing trigger descriptions.

Fix: Re-sync the bundled copies using:

python3 scripts/sync-agent-skills.py

This copies the latest SKILL.md (including updated descriptions) into the agent-plugin bundle, ensuring consistency with the source in plugins/vertical-plugins/.

Conflicting or Overlapping Skill Triggers

When multiple skills share similar trigger phrasing, Claude selects the most specific match. If two skills are equally specific, selection becomes nondeterministic.

Fix: Disambiguate triggers by adding unique keywords to each description, or nest the skill under a specific command (e.g., a slash command) that narrows the scope.

Step-by-Step Debugging Workflow

Follow this systematic approach to diagnose why skills are not triggering automatically:

1. Locate the skill's SKILL.md at paths like plugins/vertical-plugins/equity-research/skills/initiating-coverage/SKILL.md.

2. Verify the top-level description contains concise trigger phrases users naturally utter. Ensure it ends with a "When to use this skill" list if applicable.

3. Validate manifest registration by running:

   python3 scripts/check.py

   Look for "skills.path" errors or "bundled-skill drifted" warnings.

4. Synchronize the skill if drift is detected:

   python3 scripts/sync-agent-skills.py

5. Test the trigger by issuing the exact phrase from the description in a Claude session. If the skill still fails to fire, add the phrase verbatim to the description and repeat steps 3-4.

6. Check for overlapping triggers by searching other skills for similar wording. Refine descriptions to make each skill uniquely identifiable.

Code Examples for Fixing Trigger Issues

Update the description field to include explicit trigger language:

description: |
  Build a competitive landscape deck that compares peers,
  visualises market positioning, and synthesises strategic insights.
  **Trigger phrases:** "competitive analysis", "who are the competitors to <company>",
  "compare X against peers", "build a market map".

Run validation and synchronization scripts:

# Check for manifest errors and skill drift

python3 scripts/check.py

# Sync bundled skills with source

python3 scripts/sync-agent-skills.py

Key Files in the Debugging Process

• CLAUDE.md - High-level overview of skill-trigger mechanics located at the repository root.
• scripts/check.py - Linter that validates manifest references and skill paths, reporting missing entries or drift.
• scripts/sync-agent-skills.py - Propagates changes from vertical-plugins to agent-plugins bundles.
• plugins/vertical-plugins/**/skills/**/SKILL.md - Canonical skill definitions containing the trigger description.
• plugins/agent-plugins/**/agent.yaml - Agent manifests listing skill directories and commands, such as plugins/agent-plugins/valuation-reviewer/agent.yaml.

Summary

• The description field in SKILL.md controls automatic triggering; the body is lazy-loaded and ignored during selection.
• Run python3 scripts/check.py to detect missing manifest entries in agent.yaml.
• Execute python3 scripts/sync-agent-skills.py to resolve drift between source skills and bundled copies.
• Place explicit user-facing trigger phrases in the description, not buried in the body content.
• Disambiguate overlapping skills by adding unique keywords to prevent conflicts.

Frequently Asked Questions

Why does my skill not trigger even when the user says relevant things?

The trigger description at the top of SKILL.md must contain the exact phrases users speak. If trigger language exists only in the body markdown, Claude never evaluates it during the decision phase. Move all trigger cues to the description field.

How do I verify if a skill is properly registered in the system?

Run python3 scripts/check.py from the repository root. This linter inspects agent.yaml manifests for broken skills.path references and verifies that each skill directory appears in the manifest's skills array.

What is skill drift and how does it prevent triggering?

Skill drift occurs when the vendored copy of a skill in agent-plugins becomes outdated compared to the source in vertical-plugins. The bundled copy may contain an old description without the correct trigger phrases. Resolve this by running python3 scripts/sync-agent-skills.py to update bundled files.

How do I fix conflicts when multiple skills trigger simultaneously?

When skills have overlapping descriptions, Claude selects the most specific match or behaves nondeterministically. Add unique distinguishing keywords to each skill's description, or scope the skill under a specific command prefix to eliminate ambiguity.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}