optimize-skill

name	optimize-skill
description	迭代优化 Claude Code Skill 的质量。当用户想要改进 skill 的提示词、通过目标内容迭代优化 skill、自动评估和优化时触发。

optimize-skill

迭代优化 Claude Code Skill 的质量，采用类似机器学习训练循环的方式：

1. 读取目标内容（期望输出）
2. 调用子代理执行目标 skill
3. LLM 评估输出质量
4. 生成优化建议
5. 应用优化到 skill 提示词
6. 重复直到达到评估阈值

核心特性

• 迭代优化循环: 自动多轮优化，直到满足评估标准
• 子代理执行: 使用 Agent 工具隔离执行目标 skill
• LLM 评估: 自动评估知识点覆盖度和内容深度
• 完整记录: 保留每轮迭代的详细历史

使用方式

基础用法

# 迭代优化 spec-analyzer，指定目标内容和测试仓库
/optimize-skill spec-analyzer --target ./target.md --repo https://github.com/xxx/yyy

# 使用内联目标内容
/optimize-skill spec-analyzer --target "期望输出应包含：1. 问题域分析 2. 解决方案..." --repo https://github.com/xxx/yyy

# 指定评估阈值
/optimize-skill spec-analyzer --target ./target.md --repo https://github.com/xxx/yyy --threshold-coverage 95 --threshold-depth 4

参数说明

参数	说明	默认值
--target, -t	目标内容（文件路径或直接输入）	必填
--repo, -r	GitHub 仓库 URL	必填
--threshold-coverage	覆盖度阈值 (0-100)	90
--threshold-depth	深度阈值 (1-5)	3.5
--max-iterations	最大迭代次数	5
--output, -o	优化记录输出目录	./optimization-records/

工作流程

流程图

┌─────────────────────────────────────────────────────────────┐
│                    迭代优化循环                              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. 读取目标内容 → 解析知识点清单                            │
│         ↓                                                    │
│  2. 初始化工作流目录                                         │
│         ↓                                                    │
│  3. Agent 调用目标 skill 提取内容                            │
│         ↓                                                    │
│  4. LLM 评估（覆盖度 + 深度）                                │
│         ↓                                                    │
│  5. 检查是否达到阈值 ──否──→ 生成优化建议                    │
│         │                          ↓                         │
│         │                    应用优化到 SKILL.md             │
│         │                          ↓                         │
│         │                    返回步骤 3                      │
│         ↓                                                    │
│        是                                                    │
│         ↓                                                    │
│  6. 输出最终报告                                             │
│                                                              │
└─────────────────────────────────────────────────────────────┘

步骤详解

步骤 1: 读取目标内容

1. 读取 --target 指定的目标内容
2. 解析目标内容，提取知识点清单
3. 为每个知识点分配 ID、权重和类型

知识点清单格式：

ID	知识点	权重	类型
K1	问题描述	高	问题域
K2	解决方案	高	解决方案
K3	技术实现	中	技术要点

步骤 2: 初始化工作流目录

创建优化记录目录：

./optimization-records/<timestamp>/
├── target.md                 # 目标内容
├── knowledge-points.json     # 知识点清单
├── repo-url.txt              # 分析的仓库 URL
└── iterations/               # 迭代记录

步骤 3: 调用目标 Skill

使用 Agent 工具启动子代理：

使用 Agent 工具:
- subagent_type: "general-purpose"
- prompt: "执行 /spec-analyzer <repo> --depth deep"
- description: "执行 spec-analyzer 分析"

重要: 子代理在隔离环境中执行，不影响主会话上下文。

步骤 4: LLM 评估

评估维度：

1. 知识点覆盖度 (0-100%)

• 完全覆盖：有详细解释
• 部分覆盖：有提及但不完整
• 未覆盖：完全没有提到

2. 内容深度 (1-5 分)

• 1: 仅提及
• 2: 简要说明
• 3: 详细解释
• 4: 包含示例
• 5: 深入分析

步骤 5: 检查终止条件

终止条件：

• 覆盖度 >= --threshold-coverage
• 深度 >= --threshold-depth
• 或达到 --max-iterations

如果未达到阈值，生成优化建议并应用。

步骤 6: 输出最终报告

生成包含以下内容的报告：

• 评估结果对比
• 迭代历史
• 主要优化点
• 未解决问题

评估提示词模板

在每轮迭代中，使用以下提示词进行评估：

# 评估任务

## 目标知识点清单
{knowledge_points}

## 提取的内容
{extracted_content}

## 评估要求

请逐项评估每个目标知识点的覆盖情况：

### 1. 知识点覆盖度
对于每个目标知识点，判断：
- **完全覆盖**：有详细解释，包含关键细节
- **部分覆盖**：有提及但不完整
- **未覆盖**：完全没有提到

### 2. 内容深度评分 (1-5)
- 1: 仅提及名称
- 2: 简要说明（1-2 句话）
- 3: 详细解释（有完整描述）
- 4: 包含示例（有代码/图表/流程）
- 5: 深入分析（有对比、权衡、原理解释）

## 输出格式

请按以下 JSON 格式输出评估结果：

```json
{
  "coverage": {
    "total": <总数>,
    "covered": <完全覆盖数>,
    "partial": <部分覆盖数>,
    "missing": <未覆盖数>,
    "percentage": <覆盖百分比>
  },
  "depth": {
    "average": <平均深度分数>,
    "details": [
      {"id": "<知识点ID>", "score": <1-5>, "note": "<简短说明>"}
    ]
  },
  "missing_points": ["<未覆盖的知识点列表>"],
  "weak_points": ["<深度不足的知识点列表>"],
  "suggestions": ["<针对 SKILL.md 的具体修改建议>"]
}

**评估结果解读**：

| 覆盖度 | 深度 | 状态 |
|--------|------|------|
| >= 90% | >= 3.5 | ✅ 达标 |
| 70-89% | 2.5-3.4 | ⚠️ 需要优化 |
| < 70% | < 2.5 | ❌ 需要大幅改进 |

## 优化建议生成模板

当评估未达标时，使用以下模板生成优化建议：

```markdown
# 优化建议生成任务

## 当前评估结果
{evaluation_json}

## 当前 SKILL.md 内容
{current_skill_content}

## 任务

根据评估结果，生成具体的 SKILL.md 修改建议。

### 修改建议格式

对于每个问题，提供：

1. **问题描述**：具体是什么问题
2. **问题位置**：SKILL.md 中的哪个章节/步骤
3. **当前内容**：当前的提示词
4. **建议修改**：修改后的提示词
5. **修改原因**：为什么这样修改能解决问题

### 优化策略

| 问题类型 | 优化策略 |
|----------|----------|
| 未覆盖知识点 | 添加新的提取规则或检查清单 |
| 深度不足 | 细化提取指令，添加深度要求 |
| 信息遗漏 | 添加必检项和提示词引导 |
| 格式问题 | 调整输出模板 |

优化示例

问题: K4（文件体系）未被提取

位置: "扫描文档" 章节

当前内容:

递归查找所有 .md 文件，重点关注 README.md 和 docs/ 目录

建议修改:

递归查找所有 .md 文件，重点关注：

• README.md - 项目介绍
• docs/ 目录 - 文档
• PROJECT.md - 项目描述和目标
• REQUIREMENTS.md - 需求清单
• ROADMAP.md - 路线图
• STATE.md - 状态追踪
• 模板目录（如 get-shit-done/templates/）

原因: 原描述太笼统，没有指定 spec-driven 仓库特有的文件类型

输出目录结构

优化完成后，生成以下文件结构：

./optimization-records/<timestamp>/
├── target.md                 # 目标内容
├── knowledge-points.json     # 解析后的知识点清单
├── repo-url.txt              # 分析的仓库 URL
├── iterations/
│   ├── 01/
│   │   ├── extracted.md      # 第 1 轮提取结果
│   │   ├── evaluation.json   # 第 1 轮评估
│   │   └── changes.md        # 第 1 轮修改建议
│   ├── 02/
│   │   └── ...
│   └── N/
├── final-report.md           # 最终优化报告
└── SKILL.md.final            # 优化后的最终版本

文件说明

文件	说明
target.md	用户提供的期望输出内容
knowledge-points.json	从目标内容解析的知识点清单
iterations/N/extracted.md	第 N 轮 skill 执行的输出
iterations/N/evaluation.json	第 N 轮的评估结果
iterations/N/changes.md	第 N 轮对 SKILL.md 的修改
final-report.md	完整的优化报告
SKILL.md.final	最终优化后的 skill 文件

最终报告模板

优化完成后，生成 final-report.md：

# {skill-name} 优化报告

## 基本信息
- **优化日期**: {timestamp}
- **目标仓库**: {repo_url}
- **迭代次数**: {iterations}
- **最终状态**: {success/failed}

## 评估结果

### 初始状态
- 覆盖度: {initial_coverage}%
- 深度: {initial_depth}

### 最终状态
- 覆盖度: {final_coverage}%
- 深度: {final_depth}

### 改进幅度
- 覆盖度提升: +{coverage_improvement}%
- 深度提升: +{depth_improvement}

## 迭代历史

| 轮次 | 覆盖度 | 深度 | 主要修改 |
|------|--------|------|----------|
| 1 | 60% | 2.5 | 添加文件体系提取规则 |
| 2 | 75% | 3.0 | 细化工作流程描述 |
| 3 | 90% | 3.6 | 添加深度要求 |

## 主要优化点

1. {优化点1}
2. {优化点2}
3. {优化点3}

## 未解决的问题

- {问题1}（建议后续处理）
- {问题2}（需要更多测试案例验证）

## 后续建议

- {后续改进建议}

完整示例

示例 1: 优化 spec-analyzer

目标内容 (target.md):

## GSD 工作流核心知识点

### 一、AI 编程工作流的重要性
- 上下文过长问题
- 需求分散问题
- 主代理负载过重

### 二、GSD 概述
- 规范驱动的 AI 编程工作流
- 30+ 个命令

### 三、GSD 文件体系
- PROJECT.md
- REQUIREMENTS.md
- ROADMAP.md
- STATE.md

### 四、完整工作流程
1. 初始化项目
2. 需求讨论
3. 生成计划
4. 执行编码
5. 验收测试

...

执行命令:

/optimize-skill spec-analyzer \
  --target ./target.md \
  --repo https://github.com/gsd-build/get-shit-done \
  --threshold-coverage 90 \
  --threshold-depth 3.5 \
  --max-iterations 5

执行过程:

=== 迭代优化开始 ===
目标: spec-analyzer
仓库: https://github.com/gsd-build/get-shit-done
阈值: 覆盖度 90%, 深度 3.5

[迭代 1]
- 调用 spec-analyzer...
- 评估: 覆盖度 65%, 深度 2.8
- 未达标，生成优化建议...
- 应用修改: 添加文件体系提取规则

[迭代 2]
- 调用 spec-analyzer...
- 评估: 覆盖度 78%, 深度 3.2
- 未达标，生成优化建议...
- 应用修改: 细化工作流程描述

[迭代 3]
- 调用 spec-analyzer...
- 评估: 覆盖度 92%, 深度 3.7
- 达标！

=== 优化完成 ===
最终报告: ./optimization-records/20260313-143022/final-report.md
优化后 Skill: ./optimization-records/20260313-143022/SKILL.md.final

注意事项

1. 迭代控制

• 一次优化聚焦 1-2 个核心问题
• 设置合理的最大迭代次数，避免无限循环
• 每轮迭代后检查进展，如果连续无改进可提前终止

2. 评估稳定性

• LLM 评估可能有波动，设置容差范围（如 ±5%）
• 关键优化点建议人工复核
• 深度评分相对主观，关注趋势而非绝对值

3. 文件管理

• 原始 SKILL.md 会自动备份
• 每轮迭代保留完整记录
• 可随时从 SKILL.md.final 恢复

4. 上下文管理

• 使用 Agent 工具隔离子代理执行
• 大型仓库可能导致提取内容过长
• 建议先在小型仓库测试

5. 代理配置

• Clone GitHub 仓库可能需要配置代理
• 参考 spec-analyzer 中的代理配置说明

常见问题

Q1: 迭代不收敛怎么办？

可能原因：

• 目标内容与仓库内容不匹配
• 评估标准过高
• skill 本身设计有根本性问题

解决方案：

• 检查目标内容是否可从仓库中提取
• 适当降低阈值
• 分析未覆盖知识点的根本原因

Q2: Agent 调用失败怎么办？

可能原因：

• 网络问题
• 仓库访问权限
• 上下文过长

解决方案：

• 检查网络和代理配置
• 确认仓库是公开的
• 尝试更小的测试仓库

Q3: 如何只做单次评估不做迭代？

# 设置 max-iterations 为 1
/optimize-skill spec-analyzer --target ./target.md --repo https://github.com/xxx/yyy --max-iterations 1