| name | skill-tuning |
| description | 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". |
| allowed-tools | Task, AskUserQuestion, Read, Write, Bash, Glob, Grep, mcp__ace-tool__search_context |
Resource Map
ๅบๅ่ทฏๅพ: .claude/skills/code-quality-specialist/references/domains/skill-quality/tuning/
tuning/
โโโ phases/
โ โโโ actions/
โ โ โโโ action-abort.md
โ โ โโโ action-analyze-requirements.md
โ โ โโโ action-apply-fix.md
โ โ โโโ action-complete.md
โ โ โโโ action-diagnose-agent.md
โ โ โโโ action-diagnose-context.md
โ โ โโโ action-diagnose-dataflow.md
โ โ โโโ action-diagnose-docs.md
โ โ โโโ action-diagnose-memory.md
โ โ โโโ action-diagnose-token-consumption.md
โ โ โโโ action-gemini-analysis.md
โ โ โโโ action-generate-report.md
โ โ โโโ action-init.md
โ โ โโโ action-propose-fixes.md
โ โ โโโ action-verify.md
โ โโโ orchestrator.md
โ โโโ state-schema.md
โโโ specs/
โ โโโ category-mappings.json
โ โโโ dimension-mapping.md
โ โโโ problem-taxonomy.md
โ โโโ quality-gates.md
โ โโโ skill-authoring-principles.md
โ โโโ tuning-strategies.md
โโโ templates/
โ โโโ diagnosis-report.md
โ โโโ fix-proposal.md
โโโ SKILL.md
Skill Tuning
Universal skill diagnosis and optimization tool that identifies and resolves skill execution problems through iterative multi-agent analysis.
Architecture Overview
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Skill Tuning Architecture (Autonomous Mode + Gemini CLI) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ
โ โ ๏ธ Phase 0: Specification โ ้
่ฏป่ง่ + ็่งฃ็ฎๆ skill ็ปๆ (ๅผบๅถๅ็ฝฎ) โ
โ Study โ
โ โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Orchestrator (็ถๆ้ฉฑๅจๅณ็ญ) โ โ
โ โ ่ฏปๅ่ฏๆญ็ถๆ โ ้ๆฉไธไธๆญฅๅจไฝ โ ๆง่ก โ ๆดๆฐ็ถๆ โ ๅพช็ฏ็ดๅฐๅฎๆ โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ
โ โโโโโโโโโโโโโโฌโโโโโโโโโโโโผโโโโโโโโโโโโฌโโโโโโโโโโโโโฌโโโโโโโโโโโโโ โ
โ โ โ โ โ โ โ โ
โ โโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโ โโโโโโโโโโ โโโโโโโโโโโ โ
โ โ Init โโ โ Analyze โโ โDiagnose โ โDiagnoseโ โDiagnoseโ โ Gemini โ โ
โ โ โ โRequiremtsโ โ Context โ โ Memory โ โDataFlowโ โAnalysis โ โ
โ โโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโ โโโโโโโโโโ โโโโโโโโโโ โโโโโโโโโโโ โ
โ โ โ โ โ โ โ
โ โ โโโโโโโโโโโโโดโโโโโโโโโโโโดโโโโโโโโโโโโโ โ
โ โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Requirement Analysis (NEW) โ โ
โ โ โข Phase 1: ็ปดๅบฆๆ่งฃ (Gemini CLI) - ๅไธๆ่ฟฐ โ ๅคไธชๅ
ณๆณจ็ปดๅบฆ โ โ
โ โ โข Phase 2: Spec ๅน้
- ๆฏไธช็ปดๅบฆ โ taxonomy + strategy โ โ
โ โ โข Phase 3: ่ฆ็ๅบฆ่ฏไผฐ - ไปฅ"ๆไฟฎๅค็ญ็ฅ"ไธบๆปก่ถณๆ ๅ โ โ
โ โ โข Phase 4: ๆญงไนๆฃๆต - ่ฏๅซๅคไนๆงๆ่ฟฐ๏ผๅฟ
่ฆๆถ่ฏทๆฑๆพๆธ
โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ
โ โโโโโโโโโโโโโโโโโโโโ โ
โ โ Apply Fixes + โ โ
โ โ Verify Results โ โ
โ โโโโโโโโโโโโโโโโโโโโ โ
โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Gemini CLI Integration โ โ
โ โ ๆ นๆฎ็จๆท้ๆฑๅจๆ่ฐ็จ gemini cli ่ฟ่กๆทฑๅบฆๅๆ: โ โ
โ โ โข ้ๆฑ็ปดๅบฆๆ่งฃ (requirement decomposition) โ โ
โ โ โข ๅคๆ้ฎ้ขๅๆ (prompt engineering, architecture review) โ โ
โ โ โข ไปฃ็ ๆจกๅผ่ฏๅซ (pattern matching, anti-pattern detection) โ โ
โ โ โข ไฟฎๅค็ญ็ฅ็ๆ (fix generation, refactoring suggestions) โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Problem Domain
Based on comprehensive analysis, skill-tuning addresses core skill issues and general optimization areas:
Core Skill Issues (่ชๅจๆฃๆต)
| Priority | Problem | Root Cause | Solution Strategy |
|---|
| P0 | Authoring Principles Violation | ไธญ้ดๆไปถๅญๅจ, State่จ่, ๆไปถไธญ่ฝฌ | eliminate_intermediate_files, minimize_state, context_passing |
| P1 | Data Flow Disruption | Scattered state, inconsistent formats | state_centralization, schema_enforcement |
| P2 | Agent Coordination | Fragile call chains, merge complexity | error_wrapping, result_validation |
| P3 | Context Explosion | Token accumulation, multi-turn bloat | sliding_window, context_summarization |
| P4 | Long-tail Forgetting | Early constraint loss | constraint_injection, checkpoint_restore |
| P5 | Token Consumption | Verbose prompts, excessive state, redundant I/O | prompt_compression, lazy_loading, output_minimization |
General Optimization Areas (ๆ้ๅๆ via Gemini CLI)
| Category | Issues | Gemini Analysis Scope |
|---|
| Prompt Engineering | ๆจก็ณๆไปค, ่พๅบๆ ผๅผไธไธ่ด, ๅนป่ง้ฃ้ฉ | ๆ็คบ่ฏไผๅ, ็ปๆๅ่พๅบ่ฎพ่ฎก |
| Architecture | ้ถๆฎตๅๅไธๅ็, ไพ่ตๆททไนฑ, ๆฉๅฑๆงๅทฎ | ๆถๆๅฎกๆฅ, ๆจกๅๅๅปบ่ฎฎ |
| Performance | ๆง่กๆ
ข, Tokenๆถ่้ซ, ้ๅค่ฎก็ฎ | ๆง่ฝๅๆ, ็ผๅญ็ญ็ฅ |
| Error Handling | ้่ฏฏๆขๅคไธๅฝ, ๆ ้็บง็ญ็ฅ, ๆฅๅฟไธ่ถณ | ๅฎน้่ฎพ่ฎก, ๅฏ่งๆตๆงๅขๅผบ |
| Output Quality | ่พๅบไธ็จณๅฎ, ๆ ผๅผๆผ็งป, ่ดจ้ๆณขๅจ | ่ดจ้้จๆง, ้ช่ฏๆบๅถ |
| User Experience | ไบคไบไธๆต็
, ๅ้ฆไธๆธ
ๆฐ, ่ฟๅบฆไธๅฏ่ง | UXไผๅ, ่ฟๅบฆ่ฟฝ่ธช |
Key Design Principles
- Problem-First Diagnosis: Systematic identification before any fix attempt
- Data-Driven Analysis: Record execution traces, token counts, state snapshots
- Iterative Refinement: Multiple tuning rounds until quality gates pass
- Non-Destructive: All changes are reversible with backup checkpoints
- Agent Coordination: Use specialized sub-agents for each diagnosis type
- Gemini CLI On-Demand: Deep analysis via CLI for complex/custom issues
Gemini CLI Integration
ๆ นๆฎ็จๆท้ๆฑๅจๆ่ฐ็จ Gemini CLI ่ฟ่กๆทฑๅบฆๅๆใ
Trigger Conditions
| Condition | Action | CLI Mode |
|---|
| ็จๆทๆ่ฟฐๅคๆ้ฎ้ข | ่ฐ็จ Gemini ๅๆ้ฎ้ขๆ นๅ | analysis |
| ่ชๅจ่ฏๆญๅ็ฐ critical ้ฎ้ข | ่ฏทๆฑๆทฑๅบฆๅๆ็กฎ่ฎค | analysis |
| ็จๆท่ฏทๆฑๆถๆๅฎกๆฅ | ๆง่กๆถๆๅๆ | analysis |
| ้่ฆ็ๆไฟฎๅคไปฃ็ | ็ๆไฟฎๅคๆๆก | write |
| ๆ ๅ็ญ็ฅไธ้็จ | ่ฏทๆฑๅฎๅถๅ็ญ็ฅ | analysis |
CLI Command Template
ccw cli -p "
PURPOSE: ${purpose}
TASK: ${task_steps}
MODE: ${mode}
CONTEXT: @${skill_path}/**/*
EXPECTED: ${expected_output}
RULES: $(cat ~/.claude/workflows/cli-templates/protocols/${mode}-protocol.md) | ${constraints}
" --tool gemini --mode ${mode} --cd ${skill_path}
Analysis Types
1. Problem Root Cause Analysis
ccw cli -p "
PURPOSE: Identify root cause of skill execution issue: ${user_issue_description}
TASK: โข Analyze skill structure and phase flow โข Identify anti-patterns โข Trace data flow issues
MODE: analysis
CONTEXT: @**/*.md
EXPECTED: JSON with { root_causes: [], patterns_found: [], recommendations: [] }
RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md) | Focus on execution flow
" --tool gemini --mode analysis
2. Architecture Review
ccw cli -p "
PURPOSE: Review skill architecture for scalability and maintainability
TASK: โข Evaluate phase decomposition โข Check state management patterns โข Assess agent coordination
MODE: analysis
CONTEXT: @**/*.md
EXPECTED: Architecture assessment with improvement recommendations
RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md) | Focus on modularity
" --tool gemini --mode analysis
3. Fix Strategy Generation
ccw cli -p "
PURPOSE: Generate fix strategy for issue: ${issue_id} - ${issue_description}
TASK: โข Analyze issue context โข Design fix approach โข Generate implementation plan
MODE: analysis
CONTEXT: @**/*.md
EXPECTED: JSON with { strategy: string, changes: [], verification_steps: [] }
RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md) | Minimal invasive changes
" --tool gemini --mode analysis
Mandatory Prerequisites
CRITICAL: Read these documents before executing any action.
Core Specs (Required)
Templates (Reference)
Execution Flow
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Phase 0: Specification Study (ๅผบๅถๅ็ฝฎ - ็ฆๆญข่ทณ่ฟ) โ
โ โ Read: specs/problem-taxonomy.md (้ฎ้ขๅ็ฑป) โ
โ โ Read: specs/tuning-strategies.md (่ฐไผ็ญ็ฅ) โ
โ โ Read: specs/dimension-mapping.md (็ปดๅบฆๆ ๅฐ่งๅ) โ
โ โ Read: Target skill's SKILL.md and phases/*.md โ
โ โ Output: ๅ
ๅ่ง่๏ผ็่งฃ็ฎๆ skill ็ปๆ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ action-init: Initialize Tuning Session โ
โ โ Create work directory: .workflow/.scratchpad/skill-tuning-{timestamp} โ
โ โ Initialize state.json with target skill info โ
โ โ Create backup of target skill files โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ action-analyze-requirements: Requirement Analysis โ
โ โ Phase 1: ็ปดๅบฆๆ่งฃ (Gemini CLI) - ๅไธๆ่ฟฐ โ ๅคไธชๅ
ณๆณจ็ปดๅบฆ โ
โ โ Phase 2: Spec ๅน้
- ๆฏไธช็ปดๅบฆ โ taxonomy + strategy โ
โ โ Phase 3: ่ฆ็ๅบฆ่ฏไผฐ - ไปฅ"ๆไฟฎๅค็ญ็ฅ"ไธบๆปก่ถณๆ ๅ โ
โ โ Phase 4: ๆญงไนๆฃๆต - ่ฏๅซๅคไนๆงๆ่ฟฐ๏ผๅฟ
่ฆๆถ่ฏทๆฑๆพๆธ
โ
โ โ Output: state.json (requirement_analysis field) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ action-diagnose-*: Diagnosis Actions (context/memory/dataflow/agent/docs/ โ
โ token_consumption) โ
โ โ Execute pattern-based detection for each category โ
โ โ Output: state.json (diagnosis.{category} field) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ action-generate-report: Consolidated Report โ
โ โ Generate markdown summary from state.diagnosis โ
โ โ Prioritize issues by severity โ
โ โ Output: state.json (final_report field) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ action-propose-fixes: Fix Proposal Generation โ
โ โ Generate fix strategies for each issue โ
โ โ Create implementation plan โ
โ โ Output: state.json (proposed_fixes field) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ action-apply-fix: Apply Selected Fix โ
โ โ User selects fix to apply โ
โ โ Execute fix with backup โ
โ โ Update state with fix result โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ action-verify: Verification โ
โ โ Re-run affected diagnosis โ
โ โ Check quality gates โ
โ โ Update iteration count โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ action-complete: Finalization โ
โ โ Set status='completed' โ
โ โ Final report already in state.json (final_report field) โ
โ โ Output: state.json (final) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Directory Setup
const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, '');
const workDir = `.workflow/.scratchpad/skill-tuning-${timestamp}`;
Bash(`mkdir -p "${workDir}/backups"`);
Output Structure
.workflow/.scratchpad/skill-tuning-{timestamp}/
โโโ state.json # Single source of truth (all results consolidated)
โ โโโ diagnosis.* # All diagnosis results embedded
โ โโโ issues[] # Found issues
โ โโโ proposed_fixes[] # Fix proposals
โ โโโ final_report # Markdown summary (on completion)
โโโ backups/
โโโ {skill-name}-backup/ # Original skill files backup
Token Optimization: All outputs consolidated into state.json. No separate diagnosis files or report files.
State Schema
่ฏฆ็ป็ถๆ็ปๆๅฎไน่ฏทๅ้
phases/state-schema.mdใ
ๆ ธๅฟ็ถๆๅญๆฎต๏ผ
status: ๅทฅไฝๆต็ถๆ (pending/running/completed/failed)target_skill: ็ฎๆ skill ไฟกๆฏdiagnosis: ๅ็ปดๅบฆ่ฏๆญ็ปๆissues: ๅ็ฐ็้ฎ้ขๅ่กจproposed_fixes: ๅปบ่ฎฎ็ไฟฎๅคๆนๆก
Reference Documents
