深度解析：如何系统性地优化一个 Claude Skill

my-skill/
├── SKILL.md              # 必须
└── bundled-resources/    # 可选
    ├── scripts/          # 可执行脚本
    ├── references/       # 参考文档
    └── assets/           # 模板、字体、图标等

---
name: my-skill
description: >
  当用户需要做 X 的时候使用此 Skill。具体触发场景包括：
  提到"X工作流"、"需要处理Y格式"、或者问及"怎么做Z"。
  即便用户没有明确说"用skill"，只要涉及X领域的复杂任务，也要触发。
compatibility:
  tools:
    - bash
    - python3
---

## 主流程（必读）
简洁描述核心工作流，3-5步以内。

## 边界情况处理
只有遇到特殊输入时才需要阅读本节。

## 参考文档索引
- references/aws.md — AWS 部署配置
- references/gcp.md — GCP 部署配置
仅在涉及对应云平台时读取。

执行以下命令完成转换：
```bash
python /mnt/skills/my-skill/scripts/convert.py --input $INPUT --output $OUTPUT

---

## 三、优化循环：从草稿到精品的迭代路径

Skill 优化遵循一个核心循环：

### 3.1 第一步：捕获意图

在动手写之前，先回答四个问题：

1. 这个 Skill 要让 Claude 具备什么能力？
2. 哪些用户输入应该触发它？
3. 期望的输出格式是什么？
4. 输出是否有客观正确性（适合定量测试）？还是主观的（依赖人工评估）？

**客观输出**（文件转换、数据提取、代码生成）→ 写测试断言，做定量评估。  
**主观输出**（写作风格、创意内容）→ 依赖人工定性评估。

### 3.2 第二步：设计测试用例

一个好的测试用例包含：

```json
{
  "prompt": "请帮我把这个 Excel 文件转换成 CSV，并去掉空行",
  "assertions": [
    {
      "type": "file_exists",
      "value": "output.csv"
    },
    {
      "type": "content_contains",
      "value": "非空行数据"
    }
  ]
}

# Before（弱）
description: 用于处理 DOCX 文件的 Skill。

# After（强）
description: >
  当用户需要创建、读取、编辑或操作 Word 文档（.docx 文件）时使用。
  触发场景包括：提到"Word文档"、".docx"、需要带目录/页眉/页码等格式的专业文档、
  从.docx提取内容、在文档中插入图片、进行查找替换。
  即便用户只说"写一份报告"、"写一个备忘录"，如果明显是需要Word格式的，也应触发。

即便用户没有明确提到"skill"或具体工具名，只要涉及X类型的复杂任务，也必须触发本Skill。

注意：如果任务是简单的文本问答或基础代码演示（少于20行），不需要触发本Skill。

触发词：制作PPT / 做幻灯片 / 写演讲稿 / presentation / deck / 讲稿 / 课件

python -m scripts.run_loop \
  --eval-set trigger-eval.json \
  --skill-path ./my-skill \
  --model claude-sonnet-4-20250514 \
  --max-iterations 5 \
  --verbose

[
  {
    "prompt": "帮我把这个Excel转成Word格式的报告",
    "should_trigger": true
  },
  {
    "prompt": "解释一下Python的装饰器是什么",
    "should_trigger": false
  },
  {
    "prompt": "我需要一份带封面和目录的年度总结文档",
    "should_trigger": true
  }
]

## 核心流程（必读）
[10-20行的核心步骤描述]

## 详细配置
→ 根据你的需求，读取对应的参考文档：
- AWS 部署：`references/aws.md`
- GCP 部署：`references/gcp.md`
- 高级网络配置：`references/networking.md`

## 常见错误排查
→ 如果遇到报错，读取 `references/troubleshooting.md`

# AWS 部署参考

## 目录
- [1. IAM 权限配置](#iam)（第15-60行）
- [2. VPC 网络设置](#vpc)（第61-120行）
- [3. EC2 实例类型选择](#ec2)（第121-200行）
...

---
name: hugo-writer
description: 用于写 Hugo 文章的 Skill。
---

## 步骤
1. 写 frontmatter
2. 写正文
3. 保存文件

---
name: hugo-writer
description: >
  当用户需要创作 Hugo 格式的 Markdown 文章时使用，尤其是深度长文、技术博客、
  教程或分析性文章。触发场景：提到"Hugo文章"、"md博客"、"深度长文"、"技术博客"、
  需要带frontmatter的Markdown文件。即便用户只说"写一篇关于X的文章发到博客"，
  也应触发本Skill。不适用于简单的文本问答或短段落创作。
---

## Hugo 文章写作规范

### Frontmatter 必填字段
```yaml
---
title: "文章标题（简洁、包含核心关键词）"
date: YYYY-MM-DDTHH:MM:SS+08:00  # 使用当前时间
draft: false
description: "SEO描述，120-160字符"
tags: []
categories: []
author: ""
slug: "url-friendly-slug"
toc: true  # 深度长文必须开启目录
---

### 优化效果分析

经过这次优化：

1. **触发率**：description 从1句话扩展到包含多场景、关键词、边界说明，预期触发率显著提升
2. **输出质量**：明确规定了字数、必填字段、结构要求，输出更一致
3. **边界清晰**：明确说明了什么情况不触发，避免过度触发

---

## 八、总结与最佳实践清单

Skill 优化是一个**持续迭代**的工程实践，不存在"写完就完"的状态。随着使用场景积累更多反馈，Skill 应该持续演进。

### 最佳实践清单

**设计阶段**
- [ ] 明确 Skill 的唯一核心能力，不要"大而全"
- [ ] 区分哪些输出是客观可测的，哪些是主观的
- [ ] 准备至少 10 个测试用例，涵盖正常路径和边界情况

**写作阶段**
- [ ] SKILL.md 控制在 500 行以内
- [ ] description 使用"推送式"写法，列出多个触发场景
- [ ] 核心步骤不超过 5 步，细节放到参考文件
- [ ] 为每个参考文件标注"何时读取"
- [ ] 使用强制性语言（"必须"/"始终"）而非软性语言（"尽量"/"如果可能"）

**测试阶段**
- [ ] 测试用例有足够的复杂度（避免简单一步请求）
- [ ] 运行测试并记录实际输出
- [ ] 人工评估：格式是否正确、步骤是否完整

**优化阶段**
- [ ] 根据测试反馈修改 SKILL.md，而非凭直觉猜测
- [ ] 重点关注"触发不足"问题，优先优化 description
- [ ] 在 Claude Code / Cowork 环境中考虑使用 `run_loop.py` 做自动化描述优化
- [ ] 迭代至少 3 轮后再发布

**维护阶段**
- [ ] 收集用户反馈，建立 Bad Case 记录
- [ ] 定期回顾 Skill 的测试集是否仍有覆盖价值
- [ ] 版本更新时保留原有 `name` 字段，确保向后兼容

---

> **写在最后**：Skill 系统的设计哲学是"渐进式上下文管理"——把对的信息在对的时间放到模型的注意力中。一个优秀的 Skill 不是信息的堆砌，而是对"Claude 在这个场景下真正需要什么"的精准理解。这需要观察、测试、倾听反馈，然后不断打磨。

---

*文章生成时间：2026-03-22 02:31 CST*  
*基于 Claude Skill Creator 系统文档及工程实践整理*