82 lines
2.6 KiB
Markdown
82 lines
2.6 KiB
Markdown
# 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:**
|
|
```yaml
|
|
description: Advanced data analysis for CSV files. Use for statistical
|
|
modeling, regression. Do NOT use for simple data exploration.
|
|
```
|
|
|
|
2. **Be more specific:**
|
|
```yaml
|
|
# Bad: "Processes documents"
|
|
# Good: "Processes PDF legal documents for contract review"
|
|
```
|
|
|
|
3. **Clarify scope:**
|
|
```yaml
|
|
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
|