create-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill & Command Generator

Skill & Command 生成器

Generate well-structured skills or slash commands. Both are markdown files with YAML frontmatter—they share the same structure but differ in how they're triggered and described.

生成结构清晰的skill或斜杠命令。二者均为带有YAML前置元数据的Markdown文件——它们结构相同，但触发方式和描述方式有所区别。

Phase 0: Understand Requirements

阶段0：理解需求

Parse

$ARGUMENTS

for type hint. If

$ARGUMENTS

is empty or insufficient, use AskUserQuestion to gather requirements — users are often unclear on what type of artifact they need or what the best design is.

Use AskUserQuestion to collect:

Primary objective — What should this do?
Trigger scenarios — When should it activate?
Inputs/outputs — What does it receive and produce?
Complexity — Simple, standard, or complex?
Execution needs — Isolated context? Delegated to specialized agent? Proceed to Phase 1 when at minimum Objective and Trigger Scenarios are established. Remaining dimensions can be resolved during generation.

解析

$ARGUMENTS

获取类型提示。如果

$ARGUMENTS

为空或信息不足，使用AskUserQuestion工具收集需求——用户通常不清楚自己需要哪种类型的产物，或者最佳设计方案是什么。

使用AskUserQuestion收集以下信息：

核心目标——这个skill/命令应该实现什么功能？
触发场景——何时应该激活它？
输入/输出——它接收什么输入，产生什么输出？
复杂度——简单、标准还是复杂？
执行需求——是否需要独立上下文？是否需要委托给专业Agent？至少确定目标和触发场景后，再进入阶段1。其余维度可在生成过程中逐步明确。

Phase 1: Generate

阶段1：生成

Apply these principles throughout generation: use imperative voice and terse phrasing because every token in a generated skill body costs budget on every invocation, and Claude extrapolates well from precise nudges. Prefer instruction over example — state the rule with its reasoning so it generalizes to every input.

If creating a new skill directory (not editing an existing file):

bash

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

Exit 0 = directory created, proceed to Step 1. Exit 1 = naming collision; ask user whether to overwrite or rename.

在整个生成过程中遵循以下原则：使用祈使语气和简洁措辞，因为生成的skill主体中的每个token在每次调用时都会消耗预算，而Claude能从精确的提示中很好地推断内容。优先使用指令而非示例——说明规则及其原因，使其能推广到所有输入。

如果创建新的skill目录（而非编辑现有文件）：

bash

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

退出码0 = 目录已创建，进入步骤1。退出码1 = 命名冲突；询问用户是否覆盖或重命名。

Step 1 — Choose type

步骤1 — 选择类型

Skills: Trigger-rich, third-person description ("This skill should be used when..."); auto-triggered by routing
Commands: Concise, verb-first description, under 60 chars; user-invoked via
```
/
```
menu

Skills： 触发场景丰富，采用第三人称描述（"当...时应使用本skill"）；通过路由自动触发
Commands： 简洁、以动词开头的描述，不超过60字符；用户通过
```
/
```
菜单手动调用

Step 2 — Write frontmatter

步骤2 — 编写前置元数据

Read

${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/frontmatter-options.md

for the full field catalog, description patterns, tool selection framework, and execution modifiers.

Description density rules: Keep descriptions under 150 tokens (200 absolute max) — they load every session. Descriptions over 250 characters are truncated in the skill listing. Derive trigger phrases from the user's actual words in Phase 0, not paraphrases. See the token budget, pushy routing pattern, and trigger derivation principles in

frontmatter-options.md

Intensional over extensional — apply to all generated content. State the rule directly with its reasoning rather than listing examples that imply the rule. An intensional rule ("quoted phrases must be verbatim user speech because routing matches on literal tokens") generalizes to every input the skill will encounter. An extensional approach requires the reader to reverse-engineer the rule — two reasoning hops instead of one, covering only the shape of those specific examples. Since this skill generates instructions that will themselves guide further generation, the quality of reasoning propagates.

阅读

${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/frontmatter-options.md

获取完整字段目录、描述模式、工具选择框架和执行修饰符。

描述密度规则： 描述内容控制在150个token以内（最多不超过200个）——它们会在每个会话中加载。超过250字符的描述会在skill列表中被截断。从阶段0中用户的实际表述提取触发短语，而非改写后的内容。请查看

frontmatter-options.md

中的token预算、主动路由模式和触发短语推导原则。

内涵优先于外延——适用于所有生成内容。 直接说明规则及其原因，而非列出隐含规则的示例。内涵式规则（"引用短语必须与用户原话完全一致，因为路由匹配基于字面token"）能推广到skill将遇到的所有输入。外延式方法需要读者反向推导规则——需要两次推理步骤，且仅覆盖特定示例的形式。由于本skill生成的指令将指导后续生成，推理质量会层层传递。

Step 3 — Validate description discoverability

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

Before writing the body, verify the description will route correctly. Mentally generate:

3 should-trigger prompts — realistic user messages that should activate this skill. Include at least one naive phrasing from a user who has never heard of the skill.
3 should-NOT-trigger prompts — messages in adjacent domains that are close but should not activate. These test whether the description is too broad.

Evaluate: does the description cover all should-trigger prompts? Would it plausibly reject the should-NOT-trigger prompts? If coverage is weak, revise the description — add missing trigger phrases, tighten language to exclude adjacent domains, or add a negative trigger ("Not for X").

This step catches routing misses before the rest of the skill is built. Proceed when description coverage is adequate.

在编写主体内容前，验证描述能否正确路由。在脑海中生成：

3个应触发的提示——能激活本skill的真实用户消息。至少包含一个从未听说过本skill的用户会使用的朴素表述。
3个不应触发的提示——属于相邻领域、看似相关但不应激活的消息。用于测试描述是否过于宽泛。

评估：描述是否覆盖了所有应触发的提示？是否能合理排除不应触发的提示？如果覆盖范围不足，修改描述——添加缺失的触发短语、收紧措辞以排除相邻领域，或添加否定触发条件（"不适用于X场景"）。

此步骤能在skill其余部分构建完成前发现路由问题。当描述覆盖范围足够时，再继续下一步。

Step 4 — Write body

步骤4 — 编写主体内容

Construction rules:

State objective explicitly in first sentence
Use imperative voice ("Analyze", "Generate", "Identify") — no first-person ("I will", "I am")
Context only when necessary for understanding
XML tags only for complex structured data
No "When to Use This Skill" section — body loads only after triggering; routing guidance there is never read by the routing decision
Avoid headers deeper than H3 — deep nesting signals content that belongs in
```
references/
```
, not
```
SKILL.md
```
Use bang-backtick syntax for dynamic context injection when real-time data (git status, file list, env vars) improves the skill without requiring a tool call
Preserve variable bindings when collapsing code blocks to prose. Code blocks serve two purposes: illustrating an operation and establishing workflow state. When a code block assigns variables (
```
BASE=...
```
,
```
BRANCH=...
```
) that later steps reference, collapsing it to prose without preserving the bindings leaves downstream
```
$VAR
```
references unbound. Add a "derive working variables" preamble that explicitly binds each variable in prose before the steps that use them

Both skills and commands follow the same body pattern:

markdown

undefined

构建规则：

第一句明确说明目标
使用祈使语气（"分析"、"生成"、"识别"）——不使用第一人称（"我将"、"我是"）
仅在理解所需时提供上下文
仅对复杂结构化数据使用XML标签
不包含"何时使用本skill"章节——主体内容仅在触发后加载；路由决策不会读取此处的路由指导
避免超过H3的标题层级——深层嵌套意味着内容应放在
```
references/
```
目录下，而非
```
SKILL.md
```
中
当实时数据（git状态、文件列表、环境变量）能提升skill性能且无需调用工具时，使用感叹号+反引号语法注入动态上下文
将代码块转换为 prose 时保留变量绑定。 代码块有两个作用：演示操作和建立工作流状态。当代码块赋值了后续步骤会引用的变量（
```
BASE=...
```
、
```
BRANCH=...
```
）时，若将其转换为 prose 却不保留绑定，会导致下游
```
$VAR
```
引用无绑定值。添加"推导工作变量"前置部分，在使用变量的步骤前，以prose形式显式绑定每个变量

Skill和命令遵循相同的主体结构：

markdown

undefined

Name

名称

Brief overview (1-2 sentences).

简要概述（1-2句话）。

Process

流程

Step one (imperative voice)
Step two
Step three


**Dynamic Content:**

| Syntax | Purpose |
|--------|---------|
| `$ARGUMENTS` | All arguments as string |
| `$1`, `$2`, `$3` | Positional arguments (shell-style quoting for multi-word values) |
| `@path/file` | Load file contents |
| `@$1` | Load file from argument |
| Exclamation + backticks | Execute bash command, include output |
| `${CLAUDE_SKILL_DIR}` | Path to the skill's own directory (use for referencing bundled scripts/files) |
| `${CLAUDE_SESSION_ID}` | Current session ID (useful for logging or session-specific output files) |

**Example — injecting live context.** In a skill body, write lines like:

- Current branch: !\`git branch --show-current\`
- Recent commits: !\`git log --oneline -5\`
- Changed files: !\`git diff --name-only\`

Then add directives like "Summarize this pull request..."

These commands run when the skill is invoked. The model sees only the output — no tool calls needed. Use this for infallible probes (git status, env vars, file trees, process output) where failure is rare and the output is informational. Do not use for commands that may fail or need exit-code branching — those require Bash tool calls so the model can handle errors.

> **Note:** The backslashes above escape the backticks so this documentation
> doesn't execute — in a real skill, write !\`cmd\` without the backslashes.

步骤一（祈使语气）
步骤二
步骤三


**动态内容：**

| 语法 | 用途 |
|--------|---------|
| `$ARGUMENTS` | 所有参数的字符串形式 |
| `$1`, `$2`, `$3` | 位置参数（多值参数使用shell风格引号） |
| `@path/file` | 加载文件内容 |
| `@$1` | 从参数指定路径加载文件 |
| 感叹号+反引号 | 执行bash命令并包含输出 |
| `${CLAUDE_SKILL_DIR}` | skill自身目录的路径（用于引用捆绑的脚本/文件） |
| `${CLAUDE_SESSION_ID}` | 当前会话ID（用于日志记录或会话特定的输出文件） |

**示例 — 注入实时上下文。** 在skill主体中，可编写如下内容：

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

然后添加诸如"总结此拉取请求..."之类的指令

这些命令会在skill调用时执行。模型只会看到输出——无需调用工具。将此用于可靠的探测操作（git状态、环境变量、文件树、进程输出），这些操作失败概率低且输出具有参考价值。不要将其用于可能失败或需要根据退出码分支的命令——这类场景需要使用Bash工具调用，以便模型处理错误。

> **注意：** 上述示例中的反斜杠是为了转义反引号，避免文档执行命令——在实际skill中，直接编写!\`cmd\`即可，无需反斜杠。

Step 5 — Script opportunity scan

步骤5 — 脚本机会扫描

Read

${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md

and apply the five signal patterns to every workflow step in the skill being generated:

Signal	Question	If yes →
Repeated Generation	Does any step produce the same structure with different params across invocations?	Parameterized script in `scripts/`
Unclear Tool Choice	Does any step combine multiple tools in a fragile sequence naturally expressible as one function?	Script the procedure
Rigid Contract	Can you write `--help` text for this step right now without ambiguity?	CLI candidate — delegate design to `create-cli`
Dual-Use Potential	Would a user want to run this step from the terminal, outside the skill workflow?	Design as proper CLI from the start
Consistency Critical	Must this step produce bit-for-bit identical output for identical inputs?	Script — never LLM generation

For each identified script candidate:

Choose the archetype from
```
references/script-patterns.md
```
(init/validate/transform/package/query)
If the interface is non-trivial, delegate to
```
claude-skills:create-cli
```
skill to design it
Scaffold the script in
```
scripts/
```
using the Python template from
```
references/script-patterns.md
```
Wire it into SKILL.md with: trigger condition, exact invocation, output interpretation

Wiring rule: A script reference must state when to invoke (trigger condition), how to invoke (exact command with flags), and what to do with the result (exit code handling, which output fields matter).

阅读

${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md

，并将五种信号模式应用于正在生成的skill中的每个工作流步骤：

信号	问题	如果是 →
重复生成	是否有步骤会在不同调用中生成结构相同但参数不同的内容？	在 `scripts/` 目录下创建参数化脚本
工具选择模糊	是否有步骤将多个工具组合成脆弱的序列，而这些序列自然可以用一个函数表达？	将该过程编写为脚本
严格契约	你现在能否为该步骤编写无歧义的 `--help` 文本？	CLI候选——将设计委托给 `create-cli`
双重用途潜力	用户是否希望在skill工作流之外，从终端运行该步骤？	从一开始就设计为标准CLI
一致性关键	该步骤必须为相同输入生成完全相同的输出吗？	编写脚本——绝不使用LLM生成

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

从
```
references/script-patterns.md
```
中选择原型（初始化/验证/转换/打包/查询）
如果接口非 trivial，委托给
```
claude-skills:create-cli
```
skill进行设计
使用
```
references/script-patterns.md
```
中的Python模板在
```
scripts/
```
目录下搭建脚本框架
在SKILL.md中关联脚本：说明触发条件、精确调用方式、输出解释

关联规则： 脚本引用必须说明何时调用（触发条件）、如何调用（带标志的精确命令），以及如何处理结果（退出码处理、关注哪些输出字段）。

Step 6 — Check delegation

步骤6 — 检查委托

Scan for existing resources before finalizing:

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

Common delegation patterns:

Git commits →
```
Skill: claude-coding:commit
```

Always use fully qualified names:

```
Skill: plugin-dev:hook-development
```
(not just "hook-development")
```
SlashCommand: /plugin-dev:create-plugin
```
(not just "create-plugin")

Task: subagent_type=plugin-dev:agent-creator

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

查看可用资源：skills、commands、agents、MCPs
针对每个工作流步骤，询问："我们是否已有该功能？"

常见委托模式：

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

Step 7 — Validate

步骤7 — 验证

bash

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

Exit 0 = proceed to Phase 2. Exit 1 = parse the

errors

array; each entry has

field

message

severity

. Resolve all

critical

and

major

items before writing to disk.

bash

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

退出码0 = 进入阶段2。退出码1 = 解析

errors

数组；每个条目包含

field

、

message

、

severity

。在写入磁盘前解决所有

critical

和

major

级别的问题。

Phase 2: Deliver

阶段2：交付

Output Paths

输出路径

Type	Location
User skill	`~/.claude/skills/<name>/SKILL.md`
User command	`~/.claude/commands/<name>.md`
Project skill	`.claude/skills/<name>/SKILL.md`
Project command	`.claude/commands/<name>.md`

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

Write and Confirm

写入并确认

Before writing:

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

写入前：

将写入：[路径]
这将[创建新文件 / 覆盖现有文件]。
是否继续？

Explain Your Choices

解释你的选择

When presenting the generated skill/command to the user, briefly explain:

What you set and why — "Added
```
allowed-tools
```
to scope Bash to git commands only, since the skill only needs git for commits"
What you excluded and why — "
```
hooks
```
omitted (no validation needed),
```
disable-model-invocation
```
left unset (auto-triggering is appropriate)"
Add more trigger phrases if routing misses expected inputs

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

你设置了什么以及原因——"添加了
```
allowed-tools
```
将Bash限定为仅git命令，因为该skill仅需要git进行提交"
你排除了什么以及原因——"省略了
```
hooks
```
（无需验证），未设置
```
disable-model-invocation
```
（自动触发是合适的）"
如果路由遗漏了预期输入，添加更多触发短语

Package for Distribution

打包用于分发

Only when user explicitly requests a distributable file, run:

bash

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

Exit 0 =

.skill

file created at output path. Exit 1 = validation failed; read stdout for details.

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

bash

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

退出码0 = 在输出路径创建了

.skill

文件。退出码1 = 验证失败；查看标准输出获取详细信息。

After Creation

创建完成后

Summarize what was created:

Name and type
Path
How to invoke/trigger
Suggested test scenario

总结创建的内容：

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

Phase 3: Structural Lint

阶段3：结构检查

After writing the skill to disk, invoke the skill-lint agent to run a structural audit:

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."

Wait for the agent to complete. If it auto-applied fixes, note them in the Phase 4 summary. If it reports minor findings, include them in the evaluation output for the user to decide.

Proceed to Phase 4 when the lint agent returns.

将skill写入磁盘后，调用skill-lint agent进行结构审计：

使用Task工具，subagent_type=claude-skills:skill-lint:
"检查<skill目录路径>下的skill。自动应用critical和major级别的修复，将minor级别的发现报告给用户供其决策。"

等待agent完成。如果它自动应用了修复，在阶段4的总结中注明。如果它报告了minor级别的发现，将其包含在评估输出中供用户决定。

当lint agent返回结果后，进入阶段4。

Phase 4: Evaluate

阶段4：评估

Score the generated skill/command:

Dimension	Criteria
Clarity (0-10)	Instructions unambiguous, objective clear
Precision (0-10)	Appropriate specificity without over-constraint
Efficiency (0-10)	Token economy—maximum value per token
Completeness (0-10)	Covers requirements without gaps or excess
Usability (0-10)	Practical, actionable, appropriate for target use

Target: 9.0/10.0. If below, refine once addressing the weakest dimension, then deliver.

Before finalizing, load

${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/generation-standards.md

and verify the validation checklist passes.

Execute phases sequentially.

为生成的skill/命令评分：

维度	标准
清晰度（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

并验证是否通过验证清单。

按顺序执行各个阶段。