| name | skill-debugger |
| description | Deep dual-model debugging of AI skills using reasoning model and fast synthesis model. Use when asked to debug a skill, find bugs in a skill, review a skill for issues, fix a broken skill, or audit a skill's quality. Also use when a skill is not working correctly or producing unexpected results. |
Skill Debugger
Debug AI skills using two complementary AI models in parallel: reasoning model (deep code reasoning, security, logic bugs) and fast synthesis model (structural integrity, integration quality, trigger accuracy). Findings are merged by consensus — issues confirmed by both models get elevated confidence.
When to Use
- A skill is broken, crashing, or producing wrong results
- Before deploying a new or modified skill
- To audit an existing skill for hidden bugs
- When a skill triggers at the wrong time or fails to trigger
- After significant changes to a skill's scripts or instructions
Quick Start
python3 /home/ubuntu/skills/skill-debugger/scripts/debug_skill.py <skill-name>
Workflow
Step 1: Run the Debugger
Standard analysis (fast, covers most issues):
python3 /home/ubuntu/skills/skill-debugger/scripts/debug_skill.py <skill-name>
Deep analysis (extended checks for race conditions, resource leaks, edge cases):
python3 /home/ubuntu/skills/skill-debugger/scripts/debug_skill.py <skill-name> --deep
Single-model mode (when one API is unavailable):
python3 /home/ubuntu/skills/skill-debugger/scripts/debug_skill.py <skill-name> --model claude
python3 /home/ubuntu/skills/skill-debugger/scripts/debug_skill.py <skill-name> --model fast
Debug by path (for skills not in the standard directory):
python3 /home/ubuntu/skills/skill-debugger/scripts/debug_skill.py /path/to/skill-dir
Step 2: Review the Report
The script generates DEBUG_REPORT.md inside the skill directory with:
- Model status (which models responded successfully)
- Overall health assessment (healthy / degraded / broken)
- Findings summary table sorted by severity
- Detailed findings with problematic code, explanation, and exact fix
- Consensus badges showing which findings both models agree on
Raw JSON data is saved to .debug_raw.json for programmatic access.
Step 3: Apply Fixes
Read the DEBUG_REPORT.md and apply fixes in order of severity (critical first). Each finding includes:
- The exact problematic code to find
- Why it's a problem with a concrete failure scenario
- The exact replacement code or instruction
After applying fixes, re-run the debugger to verify:
python3 /home/ubuntu/skills/skill-debugger/scripts/debug_skill.py <skill-name>
Analysis Dimensions
The debugger examines five dimensions, with each model contributing its strengths:
| Dimension | Reasoning Model Focus | Fast Model Focus |
|---|
| Structural | File existence, path correctness | Frontmatter quality, trigger accuracy |
| Scripts | Logic bugs, security, edge cases | Import errors, argument parsing, output format |
| Robustness | Race conditions, resource leaks, memory | Missing error handling, hardcoded paths |
| Security | Command injection, path traversal, key exposure | Input validation, unsafe deserialization |
| Integration | API contract violations | platform-specific conventions, instruction clarity |
Prompt Engineering
The debugger uses elite prompt engineering techniques documented in references/prompt_engineering.md. Key techniques: role priming, chain-of-thought enforcement, metacognitive verification ("Would I bet $100?"), negative prompting (explicit exclusion list), and severity calibration with concrete criteria.
Requirements
OPENROUTER_API_KEY environment variable (for reasoning model)OPENAI_API_KEY environment variable (for fast synthesis model)- Python packages:
requests, openai (auto-installed if missing)
