第八章：最佳实践¶
设计原则¶
1. 简洁优先¶
❌ 不好的做法¶
介绍¶
PDF（Portable Document Format）是由 Adobe 公司开发的一种文件格式... （大量背景知识）
**原则**：上下文窗口是公共资源，只添加必要信息。
### 2. 渐进披露
```markdown
# ✅ 好的做法
## 快速开始
[基础示例]
## 高级功能
详见 [advanced.md](references/advanced.md)
# ❌ 不好的做法
[所有内容都在 SKILL.md 中]
原则：信息分层，按需加载。
3. 示例驱动¶
# ✅ 好的做法
## 提取文本
```python
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
❌ 不好的做法¶
提取文本¶
首先需要打开文件，然后访问 pages 属性， 接着调用 extract_text 方法...
**原则**：用代码示例代替冗长解释。
## 常见模式
### 工具型 Skill 模板
```markdown
---
name: tool-name
description: |
工具功能描述。支持：
(1) 功能1
(2) 功能2
当用户需要处理 X 时使用。
---
# 工具名称
一句话描述。
## 快速开始
最常用的基本用法。
## 可用脚本
- `scripts/action1.py` - 功能说明
- `scripts/action2.py` - 功能说明
## 高级功能
详见 [references/advanced.md](references/advanced.md)
工作流型 Skill 模板¶
---
name: workflow-name
description: |
工作流描述。当需要执行 X 流程时使用。
---
# 工作流名称
## 工作流程
1. **步骤一**
具体操作
2. **步骤二**
具体操作
3. **步骤三**
具体操作
## 检查清单
- [ ] 检查项1
- [ ] 检查项2
## 参考资料
见 [references/guide.md](references/guide.md)
领域型 Skill 模板¶
---
name: domain-name
description: |
领域描述。当需要处理 X 领域数据时使用。
---
# 领域名称
## 领域概述
简要说明。
## 数据结构
见 [references/schema.md](references/schema.md)
## 常用操作
### 操作1
```python
# 示例代码
操作2¶
详细文档¶
反模式 3：重复内容¶
# ❌ 避免
## SKILL.md
[完整 API 文档]
## references/api.md
[相同的完整 API 文档]
# ✅ 推荐
## SKILL.md
基础用法示例
## references/api.md
完整 API 文档
反模式 4：过度抽象¶
# ❌ 避免
## 处理器模式
使用抽象工厂模式创建处理器实例...
# ✅ 推荐
## 处理文件
```python
processor = FileProcessor()
processor.process("file.pdf")
## 质量检查清单
```yaml
quality-checklist:
description:
- [ ] 长度 > 20 字符
- [ ] 包含功能说明
- [ ] 包含触发条件
- [ ] 使用数字列表枚举功能
content:
- [ ] SKILL.md < 500 行
- [ ] 使用祈使语气
- [ ] 有代码示例
- [ ] 引用链接有效
structure:
- [ ] 目录结构清晰
- [ ] 无禁止文件
- [ ] 命名符合规范
scripts:
- [ ] 有错误处理
- [ ] 有参数验证
- [ ] 有使用说明
- [ ] 测试通过
持续改进¶
收集反馈¶
# 改进来源
1. 用户反馈
- Skill 未触发
- 功能不符合预期
- 错误信息不清晰
2. 使用分析
- 常用功能
- 很少使用的功能
- 错误频率
3. 性能监控
- 执行时间
- 资源占用
- 上下文使用
迭代优化¶
# 优化流程
1. 识别问题
- 收集反馈
- 分析数据
2. 制定方案
- 确定改进点
- 设计解决方案
3. 实施改进
- 更新 SKILL.md
- 添加/修改脚本
- 更新引用文档
4. 测试验证
- 功能测试
- 集成测试
5. 发布更新
- 打包发布
- 通知用户
总结¶
核心要点¶
┌─────────────────────────────────────────────────────────────┐
│ │
│ Skill 开发核心原则 │
│ │
│ 1. 简洁优先 │
│ - 上下文是公共资源 │
│ - 只添加必要信息 │
│ │
│ 2. 渐进披露 │
│ - 元数据 → 正文 → 引用 │
│ - 信息分层加载 │
│ │
│ 3. 示例驱动 │
│ - 代码胜过解释 │
│ - 简洁明了 │
│ │
│ 4. 持续改进 │
│ - 收集反馈 │
│ - 迭代优化 │
│ │
└─────────────────────────────────────────────────────────────┘
开发流程总结¶
1. 理解需求 → 收集具体用例
2. 规划内容 → 确定脚本、引用、资产
3. 初始化 → 创建目录结构
4. 编写内容 → SKILL.md + 资源文件
5. 测试验证 → 功能测试 + 集成测试
6. 打包发布 → 验证 + 打包 + 发布
7. 持续改进 → 反馈 + 优化