Claude-Code-Workflow/.claude/skills/_shared/COMMAND-TO-SKILL-CONVERSION.md

命令转 Skill 规范 v2.0

基于 workflow-plan 转换实践提炼的标准流程

v2.0 变更：命令调用引用统一转换为文件路径引用，不再保留 /workflow:XX 等命令调用语法

⚠️ 核心要求

Phase 文件内容必须与原命令文件内容一致

转换时只改变结构和组织方式，不改变功能实现细节。

---

目录

1. 转换目标
2. 核心原则
3. 结构映射
4. 转换步骤
5. SKILL.md 编写规范
6. Phase 文件编写规范
7. 内容一致性验证
8. 质量检查清单
9. 示例对照

---

1. 转换目标

1.1 为什么转换

命令格式	Skill 格式
单文件 + 子命令引用	结构化目录 + 分阶段执行
一次性全量加载	分布读取（按需加载）
执行流程隐式	执行流程显式定义
子命令散落各处	Phase 文件集中管理
缺乏复用机制	模板/规范可复用

1.2 转换收益

• 上下文优化：Phase 文件按需加载，减少 token 消耗
• 可维护性：结构清晰，修改范围可控
• 可扩展性：新增阶段只需添加 Phase 文件
• 执行可视化：TodoWrite 与 Phase 对齐，进度透明

---

2. 核心原则

2.1 内容一致性原则（最高优先级）

Phase 文件内容必须与原命令文件内容一致

这是转换的第一要求，不可妥协。

一致性定义：

维度	一致性要求	验证方法
代码逻辑	所有Bash命令、函数、条件判断完全一致	逐行对比代码块
Agent Prompt	Prompt内容100%保留，包括示例和约束	全文搜索关键段落
数据结构	表格、Schema、类型定义完整复制	对比字段数量
执行步骤	步骤顺序、子步骤层级保持不变	对比步骤编号
文本说明	关键说明、注释、警告完整保留	抽查重要段落

允许的差异：

差异类型	说明	示例
✅ 添加阶段标识	Phase标题、来源标注	# Phase 1: Session Discovery
✅ 添加组织结构	章节标题优化	添加 ## Execution Steps
✅ 添加衔接说明	Post-Phase Update	阶段完成后的状态说明
✅ 命令引用转文件路径	将 /workflow、/command 等命令引用转换为相对文件路径	原文 /workflow:session:start → phases/01-session-discovery.md
✅ 移除 Frontmatter	移除命令的 argument-hint、examples	命令级元数据在 Skill 中不需要
❌ 简化代码	任何代码的省略或改写	不允许
❌ 简化Prompt	Agent Prompt的任何删减	不允许
❌ 调整步骤	合并、拆分、重排步骤	不允许

内容保留清单：

内容类型	保留要求	示例
Bash命令	完整命令，包含所有参数、管道、重定向	find . -name "*.json" | head -1
Agent Prompt	全文保留，包含OBJECTIVE、TASK、EXPECTED等所有节	完整的Task({prompt: "..."})
代码函数	完整函数体，所有if/else分支	analyzeTaskComplexity() 全部代码
参数表格	所有行列，不省略任何参数	Session Types表格
JSON Schema	所有字段、类型、required定义	context-package.json schema
验证逻辑	所有校验条件、错误处理、回滚代码	conflict resolution验证清单
配置示例	输入输出示例、配置模板	planning-notes.md模板
注释说明	重要的行内注释、块注释	// CRITICAL: ...

❌ 严格禁止的简化行为：

1. 将代码替换为描述

   • ❌ 错误：Execute context gathering agent
   • ✅ 正确：完整的 Task({ subagent_type: "context-search-agent", prompt: "...[完整200行prompt]..." })

2. 省略Prompt内容

   • ❌ 错误：Agent prompt for context gathering (see original file)
   • ✅ 正确：复制粘贴完整Prompt文本

3. 压缩表格

   • ❌ 错误：Session types: Discovery/Auto/Force (see details in code)
   • ✅ 正确：完整Session Types表格，包含type/description/use case列

4. 合并步骤

   • ❌ 错误：将Step 1.1-1.4合并为Step 1
   • ✅ 正确：保持1.1、1.2、1.3、1.4独立步骤

5. 删除示例

   • ❌ 错误：省略JSON输出示例
   • ✅ 正确：保留所有输入输出示例

引用转换规则：

命令引用统一转换为文件路径引用，规则如下：

原命令引用	转换方式	示例
Frontmatter	移除，在 SKILL.md 中统一定义	argument-hint、examples → 移除
命令调用语法	转换为 Phase 文件的相对路径	/workflow:session:start → phases/01-session-discovery.md
命令路径引用	转换为 Skill 目录内路径	commands/workflow/tools/ → phases/
跨命令引用	转换为 Phase 间文件引用	/workflow:tools:context-gather → phases/02-context-gathering.md
命令参数说明	移除或转为 Phase Prerequisites	usage: /workflow:plan [session-id] → Phase Prerequisites 中说明

转换示例：

原命令文件中：

## Related Commands
- `/workflow:session:start` - Start new session
- `/workflow:tools:context-gather` - Gather context

转换后 Phase 文件中（使用文件路径引用）：

## Related Phases
- [Phase 1: Session Discovery](phases/01-session-discovery.md)
- [Phase 2: Context Gathering](phases/02-context-gathering.md)

或在 SKILL.md 的 Phase Reference Table 中统一管理引用关系：

### Phase Reference Documents
| Phase | Document | Purpose |
|-------|----------|---------|
| Phase 1 | [phases/01-session-discovery.md](phases/01-session-discovery.md) | 会话发现与初始化 |
| Phase 2 | [phases/02-context-gathering.md](phases/02-context-gathering.md) | 上下文收集 |

2.2 分布读取原则

SKILL.md 引用 Phase，Phase 按执行顺序加载

执行流程：
Phase 1 → Read: phases/01-xxx.md → 执行 → 释放
    ↓
Phase 2 → Read: phases/02-xxx.md → 执行 → 释放
    ↓
Phase N → Read: phases/0N-xxx.md → 执行 → 完成

2.3 职责分离原则

层级	职责	内容
SKILL.md	编排协调	流程图、数据流、TodoWrite 模式、阶段入口
Phase 文件	具体执行	完整执行逻辑、代码实现、Agent Prompt
Specs	规范约束	Schema 定义、质量标准、领域规范
Templates	可复用片段	Agent 基础模板、输出模板

---

3. 结构映射

3.1 命令结构 → Skill 结构

commands/                              skills/
├── workflow/                          ├── workflow-plan/
│   ├── plan.md          ────────→    │   ├── SKILL.md (orchestrator)
│   ├── session/                      │   ├── phases/
│   │   └── start.md     ────────→    │   │   ├── 01-session-discovery.md
│   └── tools/                        │   │   ├── 02-context-gathering.md
│       ├── context-gather.md ───→    │   │   ├── 03-conflict-resolution.md
│       ├── conflict-resolution.md    │   │   └── 04-task-generation.md
│       └── task-generate-agent.md    │   └── (specs/, templates/ 可选)

3.2 文件映射规则

源文件类型	目标文件	映射规则
主命令文件	SKILL.md	提取元数据、流程、协调逻辑
子命令文件	phases/0N-xxx.md	完整内容 + 阶段标识
引用的规范	specs/xxx.md	独立提取或保留在 Phase 中
通用模板	templates/xxx.md	多处引用时提取

3.3 命名转换

原命令路径	Phase 文件名
session/start.md	01-session-discovery.md
tools/context-gather.md	02-context-gathering.md
tools/conflict-resolution.md	03-conflict-resolution.md
tools/task-generate-agent.md	04-task-generation.md

命名规则：{序号}-{动作描述}.md

• 序号：两位数字 01, 02, ...
• 动作：动词-名词形式，小写连字符

---

4. 转换步骤

4.1 准备阶段

□ Step 0: 分析源命令结构
  - 读取主命令文件，识别调用的子命令
  - 绘制命令调用关系图
  - 统计各文件行数（用于后续验证）

4.2 创建目录结构

□ Step 1: 创建 Skill 目录
  mkdir skills/{skill-name}/
  mkdir skills/{skill-name}/phases/

4.3 编写 SKILL.md

□ Step 2: 编写 SKILL.md
  - 提取 Frontmatter (name, description, allowed-tools)
  - 编写架构概览图
  - 编写执行流程（含 Phase 引用表）
  - 编写数据流定义
  - 编写 TodoWrite 模式
  - 编写协调逻辑（阶段间衔接）

4.4 转换 Phase 文件

□ Step 3: 逐个转换子命令为 Phase 文件
  FOR each 子命令:
    - 读取原命令完整内容
    - 添加 Phase 标题和元信息
    - 保留所有代码、表格、Agent Prompt
    - 添加 Post-Phase Update 节（如需）
    - 验证行数接近原文件

4.5 验证完整性

□ Step 4: 验证内容完整性
  - 比较 Phase 文件与原命令行数
  - 确认关键代码块存在
  - 确认 Agent Prompt 完整
  - 确认表格和 Schema 完整

---

5. SKILL.md 编写规范

5.1 Frontmatter 模板

---
name: {skill-name}
description: {简短描述}. Triggers on "{trigger-phrase}".
allowed-tools: Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep
---

5.2 必需章节

# {Skill Name}

{一句话描述功能}

## Architecture Overview
{ASCII 架构图}

## Key Design Principles
{设计原则列表}

## Auto Mode
{自动模式说明}

## Usage

Skill(skill="{skill-name}", args="") Skill(skill="{skill-name}", args="[FLAGS] """)

Flags

{flag 说明，每个 flag 一行}

Examples

Skill(skill="{skill-name}", args=""Implement JWT authentication"") # 说明 Skill(skill="{skill-name}", args="--mode xxx "Refactor payment module"") # 说明 Skill(skill="{skill-name}", args="-y "Add user profile page"") # 说明

## Execution Flow
{流程图 + Phase 引用表}

### Phase Reference Documents
| Phase | Document | Load When |
|-------|----------|-----------|
| Phase 1 | phases/01-xxx.md | Phase 1 开始时 |
| ... | ... | ... |

## Core Rules
{执行约束和规则}

## Data Flow
{阶段间数据传递定义}

## TodoWrite Pattern
{任务列表模板}

## Error Handling
{错误处理策略}

Usage 格式要求：

• 必须使用代码块 包裹 Usage 内容
• 使用 Skill() 调用格式，不使用 /skill-name 命令行格式
• 包含两种调用格式：基本调用 + 带 Flags 的完整调用
• Flags 说明每行一个 flag，格式：flag-name 说明
• Examples 必须展示所有 flag 组合的典型调用场景
• 字符串参数中的引号使用转义 \"
• Examples 行尾可添加 # 说明 注释

5.3 执行流程示例

## Execution Flow

Phase 1: Session Discovery │ Ref: phases/01-session-discovery.md ↓ Phase 2: Context Gathering │ Ref: phases/02-context-gathering.md ↓ Phase 3: Conflict Resolution (conditional) │ Ref: phases/03-conflict-resolution.md ↓ Phase 4: Task Generation │ Ref: phases/04-task-generation.md ↓ Complete: IMPL_PLAN.md + Task JSONs

### Phase Reference Documents

| Phase | Document | Load When |
|-------|----------|-----------|
| Phase 1 | `phases/01-session-discovery.md` | Phase 1 开始执行时 |
| Phase 2 | `phases/02-context-gathering.md` | Phase 1 完成后 |
| Phase 3 | `phases/03-conflict-resolution.md` | conflict_risk ≥ medium 时 |
| Phase 4 | `phases/04-task-generation.md` | Phase 3 完成或跳过后 |

---

6. Phase 文件编写规范

6.1 Phase 文件结构

# Phase N: {Phase Name}

> 来源: `commands/{path}/original.md`

## Overview
{阶段目标和职责}

## Prerequisites
{前置条件和输入}

## Execution Steps

### Step N.1: {Step Name}
{完整实现代码}

### Step N.2: {Step Name}
{完整实现代码}

## Agent Prompt (如有)
{完整 Agent Prompt，不简化}

## Output Format
{输出 Schema 和示例}

## Post-Phase Update
{阶段完成后的状态更新}

6.2 转换原则：只改结构，不改内容

转换时的思维模式：

"我是在搬运内容，不是在改写内容"

操作	允许	禁止
复制粘贴代码	✅
调整章节标题	✅
添加Phase标识	✅
改写代码逻辑		❌
简化Prompt		❌
省略步骤		❌

转换流程：

1. 打开原命令文件和新Phase文件并排显示
2. 逐段复制粘贴（不要凭记忆改写）
3. 只添加结构性元素（Phase标题、章节标题）
4. 保留100%功能性内容（代码、Prompt、表格、示例）

6.3 内容完整性自查

转换每个Phase文件后，必须完成以下检查：

检查项	检查方法	合格标准
代码块数量	计数 ```bash 和 ```javascript	与原文件相等
表格数量	计数 | 开头的行	与原文件相等
Agent Prompt	搜索 Task({	完整的prompt参数内容
步骤编号	检查 ### Step	编号序列与原文件一致
文件行数	wc -l	±20%以内
关键函数	搜索函数名	所有函数完整保留

示例检查：

# 原命令文件
$ grep -c "^###" commands/workflow/tools/context-gather.md
15

# Phase文件（应该相等或略多）
$ grep -c "^###" skills/workflow-plan/phases/02-context-gathering.md
16  # ✓ 只多了"Post-Phase Update"节

# 代码块数量对比
$ grep -c '```' commands/workflow/tools/context-gather.md
24

$ grep -c '```' skills/workflow-plan/phases/02-context-gathering.md
24  # ✓ 完全相等

6.4 内容保留清单（详细版）

转换时必须完整保留：

内容类型	保留要求
Bash 命令	完整命令，包含所有参数和路径
Agent Prompt	全文，包含示例和约束
代码函数	完整函数体，不简化
参数表格	所有列和行
JSON Schema	完整字段定义
验证逻辑	if/else、校验代码
错误处理	try/catch、回滚逻辑
示例	输入输出示例

6.3 禁止的简化

❌ 不要这样：

### Step 2: Run context gathering
Execute the context-search-agent to gather project context.

✅ 应该这样：

### Step 2: Run context gathering

```javascript
Task({
  subagent_type: "context-search-agent",
  prompt: `
## Context Search Task

### OBJECTIVE
Gather comprehensive context for planning session ${sessionId}

### MULTI-SOURCE DISCOVERY STRATEGY

**Track 0: Project Foundation**
- Read CLAUDE.md files at all levels
- Check .workflow/project-tech.json for stack info
...
[完整 Prompt 内容]
`,
  run_in_background: false
})

---

## 7. 内容一致性验证

### 7.1 验证流程

每完成一个Phase文件转换后，执行以下验证：

┌─────────────────────────────────────────────────────────────────┐ │ 内容一致性验证流程 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Step 1: 行数对比 │ │ $ wc -l 原文件 Phase文件 │ │ └─→ 差异应在 ±20% 以内 │ │ │ │ Step 2: 代码块对比 │ │ $ grep -c '```' 原文件 Phase文件 │ │ └─→ 数量应相等 │ │ │ │ Step 3: 关键内容抽查 │ │ - 搜索 Task({ → Agent Prompt 完整性 │ │ - 搜索函数名 → 函数体完整性 │ │ - 搜索表格标记 → 表格完整性 │ │ │ │ Step 4: 并排对比 │ │ - 打开原文件和Phase文件 │ │ - 逐节对比功能性内容 │ │ - 确认无省略无改写 │ │ │ └─────────────────────────────────────────────────────────────────┘

### 7.2 验证命令

```bash
# 1. 行数对比
wc -l commands/workflow/tools/context-gather.md skills/workflow-plan/phases/02-context-gathering.md

# 2. 代码块数量
grep -c '```' commands/workflow/tools/context-gather.md
grep -c '```' skills/workflow-plan/phases/02-context-gathering.md

# 3. 表格行数
grep -c '^|' commands/workflow/tools/context-gather.md
grep -c '^|' skills/workflow-plan/phases/02-context-gathering.md

# 4. Agent Prompt检查
grep -c 'Task({' commands/workflow/tools/context-gather.md
grep -c 'Task({' skills/workflow-plan/phases/02-context-gathering.md

# 5. 函数定义检查
grep -E '^(function|const.*=.*=>|async function)' commands/workflow/tools/context-gather.md
grep -E '^(function|const.*=.*=>|async function)' skills/workflow-plan/phases/02-context-gathering.md

7.3 一致性检查表

每个Phase文件必须填写：

检查项	原文件	Phase文件	是否一致
文件行数	___	___	□ ±20%内
代码块数量	___	___	□ 相等
表格行数	___	___	□ 相等
Task调用数	___	___	□ 相等
函数定义数	___	___	□ 相等
步骤数量	___	___	□ 相等或+1

7.4 不一致处理

发现不一致时：

情况	处理方式
Phase文件行数少>20%	❌ 必须补充：定位缺失内容，从原文件复制
代码块数量少	❌ 必须补充：找出缺失的代码块
Agent Prompt缺失	❌ 严重问题：立即从原文件完整复制
表格缺失	❌ 必须补充：复制完整表格
Phase文件行数多>20%	✓ 可接受（添加了结构性内容）

---

8. 质量检查清单

8.1 结构检查

□ SKILL.md 存在且包含必需章节
□ phases/ 目录存在
□ Phase 文件按数字前缀排序
□ 所有子命令都有对应 Phase 文件

8.2 内容完整性检查

□ Phase 文件行数 ≈ 原命令行数 (±20%)
□ 所有 Bash 命令完整保留
□ 所有 Agent Prompt 完整保留
□ 所有表格完整保留
□ 所有 JSON Schema 完整保留
□ 验证逻辑和错误处理完整

8.3 引用检查

□ SKILL.md 中 Phase 引用路径正确
□ Phase 文件标注了来源命令
□ 跨 Phase 数据引用明确

8.4 行数对比表

原命令	行数	Phase 文件	行数	差异
session/start.md	202	01-session-discovery.md	281	+39% ✓
tools/context-gather.md	404	02-context-gathering.md	427	+6% ✓
tools/conflict-resolution.md	604	03-conflict-resolution.md	645	+7% ✓
tools/task-generate-agent.md	693	04-task-generation.md	701	+1% ✓

Phase 文件可以比原命令稍长（添加了阶段标识、Post-Phase Update 等），但不应显著缩短。

---

9. 示例对照

9.1 workflow-plan 转换示例

转换前（命令结构）：

commands/workflow/
├── plan.md (163 行) ─── 主命令，调用子命令
├── session/
│   └── start.md (202 行) ─── 会话管理
└── tools/
    ├── context-gather.md (404 行) ─── 上下文收集
    ├── conflict-resolution.md (604 行) ─── 冲突解决
    └── task-generate-agent.md (693 行) ─── 任务生成

转换后（Skill 结构）：

skills/workflow-plan/
├── SKILL.md (348 行) ─── 编排协调
└── phases/
    ├── 01-session-discovery.md (281 行)
    ├── 02-context-gathering.md (427 行)
    ├── 03-conflict-resolution.md (645 行)
    └── 04-task-generation.md (701 行)

9.2 SKILL.md 与原主命令对比

原 plan.md 内容	SKILL.md 对应位置
Frontmatter	Frontmatter (扩展)
argument-hint	Usage (转换为 Skill 调用格式)
执行流程描述	Execution Flow (可视化)
子命令调用	Phase Reference Table
数据传递	Data Flow (显式定义)
(无)	Usage (新增 - Skill 调用格式)
(无)	TodoWrite Pattern (新增)
(无)	Error Handling (新增)

Usage 转换示例：

原命令 argument-hint:

argument-hint: "[-y|--yes] \"text description\"|file.md"

转换为 SKILL.md Usage:

Skill(skill="workflow-plan", args="<task description>")
Skill(skill="workflow-plan", args="[-y|--yes] \"<task description>\"")

# Flags
-y, --yes    Skip all confirmations (auto mode)

# Examples
Skill(skill="workflow-plan", args="\"Implement authentication\"")     # Interactive mode
Skill(skill="workflow-plan", args="-y \"Implement authentication\"")  # Auto mode

9.3 Phase 文件与原子命令对比

原子命令内容	Phase 文件对应
Frontmatter	移除 (Skill 不需要)
步骤说明	Execution Steps
代码实现	完整保留（一致性要求）
Agent Prompt	完整保留（一致性要求）
输出格式	Output Format
(无)	Post-Phase Update (新增)

---

附录：快速转换命令

# 1. 统计原命令行数
wc -l commands/{path}/*.md commands/{path}/**/*.md

# 2. 创建 Skill 目录
mkdir -p skills/{skill-name}/phases

# 3. 转换完成后验证
wc -l skills/{skill-name}/SKILL.md skills/{skill-name}/phases/*.md

# 4. 对比行数差异
# Phase 文件行数应 ≈ 原命令行数 (±20%)

---

修订历史

版本	日期	变更
v1.0	2025-02-05	基于 workflow-plan 转换实践创建
v1.1	2025-02-05	强化内容一致性要求；添加第7章一致性验证；添加应移除的命令特有内容说明
v2.0	2026-02-05	命令调用引用统一转换为文件路径引用；移除 /workflow:XX 命令语法；引用转换规则重构
v2.1	2026-02-05	添加 Usage 部分格式规范（Skill 调用格式）；更新 5.2 必需章节；添加 Usage 转换示例到 9.2 节