Claude-Code-Workflow/.claude/skills/skill-tuning/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
skill-tuning	Universal skill diagnosis and optimization tool. Detect and fix skill execution issues including context explosion, long-tail forgetting, data flow disruption, and agent coordination failures. Supports Gemini CLI for deep analysis. Triggers on "skill tuning", "tune skill", "skill diagnosis", "optimize skill", "skill debug".	Agent, AskUserQuestion, Read, Write, Bash, Glob, Grep, mcp__ace-tool__search_context

Skill Tuning

Autonomous diagnosis and optimization for skill execution issues.

Architecture

┌─────────────────────────────────────────────────────┐
│  Phase 0: Read Specs (mandatory)                    │
│  → problem-taxonomy.md, tuning-strategies.md         │
└─────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│  Orchestrator (state-driven)                         │
│  Read state → Select action → Execute → Update → ✓ │
└─────────────────────────────────────────────────────┘
        ↓                           ↓
┌──────────────────────┐   ┌──────────────────┐
│  Diagnosis Phase     │   │ Gemini CLI       │
│  • Context          │   │ Deep analysis    │
│  • Memory           │   │ (on-demand)      │
│  • DataFlow         │   │                  │
│  • Agent            │   │ Complex issues   │
│  • Docs             │   │ Architecture     │
│  • Token Usage      │   │ Performance      │
└──────────────────────┘   └──────────────────┘
                ↓
        ┌───────────────────┐
        │  Fix & Verify     │
        │  Apply → Re-test  │
        └───────────────────┘

Core Issues Detected

Priority	Problem	Root Cause	Fix Strategy
P0	Authoring Violation	Intermediate files, state bloat, file relay	eliminate_intermediate, minimize_state
P1	Data Flow Disruption	Scattered state, inconsistent formats	state_centralization, schema_enforcement
P2	Agent Coordination	Fragile chains, no error handling	error_wrapping, result_validation
P3	Context Explosion	Unbounded history, full content passing	sliding_window, path_reference
P4	Long-tail Forgetting	Early constraint loss	constraint_injection, checkpoint_restore
P5	Token Consumption	Verbose prompts, state bloat	prompt_compression, lazy_loading

Problem Categories (Detailed Specs)

See specs/problem-taxonomy.md for:

• Detection patterns (regex/checks)
• Severity calculations
• Impact assessments

Tuning Strategies (Detailed Specs)

See specs/tuning-strategies.md for:

• 10+ strategies per category
• Implementation patterns
• Verification methods

Workflow

Step	Action	Orchestrator Decision	Output
1	action-init	status='pending'	Backup, session created
2	action-analyze-requirements	After init	Required dimensions + coverage
3	Diagnosis (6 types)	Focus areas	state.diagnosis.{type}
4	action-gemini-analysis	Critical issues OR user request	Deep findings
5	action-generate-report	All diagnosis complete	state.final_report
6	action-propose-fixes	Issues found	state.proposed_fixes[]
7	action-apply-fix	Pending fixes	Applied + verified
8	action-complete	Quality gates pass	session.status='completed'

Action Reference

Category	Actions	Purpose
Setup	action-init	Initialize backup, session state
Analysis	action-analyze-requirements	Decompose user request via Gemini CLI
Diagnosis	action-diagnose-{context,memory,dataflow,agent,docs,token_consumption}	Detect category-specific issues
Deep Analysis	action-gemini-analysis	Gemini CLI: complex/critical issues
Reporting	action-generate-report	Consolidate findings → final_report
Fixing	action-propose-fixes, action-apply-fix	Generate + apply fixes
Verify	action-verify	Re-run diagnosis, check gates
Exit	action-complete, action-abort	Finalize or rollback

Full action details: phases/actions/

State Management

Single source of truth: .workflow/.scratchpad/skill-tuning-{ts}/state.json

{
  "status": "pending|running|completed|failed",
  "target_skill": { "name": "...", "path": "..." },
  "diagnosis": {
    "context": {...},
    "memory": {...},
    "dataflow": {...},
    "agent": {...},
    "docs": {...},
    "token_consumption": {...}
  },
  "issues": [{"id":"...", "severity":"...", "category":"...", "strategy":"..."}],
  "proposed_fixes": [...],
  "applied_fixes": [...],
  "quality_gate": "pass|fail",
  "final_report": "..."
}

See phases/state-schema.md for complete schema.

Orchestrator Logic

See phases/orchestrator.md for:

• Decision logic (termination checks → action selection)
• State transitions
• Error recovery

Key Principles

1. Problem-First: Diagnosis before any fix
2. Data-Driven: Record traces, token counts, snapshots
3. Iterative: Multiple rounds until quality gates pass
4. Reversible: All changes with backup checkpoints
5. Non-Invasive: Minimal changes, maximum clarity

Usage Examples

# Basic skill diagnosis
/skill-tuning "Fix memory leaks in my skill"

# Deep analysis with Gemini
/skill-tuning "Architecture issues in async workflow"

# Focus on specific areas
/skill-tuning "Optimize token consumption and fix agent coordination"

# Custom issue
/skill-tuning "My skill produces inconsistent outputs"

Output

After completion, review:

• .workflow/.scratchpad/skill-tuning-{ts}/state.json - Full state with final_report
• state.final_report - Markdown summary (in state.json)
• state.applied_fixes - List of applied fixes with verification results

Reference Documents

Document	Purpose
specs/problem-taxonomy.md	Classification + detection patterns
specs/tuning-strategies.md	Fix implementation guide
specs/dimension-mapping.md	Dimension ↔ Spec mapping
specs/quality-gates.md	Quality verification criteria
phases/orchestrator.md	Workflow orchestration
phases/state-schema.md	State structure definition
phases/actions/	Individual action implementations