skill-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Creator

Skill 创建器

This skill provides guidance for creating effective skills using the existing tool system.

本Skill为使用现有工具系统创建高效Skill提供指导。

About Skills

关于Skill

Skills are modular, self-contained packages that extend the agent's capabilities by providing specialized knowledge, workflows, and tools. They transform a general-purpose agent into a specialized agent equipped with procedural knowledge.

Skill是模块化、独立的包，通过提供专业知识、工作流和工具来扩展Agent的能力。它们能将通用Agent转变为具备流程知识的专业Agent。

What Skills Provide

Skill提供的内容

Specialized workflows - Multi-step procedures for specific domains
Tool integrations - Instructions for working with specific file formats or APIs
Domain expertise - Company-specific knowledge, schemas, business logic
Bundled resources - Scripts, references, and assets for complex tasks

专业工作流 - 特定领域的多步骤流程
工具集成 - 处理特定文件格式或API的说明
领域专业知识 - 公司专属知识、架构、业务逻辑
捆绑资源 - 用于复杂任务的脚本、参考资料和资产

Core Principle

核心原则

Concise is Key: Only add context the agent doesn't already have. Challenge each piece of information: "Does this justify its token cost?" Prefer concise examples over verbose explanations.

简洁至上：仅添加Agent尚不具备的上下文信息。对每条信息都要质疑：“它是否值得消耗对应的token成本？” 优先选择简洁示例而非冗长解释。

Skill Structure

Skill结构

Every skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

每个Skill都包含一个必填的SKILL.md文件和可选的捆绑资源：

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md Components

SKILL.md组件

Frontmatter (YAML) - Required fields:

name: Skill name in hyphen-case (e.g.,
```
weather-api
```
,
```
pdf-editor
```
)
description: CRITICAL - Primary triggering mechanism
- Must clearly describe what the skill does
- Must explicitly state when to use it
- Include specific trigger scenarios and keywords
- All "when to use" info goes here, NOT in body
- Example:
```
"PDF document processing with rotation, merging, splitting, and text extraction. Use when user needs to: (1) Rotate PDF pages, (2) Merge multiple PDFs, (3) Split PDF files, (4) Extract text from PDFs."
```

Body (Markdown) - Loaded after skill triggers:

Detailed usage instructions
How to call scripts and read references
Examples and best practices
Use imperative/infinitive form ("Use X to do Y")

Frontmatter（YAML格式） - 必填字段：

name：Skill名称采用连字符分隔格式（例如：
```
weather-api
```
、
```
pdf-editor
```
）
description：至关重要 - 主要触发机制
- 必须清晰描述Skill的功能
- 必须明确说明使用场景
- 包含特定触发场景和关键词
- 所有“何时使用”的信息都应放在此处，而非正文部分
- 示例：
```
"PDF文档处理，支持旋转、合并、拆分和文本提取。适用于用户需要：(1) 旋转PDF页面；(2) 合并多个PDF；(3) 拆分PDF文件；(4) 提取PDF文本的场景。"
```

正文（Markdown格式） - Skill触发后加载：

详细使用说明
如何调用脚本和读取参考资料
示例和最佳实践
使用祈使/不定式形式（“使用X来完成Y”）

Bundled Resources

捆绑资源

scripts/ - When to include:

Code is repeatedly rewritten
Deterministic execution needed (avoid LLM randomness)
Examples: PDF rotation, image processing
Must test scripts before including

references/ - When to include:

ONLY when documentation is too large for SKILL.md (>500 lines)
Database schemas, complex API specs that agent needs to reference
Agent reads these files into context as needed
NOT for: API reference docs, usage examples, tutorials (put in SKILL.md instead)
Rule of thumb: If it fits in SKILL.md, don't create a separate reference file

assets/ - When to include:

Files used in output (not loaded to context)
Templates, icons, boilerplate code
Copied or modified in final output

Important: Most skills don't need all three. Choose based on actual needs.

scripts/ - 何时包含：

代码需要重复编写时
需要确定性执行（避免LLM随机性）时
示例：PDF旋转、图像处理
包含前必须测试脚本

references/ - 何时包含：

仅当文档内容过长无法放入SKILL.md（超过500行）时
数据库架构、Agent需要参考的复杂API规范
Agent会根据需要将这些文件加载到上下文中
不适用于：API参考文档、使用示例、教程（应放入SKILL.md）
经验法则：如果内容能放入SKILL.md，就不要创建单独的参考文件

assets/ - 何时包含：

用于输出的文件（不加载到上下文）
模板、图标、样板代码
在最终输出中被复制或修改

重要提示：大多数Skill不需要全部三类资源，根据实际需求选择。

What NOT to Include

不应包含的内容

Do NOT create auxiliary documentation files:

README.md - Instructions belong in SKILL.md
INSTALLATION_GUIDE.md - Setup info belongs in SKILL.md
CHANGELOG.md - Not needed for local skills
API_REFERENCE.md - Put API docs directly in SKILL.md
USAGE_EXAMPLES.md - Put examples directly in SKILL.md
Any other documentation files - Everything goes in SKILL.md unless it's too large

Critical Rule: Only create files that the agent will actually execute (scripts) or that are too large for SKILL.md (references). Documentation, examples, and guides ALL belong in SKILL.md.

请勿创建辅助文档文件：

README.md - 说明应放在SKILL.md中
INSTALLATION_GUIDE.md - 设置信息应放在SKILL.md中
CHANGELOG.md - 本地Skill不需要
API_REFERENCE.md - 将API文档直接放入SKILL.md
USAGE_EXAMPLES.md - 将示例直接放入SKILL.md
任何其他文档文件 - 所有内容都应放入SKILL.md，除非内容过长

关键规则：仅创建Agent实际会执行的文件（脚本）或内容过长无法放入SKILL.md的文件（参考资料）。文档、示例和指南全部应放入SKILL.md。

Installing a Skill

安装Skill

Install target directory:

<workspace>/skills/<name>/

(the

<workspace>

is from the "工作空间" section).

安装目标目录：

<workspace>/skills/<name>/

（

<workspace>

来自“工作空间”部分）。

Step 1 — Obtain skill content

步骤1 — 获取Skill内容

Source	Action
URL (single file)	Fetch content via curl or web_fetch
URL (zip/archive)	Download and extract to a temp directory
Local file (SKILL.md)	Read directly
Local archive (zip)	Extract to a temp directory

来源	操作
URL（单个文件）	通过curl或web_fetch获取内容
URL（压缩包/归档文件）	下载并解压到临时目录
本地文件（SKILL.md）	直接读取
本地归档文件（zip）	解压到临时目录

Step 2 — Identify and install

步骤2 — 识别并安装

Locate the SKILL.md (may be at top level or inside a subdirectory)
Extract
```
name
```
from YAML frontmatter
Copy the entire skill directory (SKILL.md and all sibling files/folders such as
```
references/
```
,
```
scripts/
```
,
```
assets/
```
, etc.) into
```
<workspace>/skills/<name>/
```
If an install/setup file exists (e.g. INSTALL.md), follow its instructions — the final result must still end up in
```
<workspace>/skills/<name>/
```

找到SKILL.md（可能在顶层目录或子目录中）
从YAML前置元数据中提取
```
name
```
将整个Skill目录（SKILL.md和所有同级文件/文件夹，如
```
references/
```
、
```
scripts/
```
、
```
assets/
```
等）复制到
```
<workspace>/skills/<name>/
```
如果存在安装/设置文件（例如INSTALL.md），请遵循其说明 — 最终结果仍需放入
```
<workspace>/skills/<name>/
```

Skill Creation Process (from scratch)

Skill创建流程（从零开始）

Understand - Clarify use cases with concrete examples
Plan - Identify needed scripts, references, assets
Initialize - Run init_skill.py to create template
Edit - Implement SKILL.md and resources
Validate (optional) - Run quick_validate.py to check format
Iterate - Improve based on real usage

理解需求 - 通过具体示例明确使用场景
规划资源 - 确定所需的脚本、参考资料和资产
初始化 - 运行init_skill.py创建模板
编辑 - 实现SKILL.md和资源
验证（可选） - 运行quick_validate.py检查格式
迭代优化 - 根据实际使用情况改进

Skill Naming

Skill命名规则

Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., "Plan Mode" ->
```
plan-mode
```
).
When generating names, generate a name under 64 characters (letters, digits, hyphens).
Prefer short, verb-led phrases that describe the action.
Namespace by tool when it improves clarity or triggering (e.g.,
```
gh-address-comments
```
,
```
linear-address-issue
```
).
Name the skill folder exactly after the skill name.

仅使用小写字母、数字和连字符；将用户提供的标题标准化为连字符分隔格式（例如："Plan Mode" ->
```
plan-mode
```
）。
生成名称时，长度需在64字符以内（字母、数字、连字符）。
优先选择简短、以动词开头的短语来描述功能。
当有助于提高清晰度或触发准确性时，按工具命名空间划分（例如：
```
gh-address-comments
```
、
```
linear-address-issue
```
）。
Skill文件夹名称必须与Skill名称完全一致。

Step-by-Step Guide

分步指南

Step 1: Understanding the Skill with Concrete Examples

步骤1：通过具体示例理解Skill

Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.

To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.

For example, when building an image-editor skill, relevant questions include:

"What functionality should the image-editor skill support? Editing, rotating, anything else?"
"Can you give some examples of how this skill would be used?"
"I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
"What would a user say that should trigger this skill?"

To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.

Conclude this step when there is a clear sense of the functionality the skill should support.

仅当Skill的使用模式已明确时才可跳过此步骤。即使处理现有Skill，此步骤仍有价值。

要创建有效的Skill，需清晰理解Skill的具体使用示例。这种理解可来自直接的用户示例，或经用户反馈验证的生成示例。

例如，构建image-editor Skill时，相关问题包括：

"image-editor Skill应支持哪些功能？编辑、旋转，还是其他？"
"能否给出一些此Skill的使用示例？"
"我能想象用户会提出诸如‘去除这张图片的红眼’或‘旋转这张图片’的请求。你认为还有其他使用场景吗？"
"用户说什么话应该触发此Skill？"

为避免使用户感到负担，请勿在一条消息中提出过多问题。从最重要的问题开始，根据需要跟进以提高效率。

当明确Skill应支持的功能时，即可结束此步骤。

Step 2: Planning the Reusable Skill Contents

步骤2：规划可复用的Skill内容

To turn concrete examples into an effective skill, analyze each example by:

Considering how to execute on the example from scratch
Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly

Planning Checklist:

✅ Always needed: SKILL.md with clear description and usage instructions
✅ scripts/: Only if code needs to be executed (not just shown as examples)
❌ references/: Rarely needed - only if documentation is >500 lines and can't fit in SKILL.md
✅ assets/: Only if files are used in output (templates, boilerplate, etc.)

Example: When building a

pdf-editor

skill to handle queries like "Help me rotate this PDF," the analysis shows:

Rotating a PDF requires re-writing the same code each time
A
```
scripts/rotate_pdf.py
```
script would be helpful to store in the skill
❌ Don't create
```
references/api-docs.md
```
- put API info in SKILL.md instead

Example: When designing a

frontend-webapp-builder

skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:

Writing a frontend webapp requires the same boilerplate HTML/React each time
An
```
assets/hello-world/
```
template containing the boilerplate HTML/React project files would be helpful to store in the skill
❌ Don't create
```
references/usage-examples.md
```
- put examples in SKILL.md instead

Example: When building a

big-query

skill to handle queries like "How many users have logged in today?" the analysis shows:

Querying BigQuery requires re-discovering the table schemas and relationships each time
A
```
references/schema.md
```
file documenting the table schemas would be helpful to store in the skill (ONLY because schemas are very large)
❌ Don't create separate
```
references/query-examples.md
```
- put examples in SKILL.md instead

To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets. Default to putting everything in SKILL.md unless there's a compelling reason to separate it.

要将具体示例转化为有效的Skill，需对每个示例进行分析：

考虑如何从头开始执行示例中的任务
确定重复执行这些工作流时需要哪些脚本、参考资料和资产

规划检查清单：

✅ 必备：包含清晰描述和使用说明的SKILL.md
✅ scripts/：仅当需要执行代码时（而非仅作为示例展示）
❌ references/：很少需要 - 仅当文档超过500行且无法放入SKILL.md时
✅ assets/：仅当文件用于输出时（模板、样板代码等）

示例：构建用于处理“帮我旋转这个PDF”等请求的

pdf-editor

Skill时，分析结果如下：

旋转PDF需要重复编写相同的代码
在Skill中存储
```
scripts/rotate_pdf.py
```
脚本会很有帮助
❌ 不要创建
```
references/api-docs.md
```
- 应将API信息放入SKILL.md

示例：设计用于处理“帮我构建一个待办事项应用”或“帮我构建一个步数跟踪仪表盘”等请求的

frontend-webapp-builder

Skill时，分析结果如下：

构建前端Web应用需要重复编写相同的HTML/React样板代码
在Skill中存储包含样板HTML/React项目文件的
```
assets/hello-world/
```
模板会很有帮助
❌ 不要创建
```
references/usage-examples.md
```
- 应将示例放入SKILL.md

示例：构建用于处理“今天有多少用户登录？”等请求的

big-query

Skill时，分析结果如下：

查询BigQuery需要反复查找表架构和关系
在Skill中存储记录表架构的
```
references/schema.md
```
文件会很有帮助（仅因为架构内容非常庞大）
❌ 不要创建单独的
```
references/query-examples.md
```
- 应将示例放入SKILL.md

要确定Skill的内容，需分析每个具体示例，创建要包含的可复用资源列表：脚本、参考资料和资产。默认将所有内容放入SKILL.md，除非有充分理由拆分。

Step 3: Initialize the Skill

步骤3：初始化Skill

At this point, it is time to actually create the skill.

Skip this step only if the skill being developed already exists, and iteration is needed. In this case, continue to the next step.

When creating a new skill from scratch, always run the

init_skill.py

script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.

Usage:

bash

scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]

Examples:

bash

scripts/init_skill.py my-skill --path <workspace>/skills
scripts/init_skill.py my-skill --path <workspace>/skills --resources scripts,references
scripts/init_skill.py my-skill --path <workspace>/skills --resources scripts --examples

Where

<workspace>

is your workspace directory shown in the "工作空间" section of the system prompt.

The script:

Creates the skill directory at the specified path
Generates a SKILL.md template with proper frontmatter and TODO placeholders
Optionally creates resource directories based on
```
--resources
```
Optionally adds example files when
```
--examples
```
is set

After initialization, customize the SKILL.md and add resources as needed. If you used

--examples

, replace or delete placeholder files.

Important: Always create skills in workspace skills directory (

<workspace>/skills

), NOT in project directory. Check the "工作空间" section for the actual workspace path.

此时可以开始实际创建Skill了。

仅当正在开发的Skill已存在且需要迭代时才可跳过此步骤。这种情况下，直接进入下一步。

从零开始创建新Skill时，务必运行

init_skill.py

脚本。该脚本会方便地生成一个新的模板Skill目录，自动包含Skill所需的所有内容，使Skill创建过程更高效、可靠。

用法：

bash

scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]

示例：

bash

scripts/init_skill.py my-skill --path <workspace>/skills
scripts/init_skill.py my-skill --path <workspace>/skills --resources scripts,references
scripts/init_skill.py my-skill --path <workspace>/skills --resources scripts --examples

其中

<workspace>

是系统提示中“工作空间”部分显示的工作区目录。

该脚本：

在指定路径创建Skill目录
生成带有正确前置元数据和待办事项占位符的SKILL.md模板
根据
```
--resources
```
参数可选创建资源目录
设置
```
--examples
```
参数时可选添加示例文件

初始化后，自定义SKILL.md并添加所需资源。如果使用了

--examples

，请替换或删除占位符文件。

重要提示：务必在工作区skills目录（

<workspace>/skills

）中创建Skill，而非项目目录。请查看“工作空间”部分获取实际工作区路径。

Step 4: Edit the Skill

步骤4：编辑Skill

When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of the agent to use. Include information that would be beneficial and non-obvious to the agent. Consider what procedural knowledge, domain-specific details, or reusable assets would help another agent instance execute these tasks more effectively.

编辑（新生成或现有）Skill时，请记住该Skill是为另一个Agent实例创建的。包含对Agent有益且非显而易见的信息。考虑哪些流程知识、领域特定细节或可复用资产能帮助另一个Agent实例更有效地执行这些任务。

Design Patterns

设计模式

Workflow patterns — For complex tasks, break operations into sequential steps or conditional branches:

markdown

undefined

工作流模式 — 对于复杂任务，将操作拆分为连续步骤或条件分支：

markdown

undefined

Sequential: list numbered steps with scripts

顺序执行：列出带脚本的编号步骤

Analyze the form (run analyze_form.py)
Create field mapping (edit fields.json)
Fill the form (run fill_form.py)

分析表单（运行analyze_form.py）
创建字段映射（编辑fields.json）
填写表单（运行fill_form.py）

Conditional: guide through decision points

条件分支：引导完成决策点

Determine the modification type: Creating new content? → Follow "Creation workflow" Editing existing content? → Follow "Editing workflow"


**Output patterns** — When consistent output format matters, provide a template or input/output examples in SKILL.md so the agent can follow the desired style.

确定修改类型： 创建新内容？ → 遵循“创建工作流” 编辑现有内容？ → 遵循“编辑工作流”


**输出模式** — 当需要一致的输出格式时，在SKILL.md中提供模板或输入/输出示例，以便Agent遵循所需风格。

Start with Reusable Skill Contents

从可复用Skill内容开始

To begin implementation, start with the reusable resources identified above:

scripts/

references/

, and

assets/

files. Note that this step may require user input. For example, when implementing a

brand-guidelines

skill, the user may need to provide brand assets or templates to store in

assets/

, or documentation to store in

references/

Available Base Tools:

The agent has access to these core tools that you can leverage in your skill:

bash: Execute shell commands (use for curl, ls, grep, sed, awk, bc for calculations, etc.)
read: Read file contents
write: Write files
edit: Edit files with search/replace

Minimize Dependencies:

✅ Prefer bash + curl for HTTP API calls (no Python dependencies)
✅ Use bash tools (grep, sed, awk) for text processing
✅ Keep scripts simple - if bash can do it, no need for Python (document packages/versions if Python is used)

Important Guidelines:

scripts/: Only create scripts that will be executed. Test all scripts before including.
references/: ONLY create if documentation is too large for SKILL.md (>500 lines). Most skills don't need this.
assets/: Only include files used in output (templates, icons, etc.)
Default approach: Put everything in SKILL.md unless there's a specific reason not to.

Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.

If you used

--examples

, delete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.

开始实现时，先处理上述确定的可复用资源：

scripts/

、

references/

和

assets/

文件。请注意，此步骤可能需要用户输入。例如，实现

brand-guidelines

Skill时，用户可能需要提供品牌资产或模板存储在

assets/

中，或提供文档存储在

references/

中。

可用基础工具：

Agent可访问以下核心工具，你可在Skill中利用它们：

bash：执行shell命令（用于curl、ls、grep、sed、awk、bc计算等）
read：读取文件内容
write：写入文件
edit：通过搜索/替换编辑文件

最小化依赖：

✅ 优先使用bash + curl进行HTTP API调用（无Python依赖）
✅ 使用bash工具（grep、sed、awk）进行文本处理
✅ 保持脚本简单 - 如果bash能完成，无需使用Python（若使用Python，请记录所需包/版本）

重要指南：

scripts/：仅创建会被执行的脚本。包含前务必测试所有脚本。
references/：仅当文档过长无法放入SKILL.md（超过500行）时才创建。大多数Skill不需要此目录。
assets/：仅包含用于输出的文件（模板、图标等）
默认方法：将所有内容放入SKILL.md，除非有特定理由不这样做。

添加的脚本必须实际运行测试，确保无bug且输出符合预期。如果有许多相似脚本，只需测试代表性样本，确保它们都能正常工作，同时平衡完成时间。

如果使用了

--examples

，删除Skill不需要的任何占位符文件。仅创建实际需要的资源目录。

Update SKILL.md

更新SKILL.md

Writing Guidelines: Always use imperative/infinitive form.

编写指南：始终使用祈使/不定式形式。

Frontmatter

前置元数据

Write the YAML frontmatter with

name

description

, and optional

metadata

```
name
```
: The skill name
```
description
```
: This is the primary triggering mechanism for your skill, and helps the agent understand when to use the skill.
- Include both what the Skill does and specific triggers/contexts for when to use it.
- Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to the agent.
- Example description for a
```
docx
```
  skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when the agent needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
```
metadata
```
: (Optional) Specify requirements and configuration
- ```
requires.bins
```
  : Required binaries (e.g.,
```
["curl", "jq"]
```
  )
- ```
requires.env
```
  : Required environment variables — all must be set (e.g.,
```
["MYAPI_KEY"]
```
  )
- ```
requires.anyEnv
```
  : Alternative environment variables — at least one must be set (e.g.,
```
["OPENAI_API_KEY", "LINKAI_API_KEY"]
```
  )
- ```
requires.anyBins
```
  : Alternative binaries — at least one must be present
- ```
always
```
  : Set to
```
true
```
  to always load regardless of requirements
- ```
emoji
```
  : Skill icon (optional)
- Do NOT set
```
category
```
  — it defaults to
```
skill
```
  and is managed by the system

API Key Requirements:

If your skill needs a single API key, declare it in

requires.env

yaml

---
name: my-search
description: Search using MyAPI
metadata:
  requires:
    bins: ["curl"]
    env: ["MYAPI_KEY"]
---

If your skill supports multiple API key providers (e.g., OpenAI or LinkAI), use

requires.anyEnv

yaml

---
name: my-vision
description: Analyze images using Vision API
metadata:
  requires:
    bins: ["curl"]
    anyEnv: ["OPENAI_API_KEY", "LINKAI_API_KEY"]
---

Auto-enable rule: Skills are automatically enabled when required environment variables are set, and automatically disabled when missing. No manual configuration needed.

编写包含

name

、

description

和可选

metadata

的YAML前置元数据：

```
name
```
：Skill名称
```
description
```
：这是Skill的主要触发机制，帮助Agent理解何时使用该Skill。
- 同时包含Skill的功能和使用的特定触发/上下文。
- 所有“何时使用”的信息都应放在此处 - 而非正文。正文仅在触发后加载，因此正文中的“何时使用此Skill”部分对Agent毫无帮助。
- ```
docx
```
  Skill的示例描述：“全面的文档创建、编辑和分析，支持修订跟踪、批注、格式保留和文本提取。适用于Agent需要处理专业文档（.docx文件）的场景：(1) 创建新文档；(2) 修改或编辑内容；(3) 处理修订跟踪；(4) 添加批注，或任何其他文档任务”
```
metadata
```
：（可选）指定要求和配置
- ```
requires.bins
```
  ：所需二进制文件（例如：
```
["curl", "jq"]
```
  ）
- ```
requires.env
```
  ：所需环境变量 — 必须全部设置（例如：
```
["MYAPI_KEY"]
```
  ）
- ```
requires.anyEnv
```
  ：可选环境变量 — 至少设置一个（例如：
```
["OPENAI_API_KEY", "LINKAI_API_KEY"]
```
  ）
- ```
requires.anyBins
```
  ：可选二进制文件 — 至少存在一个
- ```
always
```
  ：设置为
```
true
```
  时，无论要求是否满足都始终加载
- ```
emoji
```
  ：Skill图标（可选）
- 请勿设置
```
category
```
  — 默认值为
```
skill
```
  ，由系统管理

API密钥要求：

如果Skill需要单个API密钥，在

requires.env

中声明：

yaml

---
name: my-search
description: Search using MyAPI
metadata:
  requires:
    bins: ["curl"]
    env: ["MYAPI_KEY"]
---

如果Skill支持多个API密钥提供商（例如OpenAI或LinkAI），使用

requires.anyEnv

：

yaml

---
name: my-vision
description: Analyze images using Vision API
metadata:
  requires:
    bins: ["curl"]
    anyEnv: ["OPENAI_API_KEY", "LINKAI_API_KEY"]
---

自动启用规则：当所需环境变量设置完成后，Skill会自动启用；当环境变量缺失时，Skill会自动禁用。无需手动配置。

Body

正文

Write instructions for using the skill and its bundled resources.

If your skill requires an API key, include setup instructions in the body:

markdown

undefined

编写使用Skill及其捆绑资源的说明。

如果Skill需要API密钥，在正文中包含设置说明：

markdown

undefined

Setup

设置

This skill requires an API key from [Service Name].

Visit https://service.com to get an API key

Configure it using:

env_config(action="set", key="SERVICE_API_KEY", value="your-key")

Or manually add to
```
~/cow/.env
```
:
```
SERVICE_API_KEY=your-key
```
Restart the agent for changes to take effect

本Skill需要[服务名称]提供的API密钥。

访问https://service.com获取API密钥

使用以下命令配置：

env_config(action="set", key="SERVICE_API_KEY", value="your-key")

或手动添加到
```
~/cow/.env
```
：
```
SERVICE_API_KEY=your-key
```
重启Agent使更改生效

Usage

使用方法

...


The bash script should check for the key and provide helpful error messages:

```bash
#!/usr/bin/env bash
if [ -z "${SERVICE_API_KEY:-}" ]; then
    echo "Error: SERVICE_API_KEY not set"
    echo "Please configure your API key first (see SKILL.md)"
    exit 1
fi

curl -H "Authorization: Bearer $SERVICE_API_KEY" ...

Script Path Convention:

When writing SKILL.md instructions, remember that:

Skills are listed in
```
<available_skills>
```
with a
```
<base_dir>
```
path
Scripts should be referenced as:
```
<base_dir>/scripts/script_name.sh
```
The AI will see the base_dir and can construct the full path

Example instruction in SKILL.md:

markdown

undefined

...


bash脚本应检查密钥并提供有用的错误消息：

```bash
#!/usr/bin/env bash
if [ -z "${SERVICE_API_KEY:-}" ]; then
    echo "Error: SERVICE_API_KEY not set"
    echo "Please configure your API key first (see SKILL.md)"
    exit 1
fi

curl -H "Authorization: Bearer $SERVICE_API_KEY" ...

脚本路径约定：

编写SKILL.md说明时，请记住：

Skill在
```
<available_skills>
```
中列出，带有
```
<base_dir>
```
路径
脚本应引用为：
```
<base_dir>/scripts/script_name.sh
```
AI会看到base_dir并能构造完整路径

SKILL.md中的示例说明：

markdown

undefined

Usage

使用方法

Scripts are in this skill's base directory (shown in skill listing).

bash "<base_dir>/scripts/my_script.sh" <args>

undefined

脚本位于此Skill的基础目录中（在Skill列表中显示）。

bash "<base_dir>/scripts/my_script.sh" <args>

undefined

Step 5: Validate (Optional)

步骤5：验证（可选）

Validate skill format:

bash

scripts/quick_validate.py <path/to/skill-folder>

Example:

bash

scripts/quick_validate.py <workspace>/skills/weather-api

Validation checks:

YAML frontmatter format and required fields
Skill naming conventions (hyphen-case, lowercase)
Description completeness and quality
File organization

Note: Validation is optional in COW. Mainly useful for troubleshooting format issues.

验证Skill格式：

bash

scripts/quick_validate.py <path/to/skill-folder>

示例：

bash

scripts/quick_validate.py <workspace>/skills/weather-api

验证检查项：

YAML前置元数据格式和必填字段
Skill命名规范（连字符分隔格式、小写）
描述的完整性和质量
文件组织

注意：在COW中验证是可选的。主要用于排查格式问题。

Step 6: Iterate

步骤6：迭代优化

Improve based on real usage:

Use skill on real tasks
Notice struggles or inefficiencies
Identify needed updates to SKILL.md or resources
Implement changes and test again

根据实际使用情况改进：

在实际任务中使用Skill
注意遇到的困难或低效之处
确定需要更新SKILL.md或资源的地方
实施更改并再次测试

Progressive Disclosure

渐进式披露

Skills use three-level loading:

Metadata (name + description) - Always in context (~100 words)
SKILL.md body - Loaded when skill triggers (<5k words)
Resources - Loaded as needed by agent

Best practices:

Keep SKILL.md under 500 lines
Split complex content into
```
references/
```
files
Reference these files clearly in SKILL.md

Pattern: For skills with multiple variants/frameworks:

Keep core workflow in SKILL.md
Move variant-specific details to separate reference files
Agent loads only relevant files

Example:

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

When user chooses AWS, agent only reads aws.md.

Skill采用三级加载机制：

元数据（名称+描述）- 始终在上下文中（约100词）
SKILL.md正文 - Skill触发时加载（少于5000词）
资源 - Agent根据需要加载

最佳实践：

保持SKILL.md在500行以内
将复杂内容拆分为
```
references/
```
文件
在SKILL.md中清晰引用这些文件

模式：对于包含多个变体/框架的Skill：

将核心工作流保留在SKILL.md中
将变体特定细节移至单独的参考文件
Agent仅加载相关文件

示例：

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

当用户选择AWS时，Agent仅读取aws.md。