Skill debugger

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)