# Skills MD 标准书写格式

> 本文档定义了 SKILL.md 的书写规范，涵盖描述质量、章节结构、内容简洁度、格式一致性四大维度。

---

## 1. YAML Frontmatter 规范

### description 字段（关键）

description 是 Agent 决定何时应用该 Skill 的核心依据，必须满足：

| 要求 | 说明 | 示例 |
|------|------|------|
| **第三人称** | 描述 Skills 做什么，不用 "我"、"你" | ✅ "处理 Excel 文件并生成报告" ❌ "我可以帮你处理 Excel" |
| **WHAT + WHEN** | 既说明功能，也说明触发场景 | ✅ "从 PDF 提取文本和表格。当用户处理 PDF 文件或提及 PDF、表单、文档提取时使用。" |
| **触发词** | 包含用户可能使用的关键词 | ✅ "触发词：抖音热榜、抖音日榜、抖音排名" |
| **长度控制** | 最多 1024 字符 | ❌ 超过 1024 字符将被截断 |

**检查清单**：
- [ ] 使用第三人称
- [ ] 包含 WHAT（功能描述）
- [ ] 包含 WHEN（触发场景 + 触发词）
- [ ] ≤ 1024 字符

---

## 2. 章节结构规范

### 2.1 层级规范

```
# 一级标题              → Skill 名称，简洁描述核心功能
## 二级标题             → 主要章节（概述、鉴权、流程、输出格式等）
### 三级标题            → 子章节（仅在内容确实需要细分时使用）
```

### 2.2 推荐章节（SKILL.md 用）

| 章节 | 说明 | 必选 |
|------|------|------|
| `# 标题` | 一级标题，简洁描述 Skill 功能 | ✅ |
| `## 📝 简介` | 2-3 句话说明核心功能、数据范围、更新时间，必须位于一级标题之后 | ✅ |
| `## ✨ 功能特性` | 三列表格（功能模块 | 能力描述 | 核心价值），4-6 行，必须位于简介之后 | ✅ |
| `## 🔑 鉴权` | API Key 获取与配置方式，必须位于功能特性之后 | ✅ |
| `## 核心参数` / `## API 调用` | 接口地址、认证方式、参数枚举 | 按需 |
| `## 交互流程` / `## 工作流程` | Agent 执行步骤，含决策分支 | 推荐 |
| `## 输出格式` / `## 标准输出格式` | Markdown 模板，确保输出一致性 | 推荐 |
| `## 文件输出与订阅` | 导出、订阅相关说明 | 按需 |
| `## 其他资源` | references 引用链接（渐进式披露） | 推荐 |

### 2.3 不应写入 SKILL.md 的内容

以下内容属于 README.md（用户文档），不应出现在 SKILL.md：

- "一键安装" 步骤
- "使用场景" 的角色扮演描述
- "项目架构" 的目录树和技术栈
- "常见问答"
- 基础知识科普（Agent 已知的背景信息）

---

## 3. 内容简洁度规范

### 3.1 核心原则

> **默认假设：Agent 已经非常聪明。只添加它不知道的上下文。**

每条信息写入前问自己：
- "Agent 真的需要这个解释吗？"
- "我能假设 Agent 知道这个吗？"
- "这一段值得它的 token 开销吗？"

### 3.2 删减目标

| 应删除 | 应保留 |
|--------|--------|
| 基础知识科普（如 "PDF 是一种文件格式..."） | 领域特定的业务规则 |
| 重复说明（同一概念多处解释） | 关键约束和边界条件 |
| 过长示例（3+ 个相似示例） | 1-2 个典型覆盖核心场景的示例 |
| 冗余修饰词（"请注意"、"需要特别说明的是"） | 精确的参数枚举和数据格式 |

### 3.3 行数控制

- SKILL.md 主体 **≤ 500 行**
- 超过 500 行时：将详细信息外移至 `references/` 目录

---

## 4. 格式一致性规范

### 4.1 术语统一

全文使用同一术语，禁止混用：

| ✅ 统一使用 | ❌ 禁止混用 |
|------------|------------|
| API 接口 | URL、端点、路由 |
| 参数 | 字段、属性、变量 |
| 脚本 | Python 文件、执行文件 |
| references/ | 参考文档、引用目录 |

### 4.2 表格规范

```markdown
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 内容 | 内容 | 内容 |
```

- 表头与分隔符对齐
- 内容短时不强制对齐空格

### 4.3 代码块规范

````markdown
```bash
python3 scripts/search.py "关键词"
```

```json
{"key": "value"}
```
````

- 必须标注语言类型
- 禁止无标注的代码块

### 4.4 路径规范

- ✅ `scripts/search.py`
- ✅ `references/api-config.md`
- ❌ `scripts\search.py`（Windows 风格）
- ❌ `./scripts/search.py`（冗余 `./` 前缀）

### 4.5 Emoji 使用

适度使用 emoji 强化关键节点识别：
- 章节标记：`## 📊 输出格式`
- 状态提示：`⚠️ 注意`、`✅ 正确`、`❌ 错误`
- 数据展示：`📊` 榜单、`🔥` 热门、`📩` 订阅

**禁止**：每行都用 emoji 装饰，喧宾夺主。

---

## 5. 渐进式披露规范

### 5.1 文件组织

```
skill-name/
├── SKILL.md              # 核心指令（≤ 500 行）
├── references/           # 详细参考资料
│   ├── api-config.md     # API 配置细节
│   ├── interaction-guide.md  # 交互流程细节
│   └── data-format.md    # 数据字段说明
└── scripts/              # 可执行脚本
```

### 5.2 引用方式

在 SKILL.md 中引用：

```markdown
详见 [api-config.md](references/api-config.md)
```

- 保持 **一级深度**：只从 SKILL.md 直接引用 references/ 下的文件
- 禁止深层嵌套引用（references/a.md → references/b.md）

### 5.3 外移判断标准

以下内容应外移至 references/：
- 超过 20 行的 API 参数枚举表
- 超过 30 行的交互决策树
- 完整的数据字段映射表（超过 10 个字段）
- 历史版本 / 废弃用法

---

## 6. 反模式

| 反模式 | 正确做法 |
|--------|---------|
| Windows 路径 `scripts\helper.py` | Unix 路径 `scripts/helper.py` |
| 给出多个等价选项让 Agent 困惑 | 提供默认方案 + 例外情况的逃生路径 |
| 时间敏感信息 "2025年8月前用旧API" | 使用"旧模式（已废弃）"折叠区块 |
| 术语混用 "接口/端点/URL" | 全书统一为 "API 接口" |
| 空壳章节（有标题无内容） | 删除整个章节 |
| 在 SKILL.md 写 README 内容 | 用户向内容放到 README.md |

---

## 7. 快速检查清单

优化完成后逐项验证：

- [ ] description 第三人称 + WHAT + WHEN + 触发词
- [ ] SKILL.md 开头包含「📝 简介」和「✨ 功能特性」章节
- [ ] SKILL.md 包含「🔑 鉴权」章节且位于功能特性之后
- [ ] SKILL.md ≤ 500 行
- [ ] 术语全文统一（选择一个术语，全文替换）
- [ ] 代码块标注语言类型（```bash、```json 等）
- [ ] 路径使用 `/` 分隔符
- [ ] 引用文件均为一级深度
- [ ] 无时间敏感信息
- [ ] 无 Windows 风格路径
- [ ] 无空壳章节
- [ ] 无基础知识科普