编写一项技能

write-a-skill
分类编程
作者Alireza Rezvani
许可MIT
评分4.90/5
使用3.1K

编写技能 (Writing Skills)

> 衍生自 Matt Pocock 的 write-a-skill (MIT)。原样保留了 Matt 的语气和三阶段工作流。新增内容：验证工具 + 引用 + cs-* 包装器（见下文 *工具与配套*）。

流程

1. 收集需求 - 询问用户：
- 该技能涵盖的任务/领域是什么？
- 需要处理哪些具体用例？
- 是需要可执行脚本还是仅需指令？
- 是否有需要包含的参考资料？

2. 起草技能 - 创建：
- 包含简洁指令的 SKILL.md
- 如果内容超过 500 行，创建额外的参考文件
- 如果需要确定性操作，创建实用脚本

3. 用户评审 - 展示草案并询问：
- 这是否涵盖了你的用例？
- 是否有遗漏或不清晰的地方？
- 哪些部分需要增加或减少细节？

技能结构

code
skill-name/
├── SKILL.md           # 主指令（必填）
├── REFERENCE.md       # 详细文档（可选）
├── EXAMPLES.md        # 使用示例（可选）
└── scripts/           # 实用脚本（可选）
    └── helper.js

SKILL.md 模板

md
---
name: skill-name
description: 能力的简短描述。在 [特定触发条件] 时使用。
---

技能名称


快速上手


[最小可行性示例]


工作流


[针对复杂任务的步骤流程及检查清单]


高级特性


链接到独立文件：参见 [REFERENCE.md]

描述 (Description) 要求

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

目标：为智能体提供足够的信息，使其能够获知：

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

格式：

  • 最多 1024 个字符
  • 使用第三人称编写
  • 第一句：它能做什么
  • 第二句：“在 [特定触发条件] 时使用”

优秀示例：

code
从 PDF 文件中提取文本和表格，填写表单，合并文档。在处理 PDF 文件或用户提到 PDF、表单或文档提取时使用。

糟糕示例：

code
帮助处理文档。

糟糕的示例让智能体无法将其与其他文档技能区分开来。

何时添加脚本

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

  • 操作是确定性的（验证、格式化）
  • 相同的代码会被重复生成
  • 需要显式的错误处理

相比于生成的代码，脚本可以节省 Token 并提高可靠性。

何时拆分文件

在以下情况拆分为独立文件：

  • SKILL.md 超过 100 行
  • 内容属于不同的领域（例如：财务架构 vs 销售架构）
  • 高级特性很少被用到

评审检查清单

起草完成后，请验证：

  • [ ] 描述中包含触发条件（“在...时使用”）
  • [ ] SKILL.md 低于 100 行
  • [ ] 不含时效性信息
  • [ ] 术语一致
  • [ ] 包含具体示例
  • [ ] 引用深度不超过一级

工具与配套

验证工具和 cs-* 封装程序与本技能配套。可通过编程方式运行所有 6 项审核清单检查项：

code
python scripts/skill_review_checklist_runner.py path/to/skill-folder

有关工具目录、cs-skill-author 角色代理以及 /cs:write-a-skill 斜杠命令，请参阅 references/companion_tooling.md。

---

版本： 1.0.0
衍生自： Matt Pocock (MIT) + 本仓库的封装程序