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
- Problem-First: Diagnosis before any fix
- Data-Driven: Record traces, token counts, snapshots
- Iterative: Multiple rounds until quality gates pass
- Reversible: All changes with backup checkpoints
- 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 |
1---2name: skill-tuning-43description: 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".4allowed-tools: Task, AskUserQuestion, Read, Write, Bash, Glob, Grep, mcp__ace-tool__search_context5metadata:6 source: https://skillmd.com/skills/catlog22/skill-tuning-47---89# Skill Tuning1011Autonomous diagnosis and optimization for skill execution issues.1213## Architecture1415```16┌─────────────────────────────────────────────────────┐17│ Phase 0: Read Specs (mandatory) │18│ → problem-taxonomy.md, tuning-strategies.md │19└─────────────────────────────────────────────────────┘20 ↓21┌─────────────────────────────────────────────────────┐22│ Orchestrator (state-driven) │23│ Read state → Select action → Execute → Update → ✓ │24└─────────────────────────────────────────────────────┘25 ↓ ↓26┌──────────────────────┐ ┌──────────────────┐27│ Diagnosis Phase │ │ Gemini CLI │28│ • Context │ │ Deep analysis │29│ • Memory │ │ (on-demand) │30│ • DataFlow │ │ │31│ • Agent │ │ Complex issues │32│ • Docs │ │ Architecture │33│ • Token Usage │ │ Performance │34└──────────────────────┘ └──────────────────┘35 ↓36 ┌───────────────────┐37 │ Fix & Verify │38 │ Apply → Re-test │39 └───────────────────┘40```4142## Core Issues Detected4344| Priority | Problem | Root Cause | Fix Strategy |45|----------|---------|-----------|--------------|46| **P0** | Authoring Violation | Intermediate files, state bloat, file relay | eliminate_intermediate, minimize_state |47| **P1** | Data Flow Disruption | Scattered state, inconsistent formats | state_centralization, schema_enforcement |48| **P2** | Agent Coordination | Fragile chains, no error handling | error_wrapping, result_validation |49| **P3** | Context Explosion | Unbounded history, full content passing | sliding_window, path_reference |50| **P4** | Long-tail Forgetting | Early constraint loss | constraint_injection, checkpoint_restore |51| **P5** | Token Consumption | Verbose prompts, state bloat | prompt_compression, lazy_loading |5253## Problem Categories (Detailed Specs)5455See [specs/problem-taxonomy.md](specs/problem-taxonomy.md) for:56- Detection patterns (regex/checks)57- Severity calculations58- Impact assessments5960## Tuning Strategies (Detailed Specs)6162See [specs/tuning-strategies.md](specs/tuning-strategies.md) for:63- 10+ strategies per category64- Implementation patterns65- Verification methods6667## Workflow6869| Step | Action | Orchestrator Decision | Output |70|------|--------|----------------------|--------|71| 1 | `action-init` | status='pending' | Backup, session created |72| 2 | `action-analyze-requirements` | After init | Required dimensions + coverage |73| 3 | Diagnosis (6 types) | Focus areas | state.diagnosis.{type} |74| 4 | `action-gemini-analysis` | Critical issues OR user request | Deep findings |75| 5 | `action-generate-report` | All diagnosis complete | state.final_report |76| 6 | `action-propose-fixes` | Issues found | state.proposed_fixes[] |77| 7 | `action-apply-fix` | Pending fixes | Applied + verified |78| 8 | `action-complete` | Quality gates pass | session.status='completed' |7980## Action Reference8182| Category | Actions | Purpose |83|----------|---------|---------|84| **Setup** | action-init | Initialize backup, session state |85| **Analysis** | action-analyze-requirements | Decompose user request via Gemini CLI |86| **Diagnosis** | action-diagnose-{context,memory,dataflow,agent,docs,token_consumption} | Detect category-specific issues |87| **Deep Analysis** | action-gemini-analysis | Gemini CLI: complex/critical issues |88| **Reporting** | action-generate-report | Consolidate findings → final_report |89| **Fixing** | action-propose-fixes, action-apply-fix | Generate + apply fixes |90| **Verify** | action-verify | Re-run diagnosis, check gates |91| **Exit** | action-complete, action-abort | Finalize or rollback |9293Full action details: [phases/actions/](phases/actions/)9495## State Management9697**Single source of truth**: `.workflow/.scratchpad/skill-tuning-{ts}/state.json`9899```json100{101 "status": "pending|running|completed|failed",102 "target_skill": { "name": "...", "path": "..." },103 "diagnosis": {104 "context": {...},105 "memory": {...},106 "dataflow": {...},107 "agent": {...},108 "docs": {...},109 "token_consumption": {...}110 },111 "issues": [{"id":"...", "severity":"...", "category":"...", "strategy":"..."}],112 "proposed_fixes": [...],113 "applied_fixes": [...],114 "quality_gate": "pass|fail",115 "final_report": "..."116}117```118119See [phases/state-schema.md](phases/state-schema.md) for complete schema.120121## Orchestrator Logic122123See [phases/orchestrator.md](phases/orchestrator.md) for:124- Decision logic (termination checks → action selection)125- State transitions126- Error recovery127128## Key Principles1291301. **Problem-First**: Diagnosis before any fix1312. **Data-Driven**: Record traces, token counts, snapshots1323. **Iterative**: Multiple rounds until quality gates pass1334. **Reversible**: All changes with backup checkpoints1345. **Non-Invasive**: Minimal changes, maximum clarity135136## Usage Examples137138```bash139# Basic skill diagnosis140/skill-tuning "Fix memory leaks in my skill"141142# Deep analysis with Gemini143/skill-tuning "Architecture issues in async workflow"144145# Focus on specific areas146/skill-tuning "Optimize token consumption and fix agent coordination"147148# Custom issue149/skill-tuning "My skill produces inconsistent outputs"150```151152## Output153154After completion, review:155- `.workflow/.scratchpad/skill-tuning-{ts}/state.json` - Full state with final_report156- `state.final_report` - Markdown summary (in state.json)157- `state.applied_fixes` - List of applied fixes with verification results158159## Reference Documents160161| Document | Purpose |162|----------|---------|163| [specs/problem-taxonomy.md](specs/problem-taxonomy.md) | Classification + detection patterns |164| [specs/tuning-strategies.md](specs/tuning-strategies.md) | Fix implementation guide |165| [specs/dimension-mapping.md](specs/dimension-mapping.md) | Dimension ↔ Spec mapping |166| [specs/quality-gates.md](specs/quality-gates.md) | Quality verification criteria |167| [phases/orchestrator.md](phases/orchestrator.md) | Workflow orchestration |168| [phases/state-schema.md](phases/state-schema.md) | State structure definition |169| [phases/actions/](phases/actions/) | Individual action implementations |