skill-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Creator

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 from URL

从URL安装Skill

Fetch the URL content (curl or web-fetch skill)
Extract
```
name
```
from YAML frontmatter
Create directory
```
<workspace>/skills/<name>/
```
and save content as
```
SKILL.md
```
Check the saved SKILL.md for an installation/setup section — if it defines additional steps (e.g., downloading scripts, installing dependencies), execute them; otherwise installation is complete

The

<workspace>

is the working directory from the "工作空间" section.

获取URL内容（使用curl或web-fetch skill）
从YAML frontmatter中提取
```
name
```
字段
创建目录
```
<workspace>/skills/<name>/
```
并将内容保存为
```
SKILL.md
```
检查保存的SKILL.md是否包含安装/设置部分——如果定义了额外步骤（例如下载脚本、安装依赖），执行这些步骤；否则安装完成

<workspace>

是“工作空间”部分指定的工作目录。

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创建过程更高效、可靠。

使用方法：

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目录
生成带有正确frontmatter和待办占位符的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实例更高效地执行这些任务。

Learn Proven Design Patterns

学习经过验证的设计模式

Consult these helpful guides based on your skill's needs:

Multi-step processes: See references/workflows.md for sequential workflows and conditional logic
Specific output formats or quality standards: See references/output-patterns.md for template and example patterns

These files contain established best practices for effective skill design.

根据Skill的需求，参考以下实用指南：

多步骤流程：查看references/workflows.md了解顺序工作流和条件逻辑
特定输出格式或质量标准：查看references/output-patterns.md了解模板和示例模式

这些文件包含了高效Skill设计的成熟最佳实践。

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

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 (e.g.,
```
["OPENAI_API_KEY"]
```
  )
- ```
primaryEnv
```
  : Primary environment variable name (for API keys)
- ```
always
```
  : Set to
```
true
```
  to always load regardless of requirements
- ```
emoji
```
  : Skill icon (optional)

API Key Requirements:

If your skill needs an API key, declare it in metadata:

yaml

---
name: my-search
description: Search using MyAPI
metadata:
  requires:
    bins: ["curl"]
    env: ["MYAPI_KEY"]
  primaryEnv: "MYAPI_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 frontmatter：

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

API密钥需求：

如果Skill需要API密钥，请在metadata中声明：

yaml

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

自动启用规则：当所需环境变量已设置时，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需要从[Service Name]获取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 frontmatter格式和必填字段
Skill命名规范（连字符分隔、小写）
Description的完整性和质量
文件组织结构

注意：在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。