skill-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Builder

Skill 构建器

Step-by-step guide for creating high-quality agent skills based on the open Agent Skills standard.

基于开源Agent Skills标准创建高质量Agent技能的分步指南。

What is a skill

什么是Skill

A skill is a portable folder containing instructions that teach an AI agent how to handle specific tasks or workflows. Instead of re-explaining preferences, processes, and domain expertise in every session, a skill captures that knowledge once and applies it consistently across interactions and platforms.

A skill contains:

```
SKILL.md
```
(required): instructions in Markdown with YAML frontmatter
```
scripts/
```
(optional): executable code (Javascript, Bash, etc.)
```
references/
```
(optional): documentation loaded as needed
```
assets/
```
(optional): templates, fonts, icons used in output

Skill是一个可移植的文件夹，包含指导AI Agent处理特定任务或工作流的说明。无需在每次会话中重复解释偏好、流程和领域专业知识，Skill可一次性捕获这些知识，并在不同交互和平台中一致应用。

Skill包含：

```
SKILL.md
```
（必填）：带有YAML前置元数据的Markdown格式说明
```
scripts/
```
（可选）：可执行代码（Javascript、Bash等）
```
references/
```
（可选）：按需加载的文档
```
assets/
```
（可选）：输出中使用的模板、字体、图标

Core design principles

核心设计原则

Progressive disclosure: skills use a three-level loading system to minimize token usage while maintaining specialized expertise.

Level 1 (YAML frontmatter): always loaded. Tells the agent when the skill is relevant.
Level 2 (SKILL.md body): loaded when the agent determines the skill applies. Contains full instructions.
Level 3 (Linked files): additional resources the agent navigates only as needed.

Composability: an agent can load multiple skills simultaneously. Your skill should work well alongside others, not assume it's the only capability available.

Portability: skills are an open standard. A well-built skill works across any platform that supports the standard, provided the environment meets any dependencies.

渐进式披露：Skill采用三级加载系统，在保持专业能力的同时最小化令牌消耗。

第一级（YAML前置元数据）：始终加载。告知Agent何时适用该Skill。
第二级（SKILL.md正文）：当Agent判定Skill适用时加载。包含完整说明。
第三级（关联文件）：仅在需要时由Agent访问的额外资源。

可组合性：Agent可同时加载多个Skill。你的Skill应能与其他Skill良好协作，而非假设自己是唯一可用的能力。

可移植性：Skill是一种开源标准。构建良好的Skill可在任何支持该标准的平台上运行，只要环境满足其依赖要求。

Creation process

创建流程

Step 1: Define use cases

步骤1：定义用例

Before writing anything, identify 2-3 concrete use cases. For each one:

Use Case: [name]
Trigger: [what the user says or does]
Steps: [sequence of actions]
Result: [what gets produced at the end]

Key questions:

What should the agent be able to do with this skill?
When should it trigger? (phrases, contexts)
What's the expected output format?
Does it need external tools (MCP servers, APIs) or only built-in capabilities?

Common skill categories:

Document & asset creation — generating consistent, high-quality outputs like documents, presentations, code, designs. Key techniques: embedded style guides, template structures, quality checklists.

Workflow automation — multi-step processes that benefit from consistent methodology. Key techniques: step-by-step workflows with validation gates, iterative refinement loops.

MCP enhancement — workflow guidance layered on top of MCP server tool access. Key techniques: coordinating multiple MCP calls in sequence, embedding domain expertise, error handling for common MCP issues.

在开始编写前，先确定2-3个具体用例。每个用例需包含：

用例：[名称]
触发条件：[用户的言行]
步骤：[操作序列]
结果：[最终产出物]

关键问题：

借助该Skill，Agent应能完成什么任务？
何时触发该Skill？（短语、场景）
预期输出格式是什么？
是否需要外部工具（MCP服务器、API），还是仅需内置能力？

常见Skill类别：

文档与资产创建 — 生成一致、高质量的输出，如文档、演示文稿、代码、设计。核心技巧：嵌入样式指南、模板结构、质量检查表。

工作流自动化 — 受益于一致方法论的多步骤流程。核心技巧：带验证节点的分步工作流、迭代优化循环。

MCP增强 — 基于MCP服务器工具访问的工作流指导。核心技巧：协调多个MCP调用序列、嵌入领域专业知识、常见MCP问题的错误处理。

Step 2: Design the folder structure

步骤2：设计文件夹结构

skill-name/
├── SKILL.md          # Required
├── scripts/          # Optional - executable code
├── references/       # Optional - additional documentation
└── assets/           # Optional - templates, resources

Critical rules:

The file MUST be named exactly
```
SKILL.md
```
(case-sensitive). No variations (SKILL.MD, skill.md, etc.)
The folder uses kebab-case:
```
my-cool-skill
```
✅ |
```
My Skill
```
❌ |
```
my_skill
```
❌
Do NOT include
```
README.md
```
inside the skill folder. All documentation goes in SKILL.md or
```
references/
```
Do NOT use reserved platform names in the skill name

skill-name/
├── SKILL.md          # 必填
├── scripts/          # 可选 - 可执行代码
├── references/       # 可选 - 额外文档
└── assets/           # 可选 - 模板、资源

关键规则：

文件名必须严格为
```
SKILL.md
```
（大小写敏感）。不允许任何变体（如SKILL.MD、skill.md等）
文件夹名称使用kebab-case格式：
```
my-cool-skill
```
✅ |
```
My Skill
```
❌ |
```
my_skill
```
❌
请勿在Skill文件夹内包含
```
README.md
```
。所有文档应放入SKILL.md或
```
references/
```
中
请勿在Skill名称中使用平台保留名称

Step 3: Write the YAML frontmatter

步骤3：编写YAML前置元数据

The frontmatter is how the agent decides whether to load your skill. This is the most important part.

yaml

---
name: name-in-kebab-case
description: What the skill does and when to use it. Include specific trigger phrases.
---

name
field (required):

Kebab-case only, no spaces or capitals
Should match the folder name

description
field (required, max 1024 characters):

MUST include WHAT it does + WHEN to use it
Include specific phrases users would actually say
Mention file types if applicable
No XML tags (< >)
Lean slightly "pushy" — agents tend to under-trigger, so a description that's assertive about when to activate performs better than one that's conservative

Good description examples:

yaml

undefined

前置元数据是Agent决定是否加载你的Skill的依据，这是最重要的部分。

yaml

---
name: name-in-kebab-case
description: 该Skill的功能及适用场景。需包含具体触发短语。
---

name
字段（必填）：

仅允许kebab-case格式，无空格或大写字母
应与文件夹名称一致

description
字段（必填，最多1024字符）：

必须包含功能+适用场景
需包含用户实际会使用的具体短语
若适用，提及文件类型
不得包含XML标签(< >)
可适当“主动”一些——Agent往往会触发不足，因此明确说明激活场景的描述，比保守的描述效果更好

优秀描述示例：

yaml

undefined

Good - specific and actionable

优秀 - 具体且可执行

description: Analyzes Figma design files and generates developer handoff documentation. Use when the user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".

description: 分析Figma设计文件并生成开发者交付文档。当用户上传.fig文件、询问“设计规范”“组件文档”或“设计转代码交付”时使用。

Good - includes trigger phrases

优秀 - 包含触发短语

description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when the user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets".

description: 管理Linear项目工作流，包括 sprint规划、任务创建和状态跟踪。当用户提及“sprint”“Linear tasks”“项目规划”，或要求“创建工单”时使用。

Good - clear value proposition with negative trigger

优秀 - 清晰的价值主张及排除触发场景

description: Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration (use data-viz skill instead).


Bad description examples:

```yaml

description: 针对CSV文件的高级数据分析。用于统计建模、回归分析、聚类分析。请勿用于简单数据探索（请使用data-viz skill）。


糟糕描述示例：

```yaml

Too vague

过于模糊

description: Helps with projects.

description: 辅助项目工作。

Missing triggers

缺少触发条件

description: Creates sophisticated multi-page documentation systems.

description: 创建复杂的多页面文档系统。

Too technical, no user triggers

过于技术化，无用户触发短语

description: Implements the Project entity model with hierarchical relationships.


**Optional fields:**
- `license`: MIT, Apache-2.0, etc.
- `compatibility`: environment requirements, intended platforms, required system packages (1-500 chars)
- `allowed-tools`: restrict which tools the skill can invoke
- `metadata`: custom key-value pairs

```yaml
metadata:
  author: Your Name
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]

Security restrictions:

No XML angle brackets (< >) in frontmatter — frontmatter appears in the agent's system prompt and could inject instructions
No code execution in YAML (safe YAML parsing is used)

description: 实现带有层级关系的Project实体模型。


**可选字段：**
- `license`：MIT、Apache-2.0等
- `compatibility`：环境要求、目标平台、所需系统包（1-500字符）
- `allowed-tools`：限制Skill可调用的工具
- `metadata`：自定义键值对

```yaml
metadata:
  author: 你的姓名
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]

安全限制：

前置元数据中不得包含XML尖括号(< >)——前置元数据会出现在Agent的系统提示中，可能注入恶意指令
YAML中不得包含可执行代码（使用安全YAML解析）

Step 4: Write the instructions

步骤4：编写说明内容

After the frontmatter, write the instructions in Markdown. Recommended structure:

markdown

---
name: my-skill
description: [...]
---

前置元数据之后，使用Markdown编写说明内容。推荐结构：

markdown

---
name: my-skill
description: [...]
---

Skill Name

Skill名称

Instructions

操作说明

Step 1: [First step]

步骤1：[第一步]

Clear explanation of what happens.

Example: ```bash node scripts/fetch_data.js --project-id PROJECT_ID ``` Expected output: [describe what success looks like]

清晰解释操作内容。

示例： ```bash node scripts/fetch_data.js --project-id PROJECT_ID ``` 预期输出：[描述成功状态]

Step 2: [Next step]

步骤2：[下一步]

...

Examples

示例

Example 1: [common scenario] User says: "..." Actions: ... Result: ...

示例1：[常见场景] 用户输入："..." 操作：... 结果：...

Troubleshooting

故障排除

Error: [common message] Cause: [why it happens] Solution: [how to fix]

undefined

错误：[常见提示] 原因：[故障原因] 解决方案：[修复方法]

undefined

Best practices for instructions

说明内容最佳实践

Be specific and actionable:

markdown

undefined

具体且可执行：

markdown

undefined

✅ Good

✅ 优秀

Run

bun run scripts/validate.ts --input {filename}

to check data format. If validation fails, common issues include:

Missing required fields (add them to the CSV)
Invalid date formats (use YYYY-MM-DD)

运行

bun run scripts/validate.ts --input {filename}

检查数据格式。若验证失败，常见问题包括：

缺少必填字段（添加至CSV）
日期格式无效（使用YYYY-MM-DD）

❌ Bad

❌ 糟糕

Validate the data before proceeding.


**Include error handling** with concrete resolution steps. For MCP-dependent skills, include connection verification, authentication checks, and fallback instructions.

**Use progressive disclosure:** keep SKILL.md focused on core instructions (ideally <500 lines). Move detailed documentation to `references/` and link to it. For large reference files (>300 lines), include a table of contents.

**Explain the why:** instead of rigid MUSTs, explain the reasoning behind each instruction. Current LLMs are smart and respond better to understanding rationale than to authoritarian commands. If you find yourself writing ALWAYS or NEVER in all caps, reframe and explain the reasoning so the model understands why.

**Use imperative form:** "Run the script" instead of "The script should be run".

**Define output formats explicitly:**
```markdown

在继续前验证数据。


**包含错误处理**及具体解决步骤。对于依赖MCP的Skill，需包含连接验证、身份验证检查和 fallback 说明。

**使用渐进式披露：** 保持SKILL.md聚焦核心说明（理想情况下少于500行）。将详细文档移至`references/`并添加链接。对于大型参考文件（>300行），需包含目录。

**解释原因：** 不要使用生硬的“必须”，而是解释每个操作的背后逻辑。当前LLMs具备智能，理解原理比服从强制命令的响应更好。如果你发现自己在使用全大写的ALWAYS或NEVER，请重新组织语言并解释原因，让模型理解背后的逻辑。

**使用祈使语气：** “运行脚本”而非“应运行脚本”。

**明确定义输出格式：**
```markdown

Report structure

报告结构

ALWAYS use this exact template:

必须使用以下精确模板：

[Title]

[标题]

Executive summary

执行摘要

Key findings

关键发现

Recommendations

建议


**Include examples with input/output pairs:**
```markdown


**包含输入/输出配对示例：**
```markdown

Commit message format

提交信息格式

Example 1: Input: Added user authentication with JWT tokens Output: feat(auth): implement JWT-based authentication


**For critical validations, bundle scripts:** code is deterministic; language interpretation isn't. If a check can be automated, write a script in `scripts/` rather than relying on the agent to interpret instructions correctly every time.

示例1： 输入：添加基于JWT令牌的用户认证输出：feat(auth): implement JWT-based authentication


**对于关键验证，打包为脚本：** 代码是确定性的；语言解释则不是。如果某项检查可自动化，应在`scripts/`中编写脚本，而非依赖Agent每次都正确理解说明。

Step 5: Testing

步骤5：测试

Three testing areas:

1. Triggering tests — does the skill load at the right times?

✅ Triggers on obvious tasks
✅ Triggers on paraphrased requests
❌ Does NOT trigger on unrelated topics

Quick debugging: ask the agent "When would you use the [skill name] skill?" — it will quote the description back and you can adjust based on what's missing.

2. Functional tests — does the skill produce correct outputs?

Valid outputs generated
API/MCP calls succeed
Error handling works
Edge cases covered

3. Performance comparison — does the skill improve results vs baseline?

Measure back-and-forth messages needed
Measure failed API calls requiring retry
Measure tokens consumed
Compare with-skill vs without-skill

Recommended approach: iterate on a single challenging task until the agent succeeds, then extract the winning approach into the skill. This provides faster signal than broad testing. Once you have a working foundation, expand to multiple test cases for coverage.

三个测试维度：

1. 触发测试 — Skill是否在正确时机加载？

✅ 在明显任务中触发
✅ 在改写后的请求中触发
❌ 不在无关主题中触发

快速调试方法：询问Agent“你会在何时使用[skill名称]技能？”——它会引用描述内容，你可据此调整缺失的信息。

2. 功能测试 — Skill是否能生成正确输出？

生成有效输出
API/MCP调用成功
错误处理生效
覆盖边缘场景

3. 性能对比 — 与基准相比，Skill是否提升了结果？

统计所需来回消息数
统计需要重试的API调用失败次数
统计令牌消耗
对比使用Skill与不使用Skill的差异

推荐方法：针对单个具有挑战性的任务迭代，直到Agent成功完成，然后将有效的方法提取为Skill。这比广泛测试能更快获得反馈信号。一旦有了可行的基础，再扩展到多个测试用例以覆盖更多场景。

Step 6: Iterate

步骤6：迭代优化

Under-triggering signals:

Skill doesn't load when it should
Users manually enabling it
Solution: add more keywords, trigger phrases, and nuance to the description

Over-triggering signals:

Skill loads for irrelevant queries
Users disabling it
Solution: add negative triggers, narrow the scope, be more specific

Execution issues:

Inconsistent results across sessions
API call failures
Users needing to correct the agent
Solution: improve instructions, add error handling, look for steps that should be scripted

触发不足信号：

Skill在应触发时未加载
用户手动启用Skill
解决方案：添加更多关键词、触发短语和场景细节到描述中

触发过度信号：

Skill在无关查询中加载
用户禁用Skill
解决方案：添加排除触发场景、缩小范围、更明确地定义适用场景

执行问题信号：

不同会话中结果不一致
API调用失败
用户需要纠正Agent的操作
解决方案：优化说明内容、添加错误处理、识别应脚本化的步骤

Common patterns

常见模式

Pattern 1: Sequential workflow orchestration

模式1：顺序工作流编排

For multi-step processes in a specific order. Explicit step ordering, dependencies between steps, validation at each stage, rollback instructions for failures.

markdown

undefined

适用于特定顺序的多步骤流程。明确步骤顺序、步骤间依赖关系、每个阶段的验证、失败时的回滚说明。

markdown

undefined

Step 1: Create Account

步骤1：创建账户

Call MCP tool:

create_customer

Parameters: name, email, company

调用MCP工具：

create_customer

参数：name, email, company

Step 2: Setup Payment

步骤2：设置支付方式

Call MCP tool:

setup_payment_method

Wait for: payment method verification

调用MCP工具：

setup_payment_method

等待：支付方式验证完成

Step 3: Create Subscription

步骤3：创建订阅

Call MCP tool:

create_subscription

Parameters: plan_id, customer_id (from Step 1)

undefined

调用MCP工具：

create_subscription

参数：plan_id, customer_id（来自步骤1）

undefined

Pattern 2: Multi-MCP coordination

模式2：多MCP协调

For workflows spanning multiple services (e.g., Figma → Drive → Linear → Slack). Clear phase separation, data passing between MCPs, validation before advancing, centralized error handling.

适用于跨多个服务的工作流（如Figma → Drive → Linear → Slack）。明确阶段划分、MCP间数据传递、推进前的验证、集中式错误处理。

Pattern 3: Iterative refinement

模式3：迭代优化

For when output quality improves with iteration. Initial draft → quality check via validation script → refinement loop → finalization. Include explicit quality criteria and know when to stop.

适用于通过迭代提升输出质量的场景。初稿→通过验证脚本进行质量检查→优化循环→最终定稿。包含明确的质量标准及停止迭代的条件。

Pattern 4: Context-aware tool selection

模式4：上下文感知工具选择

For when the same outcome is achieved with different tools depending on context. Clear decision tree (e.g., large files → cloud storage, collaborative docs → Notion, code → GitHub), fallback options, transparency about choices.

适用于根据上下文使用不同工具达成相同结果的场景。明确决策树（如大文件→云存储、协作文档→Notion、代码→GitHub）、备选方案、选择透明度。

Pattern 5: Domain-specific intelligence

模式5：领域特定智能

For when the skill adds specialized knowledge beyond tool access. Domain expertise embedded in logic, compliance/validation before action, comprehensive audit trail, clear governance rules.

适用于Skill在工具访问之外添加专业领域知识的场景。逻辑中嵌入领域专业知识、操作前的合规/验证、完整审计跟踪、明确的治理规则。

Distribution

分发

Individual installation:

Zip the skill folder
Upload via the platform's skill settings
Or place in the platform's skills directory

Organization deployment:

Platform admins can deploy skills workspace-wide
Enables automatic updates and centralized management

Public distribution:

Host on GitHub with a clear README at repo level (NOT inside the skill folder)
Include example usage and screenshots
If paired with an MCP server, document both together and explain the combined value
Provide a quick-start installation guide

Positioning tip: focus on outcomes, not features. "Set up complete project workspaces in seconds instead of 30 minutes of manual setup" beats "A folder containing YAML frontmatter and Markdown instructions."

个人安装：

压缩Skill文件夹
通过平台的Skill设置上传
或放置在平台的skills目录中

组织部署：

平台管理员可在工作区范围内部署Skill
支持自动更新和集中管理

公开发布：

托管在GitHub上，在仓库根目录添加清晰的README（请勿放在Skill文件夹内）
包含示例用法和截图
若与MCP服务器配对，需同时文档化两者并说明组合价值
提供快速入门安装指南

定位技巧： 聚焦结果而非功能。“几秒内完成完整项目工作区设置，替代30分钟的手动操作”比“包含YAML前置元数据和Markdown说明的文件夹”更有吸引力。

Final checklist

最终检查表

Before starting:

2-3 concrete use cases identified
Required tools identified (built-in, MCP, or API)
Folder structure planned

During development:

Folder named in kebab-case
```
SKILL.md
```
file exists (exact case-sensitive spelling)
YAML frontmatter has
```
---
```
delimiters
```
name
```
field: kebab-case, no spaces, no capitals
```
description
```
includes WHAT and WHEN
No XML tags (< >) in frontmatter
Instructions are clear and actionable
Error handling included
Examples provided
References clearly linked

Before upload:

Tested triggering on obvious tasks
Tested triggering on paraphrased requests
Verified doesn't trigger on unrelated topics
Functional tests pass
Tool/MCP integration works (if applicable)

After upload:

Tested in real conversations
Monitored for under/over-triggering
Collected user feedback
Iterated on description and instructions

开始前：

已确定2-3个具体用例
已确定所需工具（内置、MCP或API）
已规划文件夹结构

开发中：

文件夹名称使用kebab-case格式
存在
```
SKILL.md
```
文件（严格大小写敏感）
YAML前置元数据包含
```
---
```
分隔符
```
name
```
字段：kebab-case格式，无空格、无大写字母
```
description
```
包含功能及适用场景
前置元数据中无XML标签(< >)
说明内容清晰且可执行
包含错误处理
提供示例
参考文档链接清晰

上传前：

已测试在明显任务中的触发情况
已测试在改写请求中的触发情况
已验证不会在无关主题中触发
功能测试通过
工具/MCP集成正常（若适用）

上传后：

在真实对话中测试
监控触发不足/过度情况
收集用户反馈
优化描述和说明内容