System Augmentor for Claude Code

Identifies what your Claude Code system cannot do, finds solutions, evaluates them rigorously, and installs the best one. A meta-skill that makes all other skills better.

When to Use

• •You want to extend Claude Code with new capabilities (MCP servers, CLI tools, skills)
• •You suspect something is missing but aren't sure what
• •You want to compare competing solutions before installing
• •You want a full audit of your system's strengths and gaps

When NOT to Use

• •You already know exactly what to install (just install it)
• •You want to debug an existing skill (fix it directly)
• •You want to modify project code (use normal Claude Code)

Invocation

/improve                     # Full system audit
/improve web scraping        # Focused audit on web scraping capability
/improve paper search        # Focused audit on academic paper search
/improve testing             # Focused audit on testing tools

The Four Phases

User: /improve [focus]
     |
     v
[Phase 1: Deep System Audit]
  - system_scanner.py → filesystem inventory
  - gap_analyzer.py → structural gap detection
  - Claude reasoning → capability-level gaps
  - STOP: present findings, ask which gaps to research
     |
     v
[Phase 2: Online Research]
  - WebSearch queries from search-templates.json
  - WebFetch promising results
  - Ranked candidate list per gap
  - STOP: present candidates, ask which to debate
     |
     v
[Phase 3: Evaluate via /debate]  (optional — skip for trivial fixes)
  - AskUserQuestion: thinking token budget (small/medium/high)
  - Compose question from debate-question-template.md
  - Call Skill(skill="debate", args="[TOKEN_BUDGET: X]\n\n<question>")
  - Full protocol: 5 solvers, 4 debaters, RWEA scoring
  - STOP: present winner, ask permission to implement
     |
     v
[Phase 4: Implement]
  - Execute chosen solution
  - Follow safety checklist
  - Test the implementation
  - Report what changed

Phase Details

Phase 1: Deep System Audit

1. •Run system_scanner.py --output-json --pretty to inventory the filesystem
2. •Read discovered files to understand current capabilities
3. •Run gap_analyzer.py --manifest <path> --pretty to detect structural gaps
4. •Apply reasoning to identify capability-level gaps not caught by rules
5. •Present findings to user with severity ratings

Phase 2: Online Research

For each user-approved gap:

1. •Load query templates from settings/search-templates.json
2. •Run 2-4 WebSearch queries per gap, substituting keywords
3. •WebFetch top results to extract: description, install method, dependencies, maintenance status
4. •Produce ranked candidate list (2-4 candidates per gap)

Phase 3: Evaluate via /debate

For non-trivial choices (2+ viable candidates):

1. •Ask user for thinking token budget via AskUserQuestion (small/medium/high)
2. •Compose question using references/debate-question-template.md
3. •Fill in context from Phase 1 manifest and Phase 2 candidates
4. •Call Skill(skill="debate", args="[TOKEN_BUDGET: <selection>]\n\n<composed question>")
5. •Debate runs full protocol (5 solvers, 4 debaters, RWEA) and returns winner

Skip the debate when:

• •Only one candidate exists
• •Solution is a simple install command
• •Gap severity is LOW
• •User says "just do it"

Phase 4: Implement

Execute the winning solution following the safety checklist:

• •Check if target already exists before creating
• •Never write API keys directly — create .env.example templates
• •Test the installation (run a smoke test)
• •Report what was created/modified

File Structure

~/.claude/commands/improve.md                  # Slash command (orchestration)
~/.claude/skills/system-augmentor/
  SKILL.md                                     # This file
  scripts/
    system_scanner.py                          # Filesystem inventory scanner
    gap_analyzer.py                            # Structural gap detector
  settings/
    scan-targets.json                          # Configurable scan paths & tools
    search-templates.json                      # WebSearch query patterns per category
  references/
    gap-taxonomy.md                            # Gap classification schema
    debate-question-template.md                # Template for /debate questions

Safety Rules

1. •Idempotent: Always check existence before creating files/dirs
2. •No secrets: Never write API keys into files — create .env.example templates
3. •User consent: Stop between every phase for user confirmation
4. •Reversible: Prefer solutions that can be easily uninstalled
5. •Respect permissions: Check settings.local.json allowlist before adding Bash permissions
6. •Minimal scope: Only install what's needed for the identified gap