create-skill

技能与命令生成器

生成结构良好的技能或斜杠命令。两者都是带有 YAML frontmatter 的 Markdown 文件——结构相同，但触发方式和描述有所不同。

阶段 0：了解需求

解析 $ARGUMENTS 中的类型提示。如果 $ARGUMENTS 为空或信息不足，请使用 AskUserQuestion 收集需求——用户通常不清楚自己需要哪种类型的产物，或哪种设计最合适。

使用 AskUserQuestion 收集以下信息：

1. 主要目标 — 这应该实现什么？
2. 触发场景 — 什么时候应该触发？
3. 输入/输出 — 它接收什么并产出什么？
4. 复杂度 — 简单、标准还是复杂？
5. 执行需求 — 是否需要隔离上下文？是否需要委派给专用 Agent？ 至少确定目标和触发场景后，再进入阶段 1。其余方面可在生成过程中确定。

阶段 1：生成

在整个生成过程中遵循以下原则：使用祈使语气和简洁措辞，因为生成的技能正文中的每个 token 都会在每次调用时消耗预算，而 Claude 能很好地根据精准提示进行推断。优先使用指令而非示例——说明规则及其原因，使其适用于所有输入。

如果要创建新的技能目录（而不是编辑现有文件）：

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/scripts/init_skill.py <name> --path <dir> [--resources scripts,references,assets] [--examples]

退出码 0 = 目录已创建，继续步骤 1。 退出码 1 = 命名冲突；询问用户是要覆盖还是重命名。

步骤 1 — 选择类型

• 技能： 触发条件丰富，使用第三人称描述（“当……时应使用此技能”）；通过路由自动触发
• 命令： 描述简洁，以动词开头，少于 60 个字符；用户通过 / 菜单调用

步骤 2 — 编写 frontmatter

阅读 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/frontmatter-options.md，了解完整的字段目录、描述模式、工具选择框架和执行修饰符。

描述密度规则： 描述应少于 150 个 token（绝对上限为 200 个）——每个会话都会加载这些描述。技能列表中超过 250 个字符的描述会被截断。从阶段 0 中用户实际使用的措辞提取触发短语，而不是改写。请参阅 frontmatter-options.md 中的 token 预算、强引导路由模式和触发条件提取原则。

内涵优先于外延——适用于所有生成内容。 直接陈述规则及其原因，而不是罗列示例来暗示规则。内涵式规则（“引号中的短语必须是用户原话，因为路由会匹配字面 token”）适用于技能将遇到的所有输入。外延式方法则要求读者反向推导规则——需要两步推理而非一步，而且只涵盖这些特定示例的形式。由于此技能生成的指令本身会进一步指导生成，推理质量会层层传递。

步骤 3 — 验证描述的可发现性

编写正文之前，验证描述是否能正确路由。设想：

1. 3 个应触发的提示 — 应激活此技能的真实用户消息。至少包含一种从未听说过此技能的用户可能使用的朴素说法。
2. 3 个不应触发的提示 — 来自相邻领域、内容相近但不应激活此技能的消息。这些提示用于测试描述是否过于宽泛。

评估：描述是否涵盖所有应触发的提示？是否有充分理由拒绝不应触发的提示？如果覆盖不足，请修改描述——补充缺失的触发短语、收紧措辞以排除相邻领域，或添加否定触发条件（“不适用于 X”）。

此步骤可在构建技能其余部分之前发现路由遗漏。描述覆盖充分后再继续。

第 4 步 — 编写正文

构建规则：

• 在第一句话中明确说明目标
• 使用祈使语气（“分析”“生成”“识别”），不要使用第一人称（“我将”“我是”）
• 仅在理解所必需时提供上下文
• 仅在复杂结构化数据中使用 XML 标签
• 不要添加“何时使用此技能”部分——只有在触发后才会加载正文；路由决策不会读取其中的路由指导
• 标题层级不要深于 H3——深层嵌套意味着相关内容应放在 references/ 中，而不是 SKILL.md 中
• 当实时数据（git 状态、文件列表、环境变量）能改进技能且无需调用工具时，使用感叹号加反引号语法注入动态上下文
• 将代码块折叠为正文时，保留变量绑定。 代码块有两种用途：演示操作，以及建立工作流状态。如果代码块为变量赋值（BASE=...、BRANCH=...），且后续步骤会引用这些变量，将其折叠为正文却不保留绑定，会导致下游的 $VAR 引用未绑定。应在使用这些变量的步骤之前添加“派生工作变量”的前置说明，并在正文中明确绑定每个变量

技能和命令遵循相同的正文模式：

# Name

Brief overview (1-2 sentences).

## Process
1. Step one (imperative voice)
2. Step two
3. Step three

动态内容：

语法	用途
$ARGUMENTS	所有参数组成的字符串
$1、$2、$3	位置参数（多词值使用 shell 风格的引号）
@path/file	加载文件内容
@$1	加载参数指定的文件
感叹号加反引号	执行 bash 命令并包含其输出
${CLAUDE_SKILL_DIR}	技能自身目录的路径（用于引用随附的脚本/文件）
${CLAUDE_SESSION_ID}	当前会话 ID（便于记录日志或生成与会话相关的输出文件）

示例——注入实时上下文。 在技能正文中，写入如下内容：

• 当前分支：!`git branch --show-current`
• 最近提交：!`git log --oneline -5`
• 已更改文件：!`git diff --name-only`

然后添加“总结此拉取请求……”之类的指令。

这些命令会在调用技能时运行。模型只会看到输出，无需调用工具。对于可靠性高的探测命令（git 状态、环境变量、文件树、进程输出），如果很少失败且输出仅供参考，请使用此方法。不要将其用于可能失败或需要根据退出代码分支处理的命令——这些命令需要通过 Bash 工具调用，以便模型处理错误。

注意： 上方的反斜杠用于转义反引号，以免本文档执行这些命令——在实际技能中，应写作 !`cmd`，不带反斜杠。

步骤 5 — 扫描脚本机会

阅读 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md，并将五种信号模式应用于正在生成的技能中的每个工作流步骤：

信号	问题	如果是 →
重复生成	是否有步骤会在多次调用中使用不同参数生成相同结构？	在 scripts/ 中创建参数化脚本
工具选择不明确	是否有步骤以脆弱的顺序组合了多个工具，而这些操作本可以自然地封装为一个函数？	将该过程编写为脚本
契约明确	现在能否毫无歧义地为此步骤编写 --help 文本？	CLI 候选项——委托给 create-cli 设计
双用途潜力	用户是否会希望在技能工作流之外从终端运行此步骤？	从一开始就将其设计为规范的 CLI
一致性至关重要	对于相同输入，此步骤是否必须生成逐位完全相同的输出？	使用脚本——绝不使用 LLM 生成

对于每个已识别的脚本候选项：

1. 从 references/script-patterns.md 中选择原型（init/validate/transform/package/query）
2. 如果接口并非简单明了，委托给 claude-skills:create-cli 技能进行设计
3. 使用 references/script-patterns.md 中的 Python 模板，在 scripts/ 中搭建脚本
4. 在 SKILL.md 中将其接入，说明：触发条件、准确调用方式、输出结果的解读方法

接入规则： 脚本引用必须说明何时调用（触发条件）、如何调用（包含标志的准确命令），以及如何处理结果（退出代码处理方式、需要关注哪些输出字段）。

步骤 6 — 检查委托

最终确定前，扫描现有资源：

Review available: skills, commands, agents, MCPs
For each workflow step, ask: "Do we already have this?"

常见委托模式：

• Git 提交 → Skill: claude-coding:commit

始终使用完整限定名称：

• Skill: plugin-dev:hook-development（不要只写“hook-development”）
• SlashCommand: /plugin-dev:create-plugin（不要只写“create-plugin”）
• Task: subagent_type=plugin-dev:agent-creator

步骤 7 — 验证

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/scripts/validate_skill.py <skill-directory> --output json

退出码为 0 = 继续进入阶段 2。退出码为 1 = 解析 errors 数组；每个条目都包含 field、message、severity。将所有 critical 和 major 项解决后，再写入磁盘。

阶段 2：交付

输出路径

类型	位置
用户技能	~/.claude/skills/<name>/SKILL.md
用户命令	~/.claude/commands/<name>.md
项目技能	.claude/skills/<name>/SKILL.md
项目命令	.claude/commands/<name>.md

写入并确认

写入前：

Writing to: [path]
This will [create new / overwrite existing] file.
Proceed?

说明选择理由

向用户展示生成的技能/命令时，简要说明：

• 设置了什么以及原因——“添加了 allowed-tools，将 Bash 限定为仅执行 git 命令，因为此技能只需使用 git 进行提交”
• 省略了什么以及原因——“省略了 hooks（无需验证），未设置 disable-model-invocation（适合自动触发）”
• 如果路由未能匹配预期输入，请添加更多触发短语

打包分发

仅当用户明确要求提供可分发文件时，才运行：

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/scripts/package_skill.py <skill-directory> [output-dir]

退出码为 0 = 已在输出路径创建 .skill 文件。退出码为 1 = 验证失败；请读取 stdout 了解详情。

创建后

总结创建的内容：

• 名称和类型
• 路径
• 调用/触发方式
• 建议的测试场景

阶段 3：结构检查

将技能写入磁盘后，调用 skill-lint Agent 进行结构审查：

Use Task tool with subagent_type=claude-skills:skill-lint:
"Lint the skill at <path-to-skill-directory>. Auto-apply critical and major fixes, report
minor findings for user decision."

等待 Agent 完成。如果它自动应用了修复，请在阶段 4 的总结中说明。 如果它报告了轻微问题，请将其纳入评估结果，供用户决定。

lint Agent 返回后，继续进入阶段 4。

第 4 阶段：评估

为生成的技能/命令评分：

维度	标准
清晰度（0-10）	指令明确无歧义，目标清晰
精准度（0-10）	具体程度恰当，不过度限制
效率（0-10）	Token 利用率——每个 Token 的价值最大化
完整性（0-10）	涵盖所有要求，无遗漏或冗余
可用性（0-10）	实用、可执行，适合目标用途

目标：9.0/10.0。 如果低于此分数，针对最薄弱的维度改进一次，然后交付。

定稿前，加载 ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/generation-standards.md 并确认验证清单全部通过。

---

按顺序执行各阶段。