Back to Details

creating-skills

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Creating a New Skill

创建新Skill

Skills follow the Agent Skills open standard.
Skills遵循Agent Skills开放标准。

1. Choose a category

1. 选择分类

Place the skill under the most specific matching category in 
skills/
:
CategoryWhen to use
python/
Python tooling, packaging, dependency management
dagster/
Dagster pipelines, code locations, 
dg
usage
infrastructure/
Pulumi IaC, secrets, Vault, Kubernetes config
containers/
Docker builds, image conventions
workflow/
Cross-cutting process conventions; meta-skills
If no category fits, create a new one and add a 
README.md
for it.
将skill放置在
skills/
目录下最匹配的具体分类中：
分类使用场景
python/
Python工具、打包、依赖管理
dagster/
Dagster流水线、代码位置、
dg
工具使用
infrastructure/
Pulumi基础设施即代码、密钥管理、Vault、Kubernetes配置
containers/
Docker构建、镜像规范
workflow/
跨领域流程规范；元技能
如果没有合适的分类，创建一个新分类并为其添加
README.md
文件。

2. Create the skill directory

2. 创建skill目录

The directory name becomes the skill's 
name
. Use lowercase letters and hyphens only.
skills/<category>/<skill-name>/
└── SKILL.md
The 
name
in 
SKILL.md
frontmatter must exactly match the directory name.
目录名称即为skill的
name
。仅使用小写字母和连字符。
skills/<category>/<skill-name>/
└── SKILL.md
SKILL.md
前置元数据中的
name
必须完全匹配目录名称。

3. Write SKILL.md

3. 编写SKILL.md

markdown
---
name: <skill-name>           # must match directory name; max 64 chars
description: >               # what it does AND when to use it; max 1024 chars
  <one or two sentences describing the skill and the keywords/scenarios
  that should trigger it>
license: BSD-3-Clause
metadata:
  category: <category>
---
markdown
---
name: <skill-name>           # 必须匹配目录名称；最多64个字符
description: >               # 技能功能及使用场景；最多1024个字符
  <一两句话描述技能内容，以及触发该技能的关键词/场景>
license: BSD-3-Clause
metadata:
  category: <category>
---

Skill Title

Skill标题

...instructions...
undefined
...操作说明...
undefined

Description guidelines (most important field)

描述指南（最重要字段）

The description is what the agent uses to decide whether to activate the skill. Make it trigger-friendly:
  • State both what the skill covers and when to use it.
  • Include the specific tool names, command names, or scenario keywords an agent would encounter when the skill is relevant.
  • Bad: "Conventions for X." — too vague, won't trigger reliably.
  • Good: "Apply X conventions. Use this skill when doing Y or Z — covers A, B, C."
描述字段用于让agent判断是否激活该技能。需便于触发：
  • 同时说明技能涵盖内容和使用时机。
  • 包含agent遇到该技能相关场景时会接触到的特定工具名称、命令名称或场景关键词。
  • 错误示例：“X的规范。”——过于模糊，无法可靠触发。
  • 正确示例：“应用X规范。在执行Y或Z操作时使用本技能——涵盖A、B、C内容。”

4. Apply progressive disclosure

4. 应用渐进式信息披露

Keep 
SKILL.md
under ~500 lines. If the skill has deep reference material (e.g., a detailed API reference, form templates, domain-specific lookup tables), move it to a 
references/
subdirectory and link to it from 
SKILL.md
:
<skill-name>/
├── SKILL.md
└── references/
    └── REFERENCE.md
In 
SKILL.md
, reference the file by relative path:
markdown
See [detailed reference](references/REFERENCE.md) for full option listings.
保持
SKILL.md
内容在约500行以内。如果技能包含深度参考资料（例如详细API参考、表单模板、领域特定查找表），将其移至
references/
子目录，并在
SKILL.md
中添加链接：
<skill-name>/
├── SKILL.md
└── references/
    └── REFERENCE.md
在
SKILL.md
中，通过相对路径引用该文件：
markdown
查看[详细参考](references/REFERENCE.md)获取完整选项列表。

5. Update the indexes

5. 更新索引

After creating the skill, update two places:
  1. Category README (
    skills/<category>/README.md
    ) — add a row to the table.
  2. Top-level skills README (
    skills/README.md
    ) — add a row to the All Skills table.
创建技能后，更新两处内容：
  1. 分类README（
    skills/<category>/README.md
    ）——在表格中添加一行。
  2. 顶级skills目录README（
    skills/README.md
    ）——在所有技能表格中添加一行。

6. Validate

6. 验证

bash
undefined
bash
undefined

Check frontmatter is valid (if skills-ref is available)

检查前置元数据是否有效（若已安装skills-ref）

npx skills-ref validate ./skills/<category>/<skill-name>

If `skills-ref` is not installed, manually verify:
- `name` matches the directory name
- `description` is non-empty and under 1024 characters
- `SKILL.md` is the correct filename (uppercase)
npx skills-ref validate ./skills/<category>/<skill-name>

若未安装`skills-ref`，手动验证：
- `name`与目录名称匹配
- `description`非空且不超过1024字符
- `SKILL.md`文件名正确（大写）