第三章：SKILL.md 编写¶

文件结构¶

SKILL.md 由两部分组成：

---
name: skill-name
description: Skill 描述和触发条件
---

# Skill 标题

正文内容...

YAML Frontmatter¶

必需字段¶

---
name: pdf-editor
description: |
  PDF 文档处理技能。支持创建、编辑、合并、拆分 PDF。
  当用户需要：
  (1) 创建 PDF 文档
  (2) 编辑 PDF 内容
  (3) 合并多个 PDF
  (4) 提取 PDF 页面
  时使用此技能。
---

描述编写指南¶

description 是触发机制的核心，要包含：

# 公式
description: |
  [功能概述]。
  当用户需要：
  (1) [场景1]
  (2) [场景2]
  (3) [场景3]
  时使用此技能。

好的描述示例¶

# 示例1：文档处理
description: |
  Word 文档创建、编辑和分析技能。支持：
  (1) 创建新文档
  (2) 修改现有内容
  (3) 处理修订跟踪
  (4) 添加批注
  当 Codex 需要处理 .docx 文件时使用。

# 示例2：数据分析
description: |
  数据分析和可视化技能。支持数据清洗、统计分析、
  图表生成和报告输出。当用户需要分析数据、
  生成图表或创建数据报告时使用。

# 示例3：云部署
description: |
  云服务部署和管理技能。支持 AWS、GCP、Azure
  三大云平台。当用户需要部署应用、配置基础设施
  或管理云资源时使用。

不好的描述示例¶

# 太简短
description: PDF 技能

# 缺少触发条件
description: 这个技能可以帮助处理 PDF 文件。

# 信息重复
description: |
  PDF 处理技能。
  详见正文。

正文编写¶

基本结构¶

# Skill 名称

一句话描述功能。

## 快速开始

最常用的基本用法。

## 工作流程

详细步骤说明。

## 高级功能

复杂用法和选项。

## 参考资料

链接到 references/ 文件。

使用祈使语气¶

# ✅ 好的写法
## 创建文档

使用 docx-js 创建新文档：

```python
from docx import Document
doc = Document()

❌ 不好的写法¶

创建文档¶

你可以使用 docx-js 来创建新文档。这个库允许你创建一个新的文档对象，然后添加内容...

### 提供简洁示例

```markdown
# ✅ 好的示例
## 提取文本

```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    for page in pdf.pages:
        print(page.extract_text())

❌ 冗长的示例¶

提取文本¶

首先，你需要安装 pdfplumber 库。可以使用 pip 安装： pip install pdfplumber

安装完成后，你可以导入库并打开 PDF 文件...

### 渐进式披露

```markdown
# ✅ 好的设计
## 快速开始

基础提取：
```python
text = extract_text("file.pdf")

高级功能¶

表单填充: 见 FORMS.md
API 参考: 见 REFERENCE.md
示例集合: 见 EXAMPLES.md

❌ 不好的设计¶

快速开始¶

[所有内容都在这里...] [继续更多内容...] [还有更多...]

## 常见章节模板

### 工具型 Skill

```markdown
---
name: pdf-editor
description: PDF 处理技能。当需要创建、编辑、合并 PDF 时使用。
---

# PDF 编辑器

处理 PDF 文档的创建、编辑和转换。

## 快速开始

### 提取文本

```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

合并 PDF¶

from PyPDF2 import PdfMerger
merger = PdfMerger()
merger.append("file1.pdf")
merger.append("file2.pdf")
merger.write("merged.pdf")

可用脚本¶

scripts/rotate.py - 旋转页面
scripts/watermark.py - 添加水印

高级功能¶

详见 references/advanced.md

### 工作流型 Skill

```markdown
---
name: code-review
description: 代码审查工作流。当需要审查代码、检查质量时使用。
---

# 代码审查

系统化的代码审查工作流。

## 工作流程

1. **获取变更**
   ```bash
   git diff main...feature-branch
   ```

2. **静态分析**
   - 检查代码风格
   - 检测潜在问题
   - 分析复杂度

3. **安全审查**
   - 检查敏感信息
   - 验证权限控制

4. **生成报告**
   - 汇总发现
   - 提供建议

## 检查清单

见 [references/checklist.md](references/checklist.md)

领域型 Skill¶

---
name: finance-report
description: 财务报告生成技能。当需要生成财务报表、分析数据时使用。
---

# 财务报告

生成标准财务报告。

## 报告类型

- 资产负债表
- 利润表
- 现金流量表

## 数据格式

见 [references/schema.md](references/schema.md)

## 模板

使用 `assets/report-template.xlsx`

引用其他文件¶

引用 references/¶

# 详细文档在 references/ 中
详见 [references/api-docs.md](references/api-docs.md)

# 特定章节
认证相关见 [references/api-docs.md#authentication](references/api-docs.md)

引用 scripts/¶

# 使用脚本
运行 `scripts/process.py` 处理数据：

```bash
python scripts/process.py --input data.csv

### 引用 assets/

```markdown
# 使用模板
复制 `assets/template.html` 作为起点：

```bash
cp assets/template.html output.html

## 长度控制

### 保持精简

```markdown
# 目标
- SKILL.md < 500 行
- 核心内容 < 5000 词

# 策略
1. 详细内容放 references/
2. 只保留核心工作流
3. 使用示例代替解释
4. 链接而非复制

超长文件处理¶

# 当 SKILL.md 接近 500 行时

## 选项 1：拆分到 references/
将高级功能移到 references/advanced.md

## 选项 2：精简内容
删除冗余解释，保留核心指令

## 选项 3：重组结构
按变体/领域拆分到多个 reference 文件

常见错误¶

错误 1：Frontmatter 字段过多¶

# ❌ 错误
---
name: my-skill
description: 描述
version: 1.0.0          # 不需要
author: name            # 不需要
dependencies: [...]     # 不需要
---

# ✅ 正确
---
name: my-skill
description: 描述
---

错误 2：描述缺少触发条件¶

# ❌ 错误
description: 这是一个 PDF 处理技能。

# ✅ 正确
description: |
  PDF 处理技能。当用户需要创建、编辑、合并 PDF 时使用。

错误 3：正文过于冗长¶

# ❌ 错误
## 介绍

PDF（Portable Document Format）是一种文件格式...
（大量背景知识）

## 历史

PDF 由 Adobe 公司于 1993 年...
（无关历史）

# ✅ 正确
## 快速开始

```python
import pdfplumber
# 直接开始使用

```

小结¶

本章介绍了 SKILL.md 的编写：

Frontmatter 只包含 name 和 description
description 是触发机制的核心
正文使用祈使语气
提供简洁示例
使用渐进式披露
控制文件长度

下一章将介绍脚本和资源的设计。