正文模式

SKILL.md 的 frontmatter 决定 Skill 是否被加载，正文决定 Skill 触发后执行得好不好。正文不是越长越好，而是要把每次执行都需要的关键步骤、判断条件和输出约束讲清楚。

推荐骨架

适合大多数 Skill 的五段式结构：

段落	作用
概述	一句话说明 Skill 的核心职责
前置检查	确认输入、环境、依赖和权限
执行步骤	用编号 SOP 写清处理顺序
示例	覆盖正常、边界与错误场景
约束	明确什么不做，避免越界

示例骨架：

# PDF 表格提取

## 概述

从 PDF 文件中提取表格，并输出为 CSV 或 Markdown。

## 前置检查

1. 确认用户提供了 PDF 文件路径。
2. 如果 PDF 加密，先询问密码。
3. 如果用户没有指定输出格式，默认 Markdown。

## 工作流程

1. 检查文件是否存在。
2. 判断是否需要 OCR。
3. 提取表格。
4. 汇总异常页码。
5. 输出结果和待复核项。

## 示例

...

## 约束

- 不承诺法律或财务结论。
- 不删除原始文件。

六种常用 Pattern

1. Template Pattern

适合需要统一输出格式的 Skill。

## 输出格式

请始终按以下格式输出：

- 摘要：
- 关键发现：
- 风险：
- 下一步：

短模板可以放在 SKILL.md，长模板放进 assets/。

2. Examples Pattern

适合限定输入输出格式，降低 agent 自由发挥。

好的示例应覆盖：

• 正常输入
• 边界输入
• 错误输入

## 示例

用户：帮我检查这个 Skill 的 description。
输出：

1. 是否只写触发条件：...
2. 是否包含隐式场景：...
3. 建议改写：...

3. Conditional Workflow Pattern

适合多分支任务。用决策树替代“根据情况选择”。

## 输出格式选择

- 用户明确要求 PDF → 生成 PDF
- 用户明确要求网页 → 生成 HTML
- 用户没有说明 → 默认 Markdown

不要写：

可以输出 PDF、HTML 或 Markdown，根据情况自行选择。

4. Script Automation Pattern

适合确定性操作。正文说明何时调用脚本，脚本执行具体操作。

当需要统计 CSV 列缺失率时，运行：

```bash
python scripts/profile_csv.py --input data.csv --output profile.json
```

如果脚本返回 `MISSING_FILE`，向用户确认文件路径。

长命令或复杂逻辑优先放到 scripts/，不要让 agent 手写每一步。

5. Read-Process-Write Pattern

适合文件转换和数据清洗。

读取输入 → 处理内容 → 写入输出 → 汇报文件路径

正文要明确：

• 输入从哪里来
• 输出写到哪里
• 是否覆盖已有文件
• 失败时如何处理

6. Gotchas Pattern

适合记录领域里“agent 不知道就会犯错”的事实。

## Gotchas

- 合同里的“罚息比例”不是实际金额，不要计入金额汇总。
- PDF 页码可能与文件页序不同，输出时同时标注两者。
- 扫描版 PDF 需要 OCR，不要直接判定没有表格。

Gotchas 要短、具体、可执行。

内容拆分规则

当 SKILL.md 变长时，不要继续堆正文。

内容	建议位置
每次都必须遵守的步骤	SKILL.md
长篇 API 文档	references/
罕见边界情况	references/
输出模板	assets/
确定性转换逻辑	scripts/
示例数据	assets/ 或 references/

推荐上限：

• SKILL.md 少于 500 行
• 正文少于 5,000 token
• 引用路径保持一层深

正文自查清单

• [ ] 第一屏能看出 Skill 做什么
• [ ] 前置检查清楚
• [ ] 步骤有顺序，不是散文
• [ ] 分支条件明确
• [ ] 示例覆盖正常、边界、错误
• [ ] 约束写清楚什么不做
• [ ] 长资料已拆到 references/
• [ ] 模板已拆到 assets/
• [ ] 确定性操作已考虑 scripts/
• [ ] 没有把过期 API 信息塞进主流程

下一步

• Frontmatter 字段看 SKILL.md。
• 确定性操作看 使用 scripts。
• 写完后看 评估 Skill。