skill-tuning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Tuning

Skill调优

Autonomous diagnosis and optimization for skill execution issues.

针对Skill执行问题的自主诊断与优化。

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  │
        └───────────────────┘

┌─────────────────────────────────────────────────────┐
│  阶段0：读取规范（必填）                    │
│  → problem-taxonomy.md, tuning-strategies.md         │
└─────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────┐
│  编排器（状态驱动）                         │
│  读取状态 → 选择操作 → 执行 → 更新 → ✓ │
└─────────────────────────────────────────────────────┘
        ↓                           ↓
┌──────────────────────┐   ┌──────────────────┐
│  诊断阶段     │   │ Gemini CLI       │
│  • 上下文          │   │ 深度分析（按需）      │
│  • 内存           │   │                  │
│  • 数据流         │   │ 复杂问题   │
│  • Agent            │   │ 架构     │
│  • 文档             │   │ 性能      │
│  • Token使用      │   │                  │
└──────────────────────┘   └──────────────────┘
                ↓
        ┌───────────────────┐
        │  修复与验证     │
        │  应用 → 重新测试  │
        └───────────────────┘

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

优先级	问题	根本原因	修复策略
P0	编写违规	中间文件、状态膨胀、文件传递	移除中间文件、最小化状态
P1	数据流中断	状态分散、格式不一致	状态集中化、模式强制
P2	Agent协调问题	脆弱的调用链、无错误处理	错误包装、结果验证
P3	上下文膨胀	无限制历史记录、完整内容传递	滑动窗口、路径引用
P4	长尾遗忘	早期约束丢失	约束注入、检查点恢复
P5	Token消耗过高	冗长提示词、状态膨胀	提示词压缩、懒加载

Problem Categories (Detailed Specs)

问题分类（详细规范）

See specs/problem-taxonomy.md for:

Detection patterns (regex/checks)
Severity calculations
Impact assessments

查看 specs/problem-taxonomy.md 了解：

检测模式（正则/检查规则）
严重程度计算
影响评估

Tuning Strategies (Detailed Specs)

调优策略（详细规范）

See specs/tuning-strategies.md for:

10+ strategies per category
Implementation patterns
Verification methods

查看 specs/tuning-strategies.md 了解：

每个分类下的10+种策略
实现模式
验证方法

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'

步骤	操作	编排器决策	输出
1	`action-init`	状态='待处理'	备份文件、会话已创建
2	`action-analyze-requirements`	初始化完成后	所需分析维度 + 覆盖范围
3	诊断（6种类型）	聚焦重点领域	state.diagnosis.{type}
4	`action-gemini-analysis`	存在关键问题或用户请求	深度分析结果
5	`action-generate-report`	所有诊断完成后	state.final_report
6	`action-propose-fixes`	检测到问题时	state.proposed_fixes[]
7	`action-apply-fix`	存在待修复问题时	修复已应用 + 验证通过
8	`action-complete`	通过质量门	session.status='已完成'

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/

分类	操作	用途
设置	action-init	初始化备份、会话状态
分析	action-analyze-requirements	通过Gemini CLI分解用户请求
诊断	action-diagnose-{context,memory,dataflow,agent,docs,token_consumption}	检测特定分类的问题
深度分析	action-gemini-analysis	Gemini CLI：处理复杂/关键问题
报告	action-generate-report	整合分析结果 → final_report
修复	action-propose-fixes, action-apply-fix	生成并应用修复方案
验证	action-verify	重新运行诊断、检查质量门
退出	action-complete, action-abort	完成或回滚操作

完整操作详情：phases/actions/

State Management

状态管理

Single source of truth:

.workflow/.scratchpad/skill-tuning-{ts}/state.json

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.

唯一可信数据源：

.workflow/.scratchpad/skill-tuning-{ts}/state.json

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": "..."
}

完整状态架构请查看 phases/state-schema.md。

Orchestrator Logic

核心原则

See phases/orchestrator.md for:

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

问题优先：先诊断再进行任何修复
数据驱动：记录跟踪信息、Token计数、快照
迭代式：多轮执行直到通过质量门
可回滚：所有更改都带有备份检查点
非侵入式：最小化代码更改，最大化清晰度

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

bash

undefined

Usage Examples

基础Skill诊断

bash

undefined

/skill-tuning "Fix memory leaks in my skill"

Basic skill diagnosis

结合Gemini进行深度分析

/skill-tuning "Fix memory leaks in my skill"

/skill-tuning "Architecture issues in async workflow"

Deep analysis with Gemini

聚焦特定领域

/skill-tuning "Architecture issues in async workflow"

/skill-tuning "Optimize token consumption and fix agent coordination"

Focus on specific areas

自定义问题

/skill-tuning "Optimize token consumption and fix agent coordination"

/skill-tuning "My skill produces inconsistent outputs"

undefined

Custom issue

输出

/skill-tuning "My skill produces inconsistent outputs"

undefined

完成后，查看以下内容：

.workflow/.scratchpad/skill-tuning-{ts}/state.json

- 包含最终报告的完整状态文件

```
state.final_report
```
- Markdown格式的分析摘要（位于state.json中）
```
state.applied_fixes
```
- 已应用修复的列表及验证结果

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

文档	用途
specs/problem-taxonomy.md	问题分类 + 检测模式
specs/tuning-strategies.md	修复方案实施指南
specs/dimension-mapping.md	分析维度 ↔ 规范映射
specs/quality-gates.md	质量验证标准
phases/orchestrator.md	工作流编排逻辑
phases/state-schema.md	状态结构定义
phases/actions/	单个操作的具体实现

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

—