命令技能创建器

创建命令型技能——一种指导 Claude 分阶段执行多步骤工作流的指令式提示。这类技能是用户主动调用的 /slash-commands，而非被动提供的参考资料。

命令技能存放在项目级别的 .claude/skills/<name>/SKILL.md 文件中，通过 /name [参数] 的形式被调用。

何时使用此技能 vs skill-creator

• 本技能：用于执行具体操作的命令——部署、提交、迁移、同步、发布、初始化等。具有副作用，包含审批环节，支持分阶段执行。
• skill-creator：提供信息性内容——编码规范、API 参考、框架指南等。无副作用，由上下文自动触发。

创建流程

步骤 1：明确意图

确定该命令要自动化的内容。可通过提问或从对话历史中提取以下信息：

• 这个命令具体做什么？主要包含哪些阶段？
• 哪些操作会产生副作用？（如提交代码、部署、修改文件、调用外部 API）
• 是否需要参数？参数类型是什么？
• 是否涉及多个仓库或项目？
• 在不可逆操作前是否需要用户审批？
• 需要多复杂的模型推理？（大多数命令使用默认模型即可；复杂多阶段逻辑可能需要 opus）

若用户说“把这个变成命令”，请从对话历史中提取实际工作流程——使用了哪些工具、执行顺序、修正过程等。

步骤 2：设计 frontmatter

根据命令特性选择合适的字段。详见下方 frontmatter 参考表。

最小可行 frontmatter：

---
name: my-command
description: 它的功能及使用场景
disable-model-invocation: true
---

disable-model-invocation: true 被设为命令技能的默认值，因为命令的本质就是有副作用。如果没有副作用，它就应归类为知识型技能。设置此项为 true 可确保命令仅在用户显式调用时才运行，防止 Claude 自主部署、提交或修改状态。

根据需求添加更多字段：

• 若需参数 → argument-hint: "[arg-name]"
• 若需强推理能力 → model: opus
• 若需限制工具使用 → allowed-tools: Read, Bash(specific-cmd *)
• 若需独立探索环境 → context: fork + agent: Explore

步骤 3：划分执行阶段

将命令拆分为编号阶段，并使用 Markdown 标题（##）标注。Claude 对编号标题序列的识别非常可靠，而密集段落容易被忽略。

常见阶段结构：

1. 预检阶段 - 验证前置条件，读取配置，检查当前状态
2. 调研/发现阶段 - 收集决策所需信息（可并行使用子代理）
3. 展示与审批阶段 - 展示建议方案，等待用户明确批准
4. 执行阶段 - 实际执行变更操作
5. 验证阶段 - 执行冒烟测试、健康检查
6. 总结阶段 - 汇报最终结果

并非所有命令都需要完整六个阶段。例如一个格式化工具可能只需“执行 + 验证”。

步骤 4：加入安全机制

对每个有副作用的阶段，必须包含以下防护措施：

• 审批门禁：在继续前添加 "STOP and wait for user approval before proceeding."
• 错误处理：如“若 X 失败，则停止并显示错误信息。不得进入第 N 阶段。”
• 回滚路径：说明出错后如何撤销变更
• 验证机制：确认每一步操作成功后再进入下一步

这些不是繁琐流程，而是防止命令自主部署损坏代码或提交垃圾内容的关键保障。一次 2 秒的审批等待，远低于回滚一次失败部署的成本。

步骤 5：编写 SKILL.md

生成完整的技能文件。保持总长度在 200 行以内——命令技能本质是提示词，而非文档。若需大量参考材料，请使用辅助文件。

始终以参数校验开头：

The target is: $ARGUMENTS

If no argument was provided, ask the user for one and stop.

随后是规则说明、各阶段内容、结果模板。

步骤 6：进行审计

逐项核对下方审计清单。在最终定稿前修复所有问题，并向用户提供审计结果。

步骤 7：放置文件

将技能保存至目标项目路径：

<project>/.claude/skills/<command-name>/SKILL.md

如需辅助文件，应与 SKILL.md 同级存放。

Frontmatter 参考表

$ARGUMENTS

$ARGUMENTS 会被替换为用户输入的完整参数字符串。可通过 $0、$1 或 $ARGUMENTS[N]（0 起始索引）访问位置参数。

/deploy twitter staging
# $ARGUMENTS = "twitter staging", $0 = "twitter", $1 = "staging"

避免过度指定参数解析逻辑。信任 Claude 能理解自然语言表达。只需描述期望输入，让 Claude 自行验证，而非编写脆弱的格式解析器。

路径变量

禁止硬编码绝对路径。应使用以下方式：

• ${CLAUDE_PROJECT_DIR} —— 项目根目录
• ${CLAUDE_SKILL_DIR} —— 当前技能所在目录（用于打包脚本）
• 相对于仓库根目录的相对路径

设计模式

参见 [references/design-patterns.md](references/design-patterns.md) 获取详细模式与完整示例。快速参考如下：

反模式警示

审查命令技能时请注意以下常见问题：

• 硬编码路径：/Users/someone/... → 改用 ${CLAUDE_PROJECT_DIR} 或相对路径
• 缺少安全机制：有副作用的命令未设置 disable-model-invocation: true
• 过度指定参数：使用复杂解析逻辑代替自然语言描述
• 缺乏检查点：未展示即将发生的变化即直接修改
• 盲目编辑：未读取文件内容即进行修改
• 静默失败：无错误处理或状态反馈
• 无视上下文：未读取 CLAUDE.md、现有规范或配置文件
• 单体提示过长：SKILL.md 超过 500 行，未使用辅助文件

审计清单

每个命令技能在正式定稿前必须通过以下检查项：

1. 存在副作用时，disable-model-invocation: true
2. 命令接收参数时，argument-hint 已定义
3. 无硬编码的绝对路径
4. 跨仓库引用使用 grep 或 glob 等自适应发现方式
5. 包含缺失 $ARGUMENTS 的保护判断
6. 在破坏性或不可逆操作前设有审批门禁
7. 明确报告执行结果（成功/失败/下一步）
8. SKILL.md 小于 200 行（超限部分使用辅助文件）
9. 明确错误处理逻辑（如“若 X 失败，则停止并显示错误”）
10. 使用 ${CLAUDE_PROJECT_DIR} 或相对路径，禁止绝对路径
11. 修改文件前已读取其内容（禁止盲改）
12. 跨仓库操作时，已读取目标项目的 CLAUDE.md