# How to Debug Skills Not Triggering Automatically in Anthropic Financial Services > Fix Anthropic financial services skills not triggering automatically. Learn to debug by checking SKILL.md, agent.yaml, and syncing skills with the provided script. - Repository: [Anthropic/financial-services](https://github.com/anthropics/financial-services) - Tags: how-to-guide - Published: 2026-05-07 --- **To debug skills that fail to trigger automatically despite matching conditions, verify the `description` field in [`SKILL.md`](https://github.com/anthropics/financial-services/blob/main/SKILL.md) contains explicit user-facing trigger phrases, ensure the skill is registered in the agent's [`agent.yaml`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/SKILL.md) to list exact trigger phrases. For example, in [`plugins/vertical-plugins/equity-research/skills/competitive-analysis/SKILL.md`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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: ```bash 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`](https://github.com/anthropics/financial-services/blob/main/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: ```bash python3 scripts/sync-agent-skills.py ``` This copies the latest [`SKILL.md`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/SKILL.md)** at paths like [`plugins/vertical-plugins/equity-research/skills/initiating-coverage/SKILL.md`](https://github.com/anthropics/financial-services/blob/main/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: ```bash python3 scripts/check.py ``` Look for "skills.path" errors or "bundled-skill drifted" warnings. 4. **Synchronize the skill** if drift is detected: ```bash 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: ```markdown 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 ", "compare X against peers", "build a market map". ``` Run validation and synchronization scripts: ```bash # 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`](https://github.com/anthropics/financial-services/blob/main/CLAUDE.md)** - High-level overview of skill-trigger mechanics located at the repository root. - **[`scripts/check.py`](https://github.com/anthropics/financial-services/blob/main/scripts/check.py)** - Linter that validates manifest references and skill paths, reporting missing entries or drift. - **[`scripts/sync-agent-skills.py`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/plugins/agent-plugins/valuation-reviewer/agent.yaml). ## Summary - The `description` field in [`SKILL.md`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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`](https://github.com/anthropics/financial-services/blob/main/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.