---

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

Skill Tuning

Universal skill diagnosis and optimization tool that identifies and resolves skill execution problems through iterative multi-agent analysis.

Architecture Overview

Copy┌─────────────────────────────────────────────────────────────────────────────┐
│  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 (自动检测)

General Optimization Areas (按需分析 via Gemini CLI)

Key Design Principles

1. Problem-First Diagnosis: Systematic identification before any fix attempt
2. Data-Driven Analysis: Record execution traces, token counts, state snapshots
3. Iterative Refinement: Multiple tuning rounds until quality gates pass
4. Non-Destructive: All changes are reversible with backup checkpoints
5. Agent Coordination: Use specialized sub-agents for each diagnosis type
6. Gemini CLI On-Demand: Deep analysis via CLI for complex/custom issues

---

Gemini CLI Integration

根据用户需求动态调用 Gemini CLI 进行深度分析。

Trigger Conditions

CLI Command Template

Copyccw 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

Copyccw 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

Copyccw 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

Copyccw 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

Copy┌─────────────────────────────────────────────────────────────────────────────┐
│  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

Copyconst timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, '');
const workDir = `.workflow/.scratchpad/skill-tuning-${timestamp}`;

// Simplified: Only backups dir needed, diagnosis results go into state.json
Bash(`mkdir -p "${workDir}/backups"`);

Output Structure

Copy.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