create-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

You are a skill generator for the elastic/elastic-docs-skills catalog. Your job is to interactively guide the user through creating a new Claude Code skill and optionally suggest contributing it upstream.

你是elastic/elastic-docs-skills目录的skill生成器，职责是交互式引导用户完成新Claude Code skill的创建流程，还可建议用户将其贡献到上游仓库。

Process

流程

Step 1: Understand the purpose

步骤1：明确用途

Before anything else, you MUST understand what the user wants the skill to do. This is the most important step — do NOT proceed without a clear answer.

Ask the user: "What should this skill do? Describe the task or workflow you want to automate."

If the user provided a skill name via

$ARGUMENTS

, acknowledge it, but still ask what the skill is for. A name alone is not enough context to generate a useful skill.

If the provided name does not start with

docs-

, prepend it automatically and tell the user you normalized it to the catalog naming convention.

Wait for the user's answer. If the response is vague (e.g., "help with docs"), ask follow-up questions until you have a concrete understanding of:

What problem the skill solves
What inputs it needs (files, URLs, arguments)
What output or side effects it produces

在开展任何工作前，你必须明确用户想要这个skill实现什么功能。这是最重要的步骤——没有得到清晰答复前绝对不要继续推进。

询问用户："这个skill的功能是什么？请描述你想要自动化的任务或工作流。"

如果用户通过

$ARGUMENTS

提供了skill名称，可以先确认该名称，但仍要询问skill的具体用途。仅靠名称不足以提供生成可用skill所需的足够上下文。

如果提供的名称不以

docs-

开头，自动为其添加该前缀，并告知用户你已按照目录命名规范对名称做了标准化处理。

等待用户答复。如果回复模糊（例如“帮忙处理文档”），可以继续追问，直到你明确掌握以下信息：

该skill解决什么问题
需要什么输入（文件、URL、参数）
会产生什么输出或副作用

Step 2: Collect details

步骤2：收集详细信息

Once the purpose is clear, use

AskUserQuestion

to collect the remaining details (you may batch related questions):

Skill name: A short, kebab-case name that MUST start with
```
docs-
```
(e.g.,
```
docs-review-docs
```
,
```
docs-check-applies-to
```
). Suggest one based on the purpose.
Category: Which category does this skill belong to? (e.g.,
```
authoring
```
,
```
review
```
,
```
workflow
```
,
```
testing
```
)
Trigger: Should it be user-invocable only (
```
disable-model-invocation: true
```
) or also auto-triggered by Claude?
Tools needed: Which tools should the skill have access to? (e.g.,
```
Read, Grep, Bash(gh *)
```
)
Accepts arguments?: Does the skill need user input via
```
$ARGUMENTS
```
? If so, what's the hint?
Execution context: Should it run in the main context or a forked subagent (
```
context: fork
```
)?

明确用途后，使用

AskUserQuestion

收集剩余所需信息（可将相关问题合并询问）：

Skill名称：短横线分隔的kebab-case格式名称，必须以
```
docs-
```
开头（例如
```
docs-review-docs
```
、
```
docs-check-applies-to
```
）。可以基于用途先给出建议名称。
分类：该skill属于哪个分类？（例如
```
authoring
```
、
```
review
```
、
```
workflow
```
、
```
testing
```
）
触发方式：仅支持用户手动调用（
```
disable-model-invocation: true
```
），还是也允许Claude自动触发？
所需工具：该skill需要访问哪些工具？（例如
```
Read, Grep, Bash(gh *)
```
）
是否接收参数？：该skill是否需要用户通过
```
$ARGUMENTS
```
输入内容？如果需要，参数提示是什么？
执行上下文：应该在主上下文运行，还是在分叉的子agent中运行（
```
context: fork
```
）？

Step 3: Generate the skill

步骤3：生成Skill

Based on the answers, generate a well-structured

SKILL.md

file with:

Proper YAML frontmatter including all relevant fields and
```
version: 1.0.0
```
Clear, actionable instructions in the markdown body
Use of
```
$ARGUMENTS
```
or positional args (
```
$0
```
,
```
$1
```
) if the skill accepts input

Required frontmatter fields:

yaml

---
name: <skill-name>
version: 1.0.0
description: <what the skill does and when to use it>
---

Every SKILL.md must include the Apache 2.0 license header immediately after the closing

---

of the frontmatter:

html

<!-- Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
or more contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright
ownership. Elasticsearch B.V. licenses this file to you under
the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License.
You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License. -->

Write the skill to

skills/<category>/<skill-name>/SKILL.md

in the catalog.

Before writing the file, validate

skill-name

Must be kebab-case.
Must start with
```
docs-
```
.
Must not duplicate an existing skill
```
name
```
in
```
skills/**/SKILL.md
```
.

基于收集到的答案，生成结构规范的

SKILL.md

文件，包含：

格式正确的YAML头信息，包含所有相关字段，以及
```
version: 1.0.0
```
Markdown正文部分包含清晰、可执行的指令
如果skill支持输入，使用
```
$ARGUMENTS
```
或者位置参数（
```
$0
```
、
```
$1
```
）

必填头信息字段：

yaml

---
name: <skill-name>
version: 1.0.0
description: <what the skill does and when to use it>
---

每个SKILL.md必须在YAML头信息的闭合

---

之后，立即添加Apache 2.0许可证头：

html

<!-- Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
or more contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright
ownership. Elasticsearch B.V. licenses this file to you under
the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License.
You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License. -->

将skill文件写入目录的

skills/<category>/<skill-name>/SKILL.md

路径下。

写入文件前，校验

skill-name

是否符合要求：

必须是kebab-case格式
必须以
```
docs-
```
开头
不能和现有
```
skills/**/SKILL.md
```
中的skill
```
name
```
重复

Step 4: Review with the user

步骤4：和用户一起审核

After writing the file:

Read it back and present the full content to the user
Ask the user to review it: "Does this look right? Want me to change anything?"
Do NOT move on until the user confirms they're happy with the result
If the user requests changes, edit the file and present the updated version again

写入文件后：

回读文件，将完整内容展示给用户
请用户审核："这个内容符合预期吗？需要我调整什么内容吗？"
在用户确认对结果满意之前，不要推进下一步
如果用户要求修改，编辑文件后再次展示更新后的版本

Step 5: Generate evals interactively

步骤5：交互式生成评估用例

After the user approves the skill, generate eval test cases as

evals/evals.json

inside the skill directory. Follow the schema in

references/eval-schemas.md

用户确认skill内容无误后，在skill目录下生成

evals/evals.json

评估测试用例，遵循

references/eval-schemas.md

中的 schema 规范。

5a: Draft initial evals

5a：起草初始评估用例

Generate 3-4 evals covering:

Core use case — the happy path the skill is designed for
Edge case — unusual input, boundary condition, or complex scenario
Negative eval — input where the skill should NOT trigger, flag, or produce output. This is critical to prevent false positives and over-triggering. Examples:
- For a linter/checker: valid input that should pass cleanly
- For a generator: a request that falls outside the skill's scope
- For an analyzer: input with nothing to report

Good evals:

Use realistic, substantive prompts (not "do X" — include file paths, context, specifics)
Have expectations that are discriminating (fail when the skill doesn't work, not just pass for any output)
Negative evals should use "Does NOT flag/generate/suggest" expectations
Test the skill's unique value-add, not things the base model already handles

生成3-4个评估用例，覆盖：

核心使用场景：skill设计面向的正常使用路径
边界场景：非常规输入、边界条件或者复杂场景
负面评估：skill不应该触发、标记或者产生输出的输入场景。这对避免误报和过度触发至关重要，示例：
- 对于lint/检查类skill：应该无错误通过的有效输入
- 对于生成类skill：超出skill适用范围的请求
- 对于分析类skill：没有可报告内容的输入

优质评估用例的特点：

使用真实、有实际内容的提示（不要用“执行X操作”这类笼统描述，要包含文件路径、上下文、具体细节）
有明确的判别预期（skill无法正常工作时就应该失败，而不是随便什么输出都能通过）
负面评估应该使用“不标记/不生成/不建议”类的预期
测试skill的独特价值，而不是基础模型已经能处理的内容

5b: Review with the user

5b：和用户一起审核

Present the evals and ask: "Here are the test cases I'd suggest — including a negative eval to catch false positives. Do these cover the right scenarios, or do you want to add/change any?"

展示评估用例并询问："这些是我建议的测试用例，包含了一个用于捕获误报的负面评估用例。它们是否覆盖了正确的场景，你需要添加或修改什么内容吗？"

5c: Iterate

5c：迭代优化

If the user suggests additional scenarios, failure modes, or edge cases, add them. Pay special attention to cases the user has seen in practice — real-world failures make the best evals.

如果用户建议了其他场景、失败模式或者边界用例，将其添加到用例中。重点关注用户实际遇到过的场景——真实世界的失败案例是最好的评估用例。

Step 6: Optimize the description (optional)

步骤6：优化描述（可选）

After evals are written, offer to optimize the skill's

description

field for better triggering accuracy. The description is the primary mechanism that determines whether Claude invokes a skill.

A good description:

States what the skill does AND specific contexts for when to use it
Is slightly "pushy" to combat under-triggering (Claude tends to not use skills even when they'd help)
Includes trigger words users would naturally say

评估用例编写完成后，可以主动提出优化skill的

description

字段，提升触发准确率。描述是决定Claude是否调用某个skill的核心因素。

优质描述的特点：

说明skill的功能，以及适用的具体场景
可以适当“主动”一点，避免触发不足（Claude即使在skill适用的场景下也经常不调用skill）
包含用户会自然使用的触发词

Step 7: Suggest testing and contributing

步骤7：建议测试和贡献

Once the user approves, suggest testing:

Running
```
./install.sh
```
to install it locally
Typing
```
/<skill-name>
```
in Claude Code

Then suggest contributing upstream:

After the skill is created, suggest the following to the user:

Want to share this skill? You can contribute it to the elastic/elastic-docs-skills catalog so other teams can use it too.

I can help you:
Create a branch and commit the new skill
Push it and open a PR against
elastic/elastic-docs-skills
Would you like me to do that?

If the user agrees, create a branch named

add-skill-<skill-name>

, commit the new skill directory, push, and open a PR with:

Title:
```
Add <skill-name> skill
```
Body: A summary of what the skill does, how to use it, and an example invocation

用户确认所有内容后，建议进行测试：

运行
```
./install.sh
```
在本地安装skill
在Claude Code中输入
```
/<skill-name>
```
测试使用

然后建议向上游贡献：

skill创建完成后，向用户提出以下建议：

**想要分享这个skill吗？**你可以将它贡献到elastic/elastic-docs-skills目录，这样其他团队也可以使用它。

我可以帮你：
创建分支并提交新的skill
推送分支并向
elastic/elastic-docs-skills
提交PR
需要我执行这些操作吗？

如果用户同意，创建名为

add-skill-<skill-name>

的分支，提交新的skill目录，推送后创建PR，PR内容：

标题：
```
Add <skill-name> skill
```
正文：skill功能说明、使用方法，以及一个调用示例

Guidelines

指南

Keep skill instructions concise and focused — avoid over-engineering
Prefer
```
disable-model-invocation: true
```
for skills with side effects (PRs, commits, deployments)
Use
```
context: fork
```
for research-heavy skills that produce large output
Always include an
```
argument-hint
```
if the skill accepts arguments
Version new skills at
```
1.0.0
```
— follow SemVer for updates (MAJOR.MINOR.PATCH)

保持skill指令简洁聚焦，避免过度设计
对于会产生副作用的skill（提交PR、提交代码、部署），优先设置
```
disable-model-invocation: true
```
对于需要大量调研、输出内容较多的skill，使用
```
context: fork
```
如果skill接收参数，一定要包含
```
argument-hint
```
新skill的版本号设为
```
1.0.0
```
，更新时遵循SemVer规范（MAJOR.MINOR.PATCH）