english/.opencode/skills/skill-creator/references/troubleshooting-guide.md

Troubleshooting Guide

Skill Won't Upload

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

• Rename to exactly SKILL.md (case-sensitive). Verify with ls -la.

Error: "Invalid frontmatter"

• Ensure --- delimiters on both sides
• Check for unclosed quotes in YAML
• Validate YAML syntax

Error: "Invalid skill name"

• Use either skill-name or namespace:skill-name
• Namespace and skill id must be kebab-case (no spaces, no capitals)
• Wrong: My Cool Skill → Correct: ck:my-cool-skill

Skill Doesn't Trigger

Symptom: Skill never loads automatically.

Checklist:

• Is description 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: Ask Claude "When would you use the [skill-name] skill?" — adjust description based on response.

Skill Triggers Too Often

Solutions:

1. Add negative triggers:

   description: Advanced data analysis for CSV files. Use for statistical
     modeling, regression. Do NOT use for simple data exploration.
   

2. Be more specific:

   # Bad: "Processes documents"
   # Good: "Processes PDF legal documents for contract review"
   

3. Clarify scope:

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

MCP Connection Issues

Symptom: Skill loads but MCP calls fail.

1. Verify MCP server is connected (Settings > Extensions)
2. Check API keys valid and not expired
3. Test MCP independently: "Use [Service] MCP to fetch my projects"
4. Verify skill references correct MCP tool names (case-sensitive)

Instructions Not Followed

Common causes and fixes:

Cause	Fix
Instructions too verbose	Use bullet points, move details to references/
Critical info buried	Put at top, use ## CRITICAL headers
Ambiguous language	Replace "validate properly" with specific checklist
Model skipping steps	Add "Do not skip validation steps" explicitly

Advanced: For critical validations, bundle a script that performs checks programmatically. Code is deterministic; language interpretation isn't.

Large Context Issues

Symptom: Skill seems slow or responses degraded.

Solutions:

1. Move detailed docs to references/ — keep SKILL.md under 300 lines
2. Link to references instead of inlining content
3. Evaluate if too many skills enabled simultaneously (>20-50 may degrade)
4. Consider skill "packs" for related capabilities