Skills: Common Issues & Troubleshooting
Last updated: 2026-08-31
Don't panic when you encounter problems — 90% of Skill issues have standard solutions. This quick-reference guide helps you locate and resolve issues fast.
1. Problem Category Quick Reference
(1) Loading Issues
| Symptom | Possible Cause | Solution |
|---|---|---|
| Skill not loaded | File path error | Check directory and filename |
| Skill not loaded | Frontmatter format error | Check YAML syntax |
| Skill not loaded | Trigger mismatch | Check keywords and trigger conditions |
| Multiple Skills conflict | Same priority | Set priorities or use more precise triggers |
(2) Execution Issues
| Symptom | Possible Cause | Solution |
|---|---|---|
| Tool not called | Prompt doesn't explicitly require it | Specify tool usage steps in the flow |
| Tool not called | Tool not bound | Check frontmatter tools list |
| Wrong output format | Prompt description not specific | Provide output template and examples |
| Hallucinated output | Prompt lacks constraints | Add "only output based on actually read content" |
(3) Quality Issues
| Symptom | Possible Cause | Solution |
|---|---|---|
| Missed review items | Incomplete review dimensions | Add check items; use enumeration instead of description |
| Fix introduces new bug | Missing verification step | Add "run tests after fix" step |
| Inconsistent output | Ambiguous prompt | Use tables and lists instead of natural language |
| Context overflow | Too much project info | Add context trimming rules |
2. Diagnosis Methods
(1) Layered Diagnosis Method
TEXT
📖 Display only
Problem Diagnosis Four Layers
├── Layer 1: File Layer
│ ├── Does the file exist?
│ ├── Is the path correct?
│ └── Is the frontmatter valid?
├── Layer 2: Configuration Layer
│ ├── Does the trigger match?
│ ├── Are tools bound?
│ └── Are permissions sufficient?
├── Layer 3: Prompt Layer
│ ├── Are instructions clear?
│ ├── Are examples sufficient?
│ └── Are constraints explicit?
└── Layer 4: Execution Layer
├── Are tools called as expected?
├── Does output match format?
└── Does the result meet the goal?
(2) A/B Testing Method
TEXT
📖 Display only
Prompt A/B Testing
1. Keep all other conditions the same
2. Only modify one part of the prompt
3. Compare output quality
4. Keep the better version
5. Record the reason for the change
(3) Minimal Reproduction
TEXT
📖 Display only
Problem Reproduction Steps
1. Create a minimal Skill file
2. Keep only the core prompt
3. Confirm whether the problem reproduces
4. Gradually add content to locate the trigger condition
5. Targeted fix
3. Common Fix Techniques
(1) Prompt Fine-Tuning
TEXT
📖 Display only
Common Fine-Tuning Techniques
├── Add examples: Wrong output format → Add expected output example
├── Add constraints: Output too verbose → Add "concise, no more than N lines"
├── Add steps: Tool not called → Add "Step N: Use XX tool"
├── Add conditions: Incorrect behavior → Add "If X, then Y; otherwise Z"
└── Add negation: Doing things it shouldn't → Add "Do not do X"
(2) Tool Binding Adjustments
TEXT
📖 Display only
Tool Problem Fixes
├── Tool not called: Explicitly specify in flow "Use Read to read file"
├── Wrong tool used: State in prompt "Use Edit not Write to modify files"
├── Insufficient permissions: Check allow/deny configuration in settings.json
└── Tool timeout: Narrow search scope, reduce data volume
(3) Trigger Fixes
TEXT
📖 Display only
Trigger Problem Fixes
├── Not triggering: Keyword too obscure → Add common synonyms
├── False triggering: Keyword too broad → Narrow match scope
├── Conflicts: Multiple Skills competing → Adjust priorities
└── Frequent triggering: Condition too loose → Add AND conditions
4. Debugging Checklist
(1) Skill Debugging Checklist
MARKDOWN
## Debugging Checklist
### Basic Checks
- [ ] File path correct
- [ ] Frontmatter YAML syntax correct
- [ ] name and description filled in
- [ ] triggers configured
### Functional Checks
- [ ] Tool bindings complete
- [ ] Prompt has clear execution steps
- [ ] Has output format example
- [ ] Has constraints and boundary conditions
### Quality Checks
- [ ] Verified on test project
- [ ] Output format stable
- [ ] Tool calls reasonable
- [ ] No security risks
(2) Platform Differences Note
| Note | Claude Code | Cursor | OpenCode |
|---|---|---|---|
| File location | .claude/skills/ |
.cursor/rules/ |
skills/ |
| Auto-load | Supported | Supported | Needs config |
| Trigger syntax | YAML | Markdown frontmatter | Markdown |
| Tool permissions | settings.json | Project config | Config file |
❓ FAQ
Q Skill works inconsistently?
A AI output has inherent randomness. Add constraints and examples in the prompt to reduce output space and improve consistency. Add "please confirm before executing" for critical decisions.
Q How to determine if it's a Skill issue or an AI platform issue?
A Test a simple Skill on the same platform. If the simple Skill also has issues, it's a platform problem; if only the specific Skill has issues, it's a Skill problem.
Q How to prevent problems from recurring after fixing?
A Add constraint conditions in the Skill prompt and verify on test projects. Record fix experience in the CHANGELOG.
📖 Summary
- Three problem categories: loading, execution, quality — each with quick-reference tables
- Three diagnosis methods: layered diagnosis, A/B testing, minimal reproduction
- Fix techniques: Prompt fine-tuning (add examples/constraints/steps/conditions/negation)
- Debugging checklist: Basic checks → Functional checks → Quality checks
📝 Exercises
- Basic (⭐): Follow the debugging checklist to check all your created Skills and fix any issues found.
- Intermediate (⭐⭐): Write a Skill troubleshooting handbook for your team with at least 10 issues and solutions.
- Advanced (⭐⭐⭐): Create a Skill diagnosis Skill that can automatically check other Skills for common issues and provide fix suggestions.
