Troubleshooting

Skill won't upload

Error: "Could not find SKILL.md in uploaded folder"

Cause: File not named exactly SKILL.md

Solution:

• • Rename to SKILL.md (case-sensitive)
• • Verify with: ls -la should show SKILL.md

Error: "Invalid frontmatter"

Cause: YAML formatting issue

Common mistakes:

# 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
---

Error: "Invalid skill name"

Cause: Name has spaces or capitals

# Wrong
name: My Cool Skill

# Correct
name: my-cool-skill

Skill doesn't trigger

Symptom: Skill never loads automatically

Fix:

Revise your description field. See The Description Field for good/bad examples.

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?

Debugging approach:

Ask Claude: "When would you use the [skill name] skill?" Claude will quote the description back. Adjust based on what's missing.

Skill triggers too often

Symptom: Skill loads for unrelated queries

Solutions:

1. Add negative triggers

description: Advanced data analysis for CSV files. Use for
statistical modeling, regression, clustering. Do NOT use for
simple data exploration (use data-viz skill instead).