编写技能

源自 Matt Pocock 的 write-a-skill（MIT）。保留了 Matt 的风格和三阶段工作流。新增内容：验证工具 + 参考文档 + cs-* 封装（见下方 工具与配套 部分）。

流程

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 将此技能与其他文档技能区分开来。

何时添加脚本

在以下情况添加工具脚本：

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

脚本可以节省 token 并提高可靠性（相比生成代码）。

何时拆分文件

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

• SKILL.md 超过 100 行
• 内容涉及不同领域（如财务 vs 销售模式）
• 高级功能很少被使用

审查清单

起草完成后，验证：

• [ ] 描述包含触发条件（"当...时使用"）
• [ ] SKILL.md 不超过 100 行
• [ ] 无时效性信息
• [ ] 术语一致
• [ ] 包含具体示例
• [ ] 引用深度为一层

工具与配套

验证工具 + cs-* 封装与此技能并列。可通过编程方式运行全部 6 项审查清单：

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

详见 references/companion_tooling.md 了解工具目录、cs-skill-author 人格 Agent 和 /cs:write-a-skill 斜杠命令。

---

版本： 1.0.0 来源： Matt Pocock（MIT）+ 本仓库封装