Skill Optimizer

• 用户只需描述"哪个 skill 没触发什么功能"
• 自动诊断问题根因（触发条件/流程缺失/逻辑错误）
• 使用 Agent 在独立上下文中执行优化，保护主会话
• 优化后输出修改摘要和使用建议

gsd:workflow gsd:meta skill-optimizer 优化 skill、skill 没触发、为什么没有、skill 诊断 Read, Glob, Grep, Agent, Skill

<!-- 必须阅读的标准参考 -->
<require_read>
  <ref id="skill-creator" required="false">优先使用当前环境提供的官方 Skill 创建规范；若不可用，则回退到通用 SKILL.md frontmatter、触发边界和渐进披露规范</ref>
  <ref id="efficiency-audit" required="false">效率审计 Skill（可选依赖，用于分析当前会话执行效率）</ref>
</require_read>

<!-- 执行前检查点 -->
<checkpoints>
  <checkpoint order="1">已提取 skill 名称和问题描述</checkpoint>
  <checkpoint order="2">已定位 skill 文件路径</checkpoint>
  <checkpoint order="3">已完成智能效率审计评估（自动触发或跳过）</checkpoint>
  <checkpoint order="4">已输出诊断报告并获得用户确认</checkpoint>
</checkpoints>

<!-- 安全约束 -->
<constraints>
  <constraint>禁止在主会话中直接修改 skill</constraint>
  <constraint>禁止不诊断直接优化</constraint>
  <constraint>禁止大规模重构，只修改必要部分</constraint>
</constraints>

gsd:goal诊断 skill 问题，使用 Agent 执行优化，保护主会话上下文

<gsd:phase name="parse" order="1"> gsd:step解析用户输入，提取 skill 名称和问题描述 gsd:step定位 skill 文件路径 gsd:checkpoint确认 skill 存在且可访问

<gsd:phase name="audit" order="2" condition="自动评估或用户选择执行效率审计"> gsd:step评估当前任务复杂度和已耗时，决定是否自动触发效率审计 gsd:step若触发（自动或用户确认），使用 Skill 工具调用 efficiency-audit gsd:step提取审计报告中的反模式和优化建议 gsd:checkpoint完成效率审计（如已触发）

<gsd:phase name="diagnose" order="3"> gsd:step阅读 skill 完整内容 gsd:step分析 skill 结构（触发条件/流程/命令） gsd:step诊断问题根因 gsd:checkpoint输出诊断报告，确认优化方向

<gsd:phase name="optimize" order="4"> gsd:step设计优化方案 gsd:step使用 Agent 在独立上下文中执行优化 gsd:step验证优化结果

Phase 1: 解析 (parse)

Step 1.1: 提取信息

从用户输入中提取：

Step 1.2: 定位 skill 文件

# 搜索 skill 位置
find ~/.claude/skills -name "SKILL.md" -exec grep -l "name: xxx" {} \;

# 或在项目目录中搜索
find ~/jacky-github/jacky-skills -name "SKILL.md" -exec grep -l "name: xxx" {} \;

常见位置：

• ~/.claude/skills/<skill-name>/SKILL.md (全局安装)
• ~/jacky-github/jacky-skills/plugins/**/SKILL.md (项目目录)
• ~/jacky-github/jacky-skills/skills/**/SKILL.md (独立 skills)

Checkpoint: 如果找不到 skill 文件，询问用户确认 skill 名称是否正确。

Phase 1.5: 智能效率审计 (audit)

此阶段为智能触发步骤。大模型根据任务复杂度和已耗时自动判断是否触发，无需用户手动决定。

Step 1.5.1: 自动评估触发条件

自动触发规则（无需询问用户）：

Step 1.5.2: 调用 efficiency-audit

触发后，使用 Skill 工具调用：

Skill(skill: "efficiency-audit")

Step 1.5.3: 提取审计关键信息

从审计报告中提取与当前 skill 相关的信息：

Checkpoint: 审计结果将作为 Phase 2 诊断的输入之一。若未触发审计，直接进入 Phase 2。

Phase 2: 诊断 (diagnose)

Step 2.1: 分析 skill 结构

阅读 skill 内容，重点关注:

# 提取关键结构
grep -E "^##|^<commands>|<process>|<trigger>|<gsd:phase>" SKILL.md

结构分析清单：

Step 2.2: 诊断问题根因

常见问题诊断表：

┌─────────────────┬──────────────────┬────────────────────────────┐
│     问题类型     │      症状        │          诊断方向           │
├─────────────────┼──────────────────┼────────────────────────────┤
│ 命令未触发      │ 命令存在但没执行 │ 检查是否为独立命令    │
│                 │                  │ → 需要显式调用           │
├─────────────────┼──────────────────┼────────────────────────────┤
│ 触发条件不匹配   │ skill 没被触发   │ 检查 description          │
│                 │                  │ → 添加更多 trigger 词   │
├─────────────────┼──────────────────┼────────────────────────────┤
│ 功能缺失        │ 预期功能不存在  │ 检查是否设计遗漏        │
│                 │                  │ → 评估是否需要添加       │
├─────────────────┼──────────────────┼────────────────────────────┤
│ 自动执行逻辑问题 │ 应自动执行但没执行 │ 检查流程中是否有自动触发 │
│                 │                  │ → 添加自动执行逻辑     │
├─────────────────┼──────────────────┼────────────────────────────┤
│ 输出格式问题    │ 结果难以理解     │ 检查输出结构            │
│                 │                  │ → 标准化输出格式        │
└─────────────────┴──────────────────┴────────────────────────────┘

Step 2.3: 输出诊断报告

## 🔍 诊断报告

### 问题分析
- **Skill**: {skill-name}
- **预期功能**: {用户期望的功能}
- **实际行为**: {skill 实际做了什么}

### 诊断结果
- **问题类型**: 命令未触发 / 触发条件不匹配 / 功能缺失 / 自动执行逻辑问题
- **根本原因**: {详细说明}

### 优化方向
- [ ] 方向 1: {说明}
- [ ] 方向 2: {说明}

是否需要我执行优化？

Checkpoint: 使用 AskUserQuestion 确认是否执行优化。

Phase 3: 优化 (optimize) - 使用 Agent 保护上下文

Step 3.1: 使用 Agent 执行优化

重要: 使用 Agent 模式在独立上下文中执行优化，避免消耗主会话 token。

Agent({
  subagent_type: "general-purpose",
  description: "优化 skill 逻辑",
  prompt: `
你是一个 Skill 优化专家。请优化以下 skill。

## Skill 路径
{skill_path}

## 问题描述
{问题描述}

## 诊断结果
{诊断结果}

## 优化要求
1. 阅读当前 skill 内容
2. 根据诊断结果设计优化方案
3. 执行修改
4. 输出修改摘要（不要输出完整代码）
5. 提供使用建议

注意：
- 只修改必要的部分，不要大规模重构
- 保持与现有风格一致
- 使用 GSD 风格的 XML 标签（如适用）
`
})

Step 3.2: 鸸证优化结果

Agent 完成后， 检查:

• 修改是否合理
• 是否解决了问题
• 是否有其他影响

Step 3.3: 输出优化摘要

## ✅ 优化完成

### 修改摘要
| 文件 | 修改内容 |
|------|---------|
| {file} | {简要说明} |

### 新增/修改内容
{描述新增或修改的功能}

### 使用建议
1. {建议 1}
2. {建议 2}

### 后续验证
- [ ] 测试 skill 触发
- [ ] 验证功能执行
- [ ] 检查是否有副作用

详细诊断模式

Phase 2 无法仅凭诊断表确定根因，或需要设计具体优化方案时，读取 references/detailed-diagnosis-guide.md。若需要更多历史案例，可再读取 references/diagnosis-patterns.md。

❌ 错误 1：在主会话中直接读取大量代码

错误做法：直接 Read 整个 skill 文件和所有 references 正确做法：使用 Agent 在独立上下文中分析

❌ 错误 2：不诊断直接修改

错误做法：凭猜测直接修改 skill 正确做法：先诊断问题根因，再针对性优化

❌ 错误 3：优化后不验证

错误做法：修改后直接结束 正确做法：输出修改摘要，提供使用建议

❌ 错误 4：忽略用户确认

错误做法：诊断后直接修改，不询问用户 正确做法：输出诊断报告，使用 AskUserQuestion 确认

❌ 错误 5：大规模重构

错误做法：重写整个 skill 结构 正确做法：只修改必要的部分，保持与现有风格一致

使用示例

# 示例 1: 诊断命令未触发
/repo-study 为什么没有触发翻译功能
# → 诊断：translate 是独立命令，需要显式调用
# → 优化：在 research 阶段结束后提示用户

# 示例 2: 诊断功能缺失
skill-optimizer j-skills 没有批量安装功能
# → 诊断：commands 中没有 batch-install
# → 优化：添加批量安装命令

# 示例 3: 诊断触发问题
skill-optimizer parallel-translation 没有被触发
# → 诊断：description 缺少"翻译"触发词
# → 优化：扩展 description

诊断命令速查

# 搜索 skill 位置
find ~/.claude/skills -name "SKILL.md" -exec grep -l "name: xxx" {} \;

# 搜索关键词
grep -r "translate" ~/.claude/skills/xxx/SKILL.md

# 查看 skill 结构
grep -E "^##|^<commands>|<process>|<trigger>" SKILL.md