skill-creator

技能创建器

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

关于技能

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

技能提供的内容

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

核心原则

简洁是关键：只添加 Agent 尚未掌握的上下文。对每一条信息都要质疑："它是否值得消耗这些 token？"优先使用简洁的示例，而非冗长的解释。

技能结构

每个技能都包含一个必需的 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 组件

Frontmatter（YAML） - 必需字段：

• name：技能名称，使用连字符格式（例如 weather-api、pdf-editor）
• description：至关重要 - 主要触发机制
  • 必须清楚描述该技能的作用
  • 必须明确说明何时使用它
  • 包含具体的触发场景和关键词
  • 所有"何时使用"的信息都放在这里，而不是正文中
  • 示例："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."

正文（Markdown） - 技能触发后加载：

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

捆绑资源

scripts/ - 何时包含：

• 代码被反复重写
• 需要确定性执行（避免大模型的随机性）
• 示例：PDF 旋转、图像处理
• 包含前必须测试脚本

references/ - 何时包含：

• 仅当文档过大、无法放入 SKILL.md 时（>500 行）
• 数据库 schema、Agent 需要参考的复杂 API 规范
• Agent 会按需将这些文件读入上下文
• 不适用于：API 参考文档、使用示例、教程（应改为放入 SKILL.md）
• 经验法则：如果能放进 SKILL.md，就不要单独创建参考文件

assets/ - 何时包含：

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

重要：大多数技能并不需要这三者全部。根据实际需求选择。

不应包含的内容

不要创建辅助文档文件：

• README.md - 说明应放在 SKILL.md 中
• INSTALLATION_GUIDE.md - 安装信息应放在 SKILL.md 中
• CHANGELOG.md - 本地技能不需要
• API_REFERENCE.md - 将 API 文档直接放在 SKILL.md 中
• USAGE_EXAMPLES.md - 将示例直接放在 SKILL.md 中
• 任何其他文档文件 - 除非过大，否则一切都放在 SKILL.md 中

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

安装技能

安装目标目录：<workspace>/skills/<name>/（<workspace> 来自"Workspace"部分）。

第 1 步 — 获取技能内容

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

第 2 步 — 识别并安装

1. 找到 SKILL.md（可能位于顶层，也可能位于某个子目录中）
2. 从 YAML frontmatter 中提取 name
3. 将整个 skill 目录（SKILL.md 以及所有同级文件/文件夹，例如 references/、scripts/、assets/ 等）复制到 <workspace>/skills/<name>/
4. 如果存在安装/设置文件（例如 INSTALL.md），请遵循其中的说明 —— 最终结果仍必须位于 <workspace>/skills/<name>/

Skill 创建流程（从零开始）

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

Skill 命名

• 仅使用小写字母、数字和连字符；将用户提供的标题规范化为连字符格式（例如 "Plan Mode" -> plan-mode）。
• 生成名称时，生成的名称应少于 64 个字符（字母、数字、连字符）。
• 优先使用描述动作的简短动词开头短语。
• 当有助于提升清晰度或触发效果时，按工具添加命名空间（例如 gh-address-comments、linear-address-issue）。
• skill 文件夹的名称应与 skill 名称完全一致。

分步指南

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

仅当 skill 的使用模式已经清晰明了时，才可跳过此步骤。即使是在处理现有 skill 时，这一步仍然很有价值。

要创建有效的 skill，需要清楚地理解 skill 将如何被使用的具体示例。这种理解可以来自用户的直接示例，也可以来自生成并经用户反馈验证的示例。

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

• "image-editor skill 应支持哪些功能？编辑、旋转，还是其他功能？"
• "你能给出一些这个 skill 将如何被使用的示例吗？"
• "我可以想象用户会提出类似 'Remove the red-eye from this image' 或 'Rotate this image' 的需求。你还能想到这个 skill 的其他使用方式吗？"
• "用户会说什么话来触发这个 skill？"

为避免让用户不堪重负，避免在单条消息中提出过多问题。先从最重要的问题开始，并根据需要继续追问，以获得更好的效果。

当对 skill 应支持的功能有了清晰的认识时，即可结束此步骤。

第 2 步：规划可复用技能的内容

要将具体示例转化为有效的技能，请通过以下方式分析每个示例：

1. 考虑如何从零开始执行该示例
2. 确定在反复执行这些工作流时，哪些脚本、参考资料和资产会有所帮助

规划清单：

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

示例：在构建 pdf-editor 技能以处理诸如"帮我旋转这个 PDF"之类的查询时，分析表明：

1. 旋转 PDF 每次都需要重新编写相同的代码
2. 一个 scripts/rotate_pdf.py 脚本会有所帮助，应存储在技能中
3. ❌ 不要创建 references/api-docs.md - 而应将 API 信息放入 SKILL.md

示例：在为诸如"帮我构建一个待办事项应用"或"帮我构建一个追踪步数的仪表盘"之类的查询设计 frontend-webapp-builder 技能时，分析表明：

1. 编写前端 Web 应用每次都需要相同的 HTML/React 样板代码
2. 一个包含样板 HTML/React 项目文件的 assets/hello-world/ 模板会有所帮助，应存储在技能中
3. ❌ 不要创建 references/usage-examples.md - 而应将示例放入 SKILL.md

示例：在构建 big-query 技能以处理诸如"今天有多少用户登录了？"之类的查询时，分析表明：

1. 查询 BigQuery 每次都需要重新发现表结构和关系
2. 一个记录表结构的 references/schema.md 文件会有所帮助，应存储在技能中（仅因为结构非常大）
3. ❌ 不要创建单独的 references/query-examples.md - 而应将示例放入 SKILL.md

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

第 3 步：初始化技能

此时，是时候真正创建技能了。

仅当正在开发的技能已存在且需要迭代时，才跳过此步骤。在这种情况下，请继续下一步。

从头创建新技能时，始终运行 init_skill.py 脚本。该脚本会方便地生成一个新的模板技能目录，自动包含技能所需的一切，使技能创建过程更加高效和可靠。

用法：

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

示例：

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> 是系统提示词"Workspace"部分中显示的工作区目录。

该脚本：

• 在指定路径创建技能目录
• 生成带有正确 frontmatter 和 TODO 占位符的 SKILL.md 模板
• 根据 --resources 可选地创建资源目录
• 当设置 --examples 时可选地添加示例文件

初始化后，根据需要自定义 SKILL.md 并添加资源。如果你使用了 --examples，请替换或删除占位文件。

重要：始终在工作区技能目录（<workspace>/skills）中创建技能，而不是在项目目录中。请查看"Workspace"部分以获取实际的工作区路径。

第 4 步：编辑技能

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

设计模式

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

# Sequential: list numbered steps with scripts
1. Analyze the form (run analyze_form.py)
2. Create field mapping (edit fields.json)
3. Fill the form (run fill_form.py)

# Conditional: guide through decision points
1. Determine the modification type:
   **Creating new content?** → Follow "Creation workflow"
   **Editing existing content?** → Follow "Editing workflow"

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

从可复用的技能内容开始

要开始实现，请从上面确定的可复用资源入手：scripts/、references/ 和 assets/ 文件。请注意，此步骤可能需要用户输入。例如，在实现 brand-guidelines 技能时，用户可能需要提供品牌资产或模板以存储在 assets/ 中，或提供文档以存储在 references/ 中。

可用的基础工具：

Agent 可以访问以下核心工具，你可以在技能中加以利用：

• 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 行）时创建。大多数技能不需要此项。
• assets/：仅包含输出中使用的文件（模板、图标等）
• 默认做法：除非有特定理由不这样做，否则将所有内容放入 SKILL.md。

添加的脚本必须通过实际运行来测试，以确保没有缺陷，并且输出符合预期。如果存在许多相似的脚本，只需测试具有代表性的样本，以在确保它们都能正常工作的信心的同时平衡完成时间。

如果你使用了 --examples，请删除技能不需要的任何占位文件。只创建实际需要的资源目录。

更新 SKILL.md

写作准则： 始终使用祈使式/不定式形式。

Frontmatter

使用 name、description 和可选的 metadata 编写 YAML frontmatter：

• name：技能名称
• description：这是技能的主要触发机制，帮助 Agent 理解何时使用该技能。
  • 同时包含该 Skill 的功能以及使用它的具体触发条件/场景。
  • 在此处包含所有“何时使用”的信息——不要放在正文中。正文仅在触发后才会加载，因此正文中的“When to Use This Skill”部分对 Agent 没有帮助。
  • docx 技能的示例 description：“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：（可选）指定要求和配置
  • requires.bins：必需的二进制文件（例如 ["curl", "jq"]）
  • requires.env：必需的环境变量——必须全部设置（例如 ["MYAPI_KEY"]）
  • requires.anyEnv：备选环境变量——至少设置一个（例如 ["OPENAI_API_KEY", "LINKAI_API_KEY"]）
  • requires.anyBins：备选二进制文件——至少存在一个
  • always：设为 true 可无视要求始终加载
  • emoji：技能图标（可选）
  • 不要设置 category——它默认为 skill 并由系统管理

API Key 要求：

如果你的技能需要单个 API key，请在 requires.env 中声明：

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

如果你的技能支持多个 API key 提供方（例如 OpenAI 或 LinkAI），请使用 requires.anyEnv：

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

自动启用规则：当设置了必需的环境变量时，技能会自动启用；缺失时会自动禁用。无需手动配置。

正文

编写使用该技能及其捆绑资源的说明。

如果你的技能需要 API key，请在正文中包含设置说明：

## Setup

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

1. Visit https://service.com to get an API key
2. Configure it using: `env_config(action="set", key="SERVICE_API_KEY", value="your-key")`
3. Or manually add to `~/cow/.env`: `SERVICE_API_KEY=your-key`
4. Restart the agent for changes to take effect

## Usage
...

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

#!/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 说明时，请记住：

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

SKILL.md 中的示例说明：

## Usage

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

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

第 5 步：验证（可选）

验证技能格式：

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

示例：

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

验证检查项：

• YAML frontmatter 格式和必填字段
• 技能命名约定（连字符式、小写）
• description 的完整性和质量
• 文件组织

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

第 6 步：迭代

根据实际使用情况进行改进：

1. 在真实任务中使用技能
2. 留意困难或低效之处
3. 确定需要对 SKILL.md 或资源进行的更新
4. 实施更改并再次测试

渐进式披露

技能采用三级加载：

1. Metadata（name + description）- 始终在上下文中（约 100 词）
2. SKILL.md 正文 - 技能触发时加载（<5k 词）
3. 资源 - 由 Agent 按需加载

最佳实践：

• 保持 SKILL.md 少于 500 行
• 将复杂内容拆分到 references/ 文件中
• 在 SKILL.md 中清晰引用这些文件

模式：对于具有多个变体/框架的技能：

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

示例：

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

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