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)

Document Purpose Priority

specs/skill-authoring-principles.md 首要准则：简洁高效、去除存储、上下文流转 P0

specs/problem-taxonomy.md Problem classification and detection patterns P0

specs/tuning-strategies.md Fix strategies for each problem type P0

specs/dimension-mapping.md Dimension to Spec mapping rules P0

specs/quality-gates.md Quality thresholds and verification criteria P1

Templates (Reference)

Document Purpose

templates/diagnosis-report.md Diagnosis report structure

templates/fix-proposal.md Fix proposal format

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};

// Simplified: Only backups dir needed, diagnosis results go into state.json 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

Document Purpose

phases/orchestrator.md Orchestrator decision logic

phases/state-schema.md State structure definition

phases/actions/action-init.md Initialize tuning session

phases/actions/action-analyze-requirements.md Requirement analysis (NEW)

phases/actions/action-diagnose-context.md Context explosion diagnosis

phases/actions/action-diagnose-memory.md Long-tail forgetting diagnosis

phases/actions/action-diagnose-dataflow.md Data flow diagnosis

phases/actions/action-diagnose-agent.md Agent coordination diagnosis

phases/actions/action-diagnose-docs.md Documentation structure diagnosis

phases/actions/action-diagnose-token-consumption.md Token consumption diagnosis

phases/actions/action-generate-report.md Report generation

phases/actions/action-propose-fixes.md Fix proposal

phases/actions/action-apply-fix.md Fix application

phases/actions/action-verify.md Verification

phases/actions/action-complete.md Finalization

specs/problem-taxonomy.md Problem classification

specs/tuning-strategies.md Fix strategies

specs/dimension-mapping.md Dimension to Spec mapping (NEW)

specs/quality-gates.md Quality criteria