🛠️Advanced

Troubleshooting

A catalog of failure modes — from upload errors to triggering problems, MCP calls, and context bloat.

Skill Won't Upload

Symptom: "Could not find SKILL.md in uploaded folder". Cause: the file is not named exactly SKILL.md (case-sensitive). Fix: rename and verify with ls -la.

Symptom: "Invalid frontmatter". Cause: YAML formatting issue — missing --- delimiters, unclosed quotes, or tabs where spaces should be. Fix: normalize to the minimal template and re-validate.

yaml

# Wrong — missing delimiters
name: my-skill
description: Does things

# Wrong — unclosed quotes
---
name: my-skill
description: "Does things
---

# Correct
---
name: my-skill
description: Does things
---

Symptom: "Invalid skill name". Cause: name has spaces or capitals. Fix: convert to kebab-case (my-cool-skill, not My Cool Skill).

Skill Doesn't Trigger

Symptom: skill never loads automatically. Fix: revise the description field. Quick checklist:

▸Is it too generic? ("Helps with projects" won't work.)
▸Does it include trigger phrases users would actually say?
▸Does it mention relevant file types if applicable?

Debug approach: ask Claude "When would you use the [skill name] skill?" Claude will echo its understanding of the description. Adjust based on what is missing or misleading.

Skill Triggers Too Often

Symptom: skill loads for unrelated queries. Solutions: add negative triggers, narrow scope, clarify what the skill is NOT for.

yaml

# Too broad
description: Processes documents

# More specific
description: Processes PDF legal documents for contract review

# Scope clarified
description: PayFlow payment processing for e-commerce. Use specifically for online payment workflows, not for general financial queries.

MCP Connection Issues

Symptom: skill loads but MCP calls fail. Walk the checklist in order:

▸Verify the MCP server is connected (Claude.ai: Settings → Extensions → [Your Service], should show "Connected").
▸Check authentication — API keys valid and not expired, proper scopes granted, OAuth tokens refreshed.
▸Test MCP independently — ask Claude to call the MCP directly without the skill. If that fails, the issue is MCP, not the skill.
▸Verify tool names — skill references must match MCP tool names exactly (case-sensitive).

Instructions Not Followed

Symptom: skill loads but Claude ignores parts of the instructions. Three common causes and fixes:

▸Too verbose: keep instructions concise; use bullet points and numbered lists; move detailed reference to separate files under references/.
▸Buried: put critical instructions at the top under ## Important or ## Critical headers; repeat key points if needed.
▸Ambiguous: rewrite "Make sure to validate things properly" as "CRITICAL: Before calling create_project, verify project name is non-empty, at least one team member assigned, and start date is not in the past."

💡Tip

For critical validations, bundle a script that performs the checks programmatically instead of relying on language instructions. Code is deterministic; language interpretation is not.

Large Context Issues

Symptom: skill seems slow or responses degrade. Causes: SKILL.md content too large, too many skills enabled at once, all content loaded up-front instead of via progressive disclosure.

▸Optimize SKILL.md: move detailed docs to references/, link instead of inlining, keep SKILL.md under 5,000 words.
▸Reduce enabled skills: if more than 20–50 are enabled simultaneously, evaluate which are actually needed and consider skill "packs" for related capabilities.
▸Re-audit progressive disclosure: anything not needed for initial selection should live in references/ or scripts/, not in the SKILL.md body.

← PreviousDistribution