write-a-skill

编写技能

流程

1. 收集需求 - 向用户询问：

   • 该技能涵盖什么任务／领域？
   • 它应处理哪些具体用例？
   • 它需要可执行脚本，还是只需说明？
   • 是否需要包含任何参考资料？

2. 起草技能 - 创建：

   • 包含简洁说明的 SKILL.md
   • 如果内容超过 500 行，则添加额外的参考文件
   • 如果需要确定性操作，则添加工具脚本

3. 与用户审查 - 展示草稿并询问：

   • 这是否涵盖你的用例？
   • 是否有遗漏或不明确之处？
   • 是否有任何部分需要更详细／更简洁？

技能结构

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](REFERENCE.md)]

描述要求

描述是 Agent 在决定加载哪个技能时唯一能看到的内容。它会与其他所有已安装的技能一起显示在系统提示词中。Agent 会读取这些描述，并根据用户的请求选择相关技能。

目标：向 Agent 提供足够的信息，使其了解：

1. 该技能提供什么能力
2. 何时／为何触发它（具体关键词、上下文、文件类型）

格式：

• 最多 1024 个字符
• 使用第三人称
• 第一句：说明其功能
• 第二句：“在[具体触发条件]时使用”

良好示例：

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.md 超过 100 行
• 内容包含不同领域（财务与销售架构）
• 高级功能很少使用

审查清单

起草后，验证：

• 描述包含触发条件（“在……时使用……”）
• SKILL.md 少于 100 行
• 不含时效性信息
• 术语使用一致
• 包含具体示例
• 引用仅嵌套一层