编写 Skill

流程

1. 收集需求 — 向用户询问：
   - 这个 skill 覆盖什么任务/领域？
   - 应处理哪些具体用例？
   - 需要可执行脚本，还是只要说明即可？
   - 是否要纳入参考材料？

2. 起草 skill — 创建：
   - 简洁说明的 SKILL.md
   - 若内容超过 500 行，则增加额外参考文件
   - 若需要确定性操作，则增加实用脚本

3. 与用户评审 — 展示草稿并询问：
   - 是否覆盖你的用例？
   - 有无遗漏或不清楚之处？
   - 哪些部分应更详细或更简略？

Skill 结构

skill-name/
├── SKILL.md           # Main instructions (required)
├── REFERENCE.md       # Detailed docs (if needed)
├── EXAMPLES.md        # Usage examples (if needed)
└── scripts/           # Utility scripts (if needed)
    └── helper.js

SKILL.md 模板

---
name: skill-name
description: Brief description of capability. Use when [specific triggers].
---

# Skill Name

## Quick start

[Minimal working example]

## Workflows

[Step-by-step processes with checklists for complex tasks]

## Advanced features

[Link to separate files: See `REFERENCE.md`]

Description 要求

description 是 agent 决定加载哪个 skill 时唯一能看到的内容。它会与所有已安装 skill 一起出现在系统提示中。agent 读取这些 description，并根据用户请求选择相关 skill。

目标：给 agent 刚好足够的信息，让它知道：

1. 这个 skill 提供什么能力
2. 何时/为何触发（具体关键词、上下文、文件类型）

格式：

• 最多 1024 个字符
• 使用第三人称
• 第一句：它做什么
• 第二句："Use when [specific triggers]"

好例子：

Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.

坏例子：

Helps with documents.

坏例子无法让 agent 把它和其他文档类 skill 区分开。

何时添加脚本

在以下情况添加实用脚本：

• 操作是确定性的（校验、格式化）
• 同一段代码会反复生成
• 错误需要显式处理

相比生成代码，脚本能省 token，也更可靠。

何时拆分文件

在以下情况拆成独立文件：

• SKILL.md 超过 100 行
• 内容属于不同领域（例如 finance vs sales schema）
• 高级功能很少用到

评审清单

起草完成后，确认：

• [ ] Description 包含触发条件（"Use when..."）
• [ ] SKILL.md 少于 100 行
• [ ] 无时效性信息
• [ ] 术语一致
• [ ] 包含具体示例
• [ ] 引用层级不超过一层