claude-command-converter

Claude 命令转换器

将 Claude Code 命令转换为标准 Agent Skills 格式，以便在不同 AI 编码助手之间移植。

适用场景

• 将现有的 .claude/commands/*.md 文件迁移为 skills/*/SKILL.md 格式。
• 根据 Claude Code 专用命令创建可移植的技能。
• 标准化命令定义，以便用于 Claude Code、Codex CLI、GitHub Copilot 和其他运行时。

输入

• 源命令文件路径（例如 .claude/commands/my-command.md）。
• 可选：目标技能名称（默认为不带扩展名的命令文件名）。

如果缺少输入，请询问源命令文件路径。

格式差异

Claude Code 命令格式

位置：.claude/commands/<command-name>.md

---
description: Short description of the command
handoffs:
  - label: Next Action
    agent: other.command
    prompt: Trigger prompt
    send: true
---
## User Input

\`\`\`text
$ARGUMENTS
\`\`\`

[Command instructions...]

标准 Agent Skill 格式

位置：skills/<skill-name>/SKILL.md

---
name: skill-name
description: Complete description including what the skill does and when to use it.
---

# Skill Title

## When to Use

- Scenario 1
- Scenario 2

## Inputs

- Required input 1
- Optional input 2

## Workflow

1. Step 1
2. Step 2
...

## Outputs

- Output file 1
- Output file 2

转换工作流

1. 读取源命令：从 .claude/commands/ 中读取。

2. 提取元数据：

   • 从 YAML frontmatter 中提取 description。
   • 提取用于关联技能/后续步骤的 handoffs。
   • 处理输入时对 $ARGUMENTS 的用法。

3. 确定技能名称：

   • 将 command.name.md 转换为 command-name（将点替换为连字符）。
   • 多词名称使用 kebab-case。

4. 创建技能目录：skills/<skill-name>/

5. 将内容转换为 SKILL.md 格式：

   • Frontmatter：仅保留 name 和 description。
   • 完善描述：扩展描述，说明适用场景。
   • 转换 $ARGUMENTS：将其记录在 Inputs 部分。
   • 组织工作流：将步骤提取到编号的 Workflow 部分。
   • 添加“When to Use”：根据命令上下文和描述推导。
   • 添加“Outputs”：列出生成的文件/产物。
   • 转换 handoffs：添加“Next Steps”部分，引用相关技能。

6. 移除运行时专用内容：

   • 移除包含 $ARGUMENTS 块的 ## User Input 部分。
   • 从 frontmatter 中移除 handoffs（将其移入正文）。
   • 移除 /command.name 引用（改用技能名称）。

7. 验证技能结构：

   • Frontmatter 仅包含 name 和 description。
   • 正文包含清晰的章节（When to Use、Inputs、Workflow、Outputs）。
   • 不保留任何 TODO 占位符。
   • 不包含 $ARGUMENTS 等运行时专用变量。

8. 报告转换结果：

   • 源命令路径。
   • 生成的技能路径。
   • 应用的关键转换。
   • 人工审核建议。

转换规则

Claude 命令	Agent Skill
$ARGUMENTS	描述预期用户输入的 Inputs 部分
handoffs:	包含技能引用的 Next Steps 部分
/command.name	skill-name（kebab-case）
agent: foo.bar	foo-bar 技能引用
frontmatter 中的 description:	扩展 description:，加入触发条件
行内 ## User Input	移除；在 Inputs 中记录

转换示例

输入：.claude/commands/speckit.specify.md

---
description: Create feature specification from natural language.
handoffs:
  - label: Build Technical Plan
    agent: speckit.plan
---
## User Input

\`\`\`text
$ARGUMENTS
\`\`\`

The text the user typed after `/speckit.specify`...

输出：skills/speckit-specify/SKILL.md

---
name: speckit-specify
description: Create or update a feature specification from a natural language feature description.
---

# Spec Kit Specify Skill

## When to Use

- The user wants a new or updated feature spec from a natural language description.

## Inputs

- Feature description from the user.
- Repo context with `.specify/` scripts and templates.

If the description is missing or unclear, ask a targeted question before continuing.

## Workflow

...

## Outputs

- `specs/<feature>/spec.md`
- `specs/<feature>/checklists/requirements.md`

## Next Steps

After generating spec.md:

- **Plan** technical implementation with speckit-plan.
- **Clarify** specification requirements with speckit-clarify.

关键规则

• 保留所有工作流逻辑和指令。
• 移除运行时专用结构（$ARGUMENTS、handoffs、/slash-commands）。
• 扩展过于简略的描述，加入使用触发条件。
• 工作流步骤使用祈使语气。
• 确保技能内容完整且可移植。
• 不要添加多余的文档文件（README、CHANGELOG 等）。

后续步骤

转换完成后：

• 检查生成的 SKILL.md 是否完整。
• 删除 scripts/、references/、assets/ 中未使用的示例文件。
• 如适用，更新 AGENTS.md/CLAUDE.md 中的技能清单。
• 如有需要，为运行时集成创建符号链接。