write-a-skill

name	write-a-skill
description	以正确的技能结构、渐进式披露与打包资源来创建新的 agent 技能。适用于用户希望创建、编写或构建新的技能。

写作技能（Writing Skills）

流程（Process）

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

   • 该技能覆盖的任务/领域是什么？
   • 需要处理哪些具体使用场景？
   • 是否需要可执行脚本，还是只提供说明即可？
   • 是否需要附带参考资料？

2. 起草技能 - 创建：

   • 简洁的 SKILL.md 主说明
   • 若内容超过 500 行，补充额外参考文件
   • 若需要确定性操作，再添加工具脚本

3. 与用户一起复核 - 展示草稿并询问：

   • 这是否覆盖你的使用场景？
   • 是否有遗漏或不清楚之处？
   • 哪些章节需要更详细/更精简？

技能结构（Skill Structure）

skill-name/
├── SKILL.md           # 主说明（必需）
├── REFERENCE.md       # 详细文档（如需）
├── EXAMPLES.md        # 使用示例（如需）
└── scripts/           # 工具脚本（如需）
    └── helper.js

SKILL.md 模板

---
name: skill-name
description: 对能力的简短说明。适用于 [特定触发条件]。
---

# 技能名称

## 快速开始

[最小可用示例]

## 工作流

[包含检查清单的分步骤流程（适用于复杂任务）]

## 高级特性

[如需更详细内容：见 [REFERENCE.md](REFERENCE.md)]

描述要求（Description Requirements）

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

目标：让 agent 只需要获得足够信息即可判断：

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

格式要求：

• 最多 1024 个字符
• 使用第三人称表述
• 第一句：做什么
• 第二句：使用“适用于 [特定触发条件]”

良好示例：

从 PDF 文件中提取文本与表格，填写表单并合并文档。适用于处理 PDF 文件，或用户提到 PDF、表单、文档提取等场景。

不良示例：

处理文档。

该不良示例无法让 agent 与其他文档类技能区分开来。

何时添加脚本（When to Add Scripts）

当需要以下情况时，添加工具脚本：

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

相较于生成代码，脚本可以节省 token，并提升稳定性与可预期性。

何时拆分文件（When to Split Files）

当出现以下情况时，将内容拆分到独立文件：

• SKILL.md 超过 100 行
• 内容属于不同领域（例如财务 vs 销售 schema）
• 高级特性很少需要

复核清单（Review Checklist）

起草完成后，请复核：

• 描述包含触发条件（例如“适用于...”）
• SKILL.md 行数少于 100
• 不包含时间敏感信息
• 术语前后一致
• 包含具体示例
• 引用内容只需一层（不要过度嵌套引用）