skill规范详解（6）— content正文部分

Body Content（正文）是SKILL.md的核心灵魂，本质上是写给 Agent的SOP说明书。它位于frontmatter之后，负责告诉Agent激活后具体如何执行任务，并严格遵循≤500行（硬校验）、≤5000tokens（软校验）的篇幅限制，超出内容必须剥离至references/目录。

一、核心设计原则

只写模型自身无法可靠完成的部分。模型已能稳定处理的通用常识或领域知识不应写入，冗余内容会浪费Token并干扰决策。具体聚焦以下四类：

模型会做错的：领域概念混淆、意图消歧规则、参数映射逻辑
模型做得不稳定的：高频场景的推理模式、多步流程的执行顺序
做错了代价大的：不可逆操作的确认机制、安全红线、数据风险约束
产品特定的体验要求：输出格式、交互话术、降级策略

二、四层六块结构

正文按 知识层 → 能力层 → 编排层 → 协作层 四层组织，涵盖6个内容块：

内容块	所属层	参考行数	说明
领域知识	知识层	10–25 行	模型容易混淆的领域特有概念
工具定义	能力层	50–150 行	Skill 依赖的工具/脚本详细说明
经验攻略	编排层	30–60 行	高频场景的推荐做法
操作规程	编排层	20–40 行	不可逆/多步操作的严格流程
安全红线	编排层	10–20 行	绝对禁止的操作
与人协作	协作层	15–30 行	歧义/缺参时的确认策略

1. 知识层：领域知识

控制在 3–5 条、每条 1–2 行，只写模型容易混淆的要点：

## 领域知识
- "季度"在本系统中指自然季度（1-3月、4-6月…），不是财年季度
- 用户说"最近的报告"默认指最近一个自然月，不是最近7天
- CSV编码统一为UTF-8 with BOM，避免Excel打开乱码

知识量 < 10 行直接写入正文；大段知识应剥离到 references/，正文只放索引。

2. 能力层：工具定义

当Skill依赖scripts/中的脚本时，必须逐一说明其功能、参数和输出格式：

## 工具定义
### scripts/extract.py
从 PDF 中提取结构化数据。
- 输入：`python3 scripts/extract.py <pdf_path> --format json`
- 输出：JSON 格式的键值对，写入 stdout
- 错误：非零退出码 + stderr 输出错误信息

### scripts/validate.sh
校验提取结果的完整性。
- 输入：`bash scripts/validate.sh <json_path>`
- 输出：校验通过返回 0，失败返回 1 并输出缺失字段

3. 编排层：经验攻略+操作规程+安全红线

经验攻略覆盖高频场景，Agent可灵活调整：

## 经验攻略
- 用户未指定输出格式时，优先使用Markdown表格
- 数据量超过100行时，先输出前10行预览，确认后再处理全部
- 遇到编码问题时，依次尝试UTF-8 → GBK → Latin-1

**操作规程（SOP）**用于不可逆或多步依赖操作，Agent 必须严格按序执行，禁止跳步：

## 操作规程：数据库迁移
1. 备份当前数据库：`pg_dump -Fc mydb > backup.dump`
2. 确认备份文件存在且大小 > 0
3. 执行迁移脚本：`python3 scripts/migrate.py`
4. 运行校验：`python3 scripts/validate.py`
5. 校验通过后，删除备份文件

安全红线列出领域特有禁止项，Agent 禁止违背，绝对底线：

## 安全红线
- 禁止执行 DROP、DELETE、TRUNCATE 等不可逆 SQL 操作
- 禁止在日志中输出用户密码、Token 等敏感信息
- 禁止修改 production 环境的配置，只能修改 staging

4. 协作层：与人协作

定义歧义或缺参场景下的确认策略：

## 与人协作
- 用户说"清理数据"但未指定范围时，必须确认是清理全部还是部分
- 输出结果超过 50 行时，询问用户是否需要导出为文件
- 遇到无法解析的输入格式时，展示识别到的内容并请用户确认

三、渐进式披露机制

正文并非一次性全部加载，而是按需读取，以节省上下文空间：

Agent 激活 Skill
    ↓
加载 SKILL.md 正文（≤5000 tokens）
    ↓
执行过程中遇到需要详细参考的内容
    ↓
按需读取 references/ 中的文件（第三层）

正文只放核心流程和索引，详细技术文档放 references/：

## 参考资料
- 完整的 API 错误码说明，请阅读 [references/api-errors.md](references/api-errors.md)
- 高级用法和边界情况，请阅读 [references/advanced-usage.md](references/advanced-usage.md)

一句话总结：Body Content 的核心心法是"精简、结构化、只写必要的"——用最少的 Token 传递最关键的执行信息，让 Agent 在有限的上下文窗口内做出最准确的决策。

ishane.cn