命令型技能创建器

创建命令型技能——一种指导 Claude 分阶段执行多步骤工作流的指令式提示。这些是用户显式调用的 /slash-commands，而非被动引用的内容。

命令型技能位于项目级别的 .claude/skills/<name>/SKILL.md 路径下，通过 /name [参数] 形式调用。

与 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：加入安全机制

对每个具有副作用的阶段，添加以下防护措施：

• 审批门禁： "停止并等待用户批准后方可继续。"
• 错误处理： "如果 X 失败，请停止并显示错误信息。不要继续到第 N 阶段。"
• 回滚路径： 出错时如何撤销操作
• 验证机制： 确保每一步操作成功后再进入下一步

这些不是形式主义——它们防止命令自主部署损坏代码或提交垃圾内容。两秒的审批延迟，远低于一次失败部署的回滚成本。

步骤 5：编写 SKILL.md

生成完整的技能文件。保持在 200 行以内——命令型技能是提示词，而非文档。若需大量参考资料，应使用辅助文件。

始终以参数校验开头：

目标为：$ARGUMENTS

若未提供参数，请向用户询问并停止执行。

然后是规则部分、各阶段说明、总结模板。

步骤 6：审计检查

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

步骤 7：放置文件

将技能保存至目标项目目录：

<project>/.claude/skills/<command-name>/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) 获取完整示例和详细模式说明。快速参考：

name: command-skill-creator

version: 0.1.1

description: 用于创建命令型技能的模板与规范，帮助开发者构建安全、可维护的自动化操作。

summary: 一套用于编写命令型技能的结构化指南，涵盖场景匹配、反模式警示与审计清单。

场景匹配

反模式警示

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

• 硬编码路径：如 /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