周报生成 Skill

你已经在用 AI 了。

每天打开 Claude，问问题，改改文案，让它帮你整理一些东西。感觉有在用，但隐隐觉得哪里不对——怎么别人说 AI 能帮他们节省好几个小时，你这边就是快了一点点？

不是 AI 不行。是用法有问题。

大多数人用 Claude 的方式，本质上和用搜索引擎没什么区别。问一句，得一句。用完就关。下次再开一个新对话，重新解释一遍背景，重新等它理解你。每次都在从零开始。

这不叫用 AI。这叫在消耗 AI。

真正让 AI 给你带来质变提效的方式，叫做 Skill。但 90% 在琢磨 AI 的人，根本不知道这个东西的存在。知道的人里，有 90% 搭出来的 Skill 是烂的——我早期就是其中之一。

摸索了好几周，反复踩坑，做出来的 Skill 效果一般，产出质量差，还要不停返工。后来系统学了 prompt 优化的底层逻辑才明白：Skill 搭得烂，不是因为不够聪明，是因为根本没有一套科学的流程。

下面这六步，是我花了很长时间才拼出来的东西。

---

#先说清楚：Skill 到底是什么

Skill 是你给 Claude 预装的一套行为规范。

你可以把它理解成：一个提前写好的、针对某类任务的完整操作手册。Claude 读完这个手册，就知道碰到这类任务该怎么做、用什么工具、按什么步骤、输出什么格式。

没有 Skill 的 Claude，每次都要重新猜你要什么。

有了 Skill 的 Claude，一看到触发词，直接进入专家模式。

这不是玄学，这是工程问题。

---

#为什么你之前搭的 Skill 效果差

先做个自测。你之前是怎么搭 Skill 的？

大概率是这样：打开对话框，输入"帮我创建一个 XX Skill"，等 Claude 吐出一大段文字，复制粘贴，用一次，发现效果不行，然后放弃。

问题出在哪？

你没有给 Skill 写清楚三件事：做什么、什么时候触发、输出是什么。

Claude 不是读心术。你给它一个模糊的需求，它就还你一个模糊的结果。垃圾进，垃圾出——这个规律对人类成立，对 AI 同样成立。

哈佛商学院有研究：用 AI 完成任务的人，比不用 AI 的人快 25%，质量高 40% 以上。但这个数据的前提是——他们知道怎么用。

频繁的 AI 超级用户每周能节省 20 小时以上。

你上周用 AI 节省了几小时？

如果答案让你不舒服，那正是这篇文章要解决的问题。

---

#搭一个真正好用的 Skill，分六步走

第一步：想清楚再动手

在碰键盘之前，先在脑子里回答三个问题：

这个 Skill 能做什么？ 不要说"帮我处理工作"。要具体到：把用户上传的销售数据整理成可视化的周报，输出 Word 文件。

什么时候触发它？ 用户说什么话、上传什么文件时，Claude 应该自动调用这个 Skill？把所有可能的说法都列出来——"写周报"、"整理数据"、"生成报告"，越全越好。

输出是什么？ 一个文件？一段分析？一个可交互的界面？

这三个问题想不清楚，后面所有步骤都是在浪费时间。

---

第二步：建文件夹

Skill 的物理形态，就是一个文件夹。结构非常简单：

my-skill/
├── SKILL.md        ← 必须有，核心说明文件
├── scripts/        ← 可选，放可执行脚本
├── references/     ← 可选，放参考文档
└── assets/         ← 可选，放模板文件

在终端里两行命令搞定：

mkdir -p my-skill/{scripts,references,assets}
touch my-skill/SKILL.md

文件夹名字就是 Skill 的名字。用小写加连字符，比如 weekly-report、data-to-docx。

---

第三步：写 SKILL.md（最核心的一步）

这个文件分两部分：顶部 YAML 和 正文说明。

顶部 YAML 决定 Claude 会不会用这个 Skill。正文说明决定 Claude 用得好不好。

格式如下：

---
name: weekly-report
description: |
  把工作内容整理成 Word 格式周报。
  当用户说「写周报」「生成周报」「weekly report」
  「整理本周」时必须使用本 Skill。
  哪怕用户没有明确说"周报"，只要在整理
  本周工作总结，也要触发。
---

# 周报生成 Skill

## 步骤
1. 先读取 /mnt/skills/public/docx/SKILL.md
2. 询问用户本周的工作内容（如果没提供）
3. 按模板格式整理内容
4. 生成 .docx 文件
5. 用 present_files 工具呈现给用户

## 模板格式
- 本周完成事项
- 遇到的问题与解决方案
- 下周计划

description 是整个 Skill 的触发器，是最容易被忽视、也最容易搞砸的地方。

大多数人写 description 只写"这是什么"——"生成周报的工具"。这种写法触发率极低。

正确的写法是：把用户可能说的各种话都写进去，明确告诉 Claude 什么时候必须用这个 Skill。要稍微"强硬"一点——Claude 有一个天然倾向，就是能自己处理的事情就不调用 Skill。你必须在 description 里打破这个倾向。

---

第四步：按需加辅助资源

SKILL.md 建议控制在 500 行以内。说明太长，把细节拆出来放到 references/ 文件夹，在 SKILL.md 里写清楚"需要时去读 references/xxx.md"就好。

三类资源各司其职：

• scripts/：放 Python 或 Shell 脚本，处理格式转换、数据处理这类机械性任务
• references/：放参考文档，比如格式规范、行业术语表、品牌语气指南
• assets/：放模板文件、字体、图标，供脚本直接调用

在 SKILL.md 里引用资源的写法：

## 格式规范
详见 references/style-guide.md，
处理格式时请先读取该文件。

---

第五步：用评估器打分，量化迭代

这一步是大多数人跳过的步骤，也是 Skill 质量差距真正拉开的地方。

靠感觉测试是没用的。你觉得"好像还行"，不代表 Skill 真的在稳定工作。正确的做法是建一套评估体系，让数据说话。

第一步：写测试用例

在 Skill 文件夹里建一个 evals/evals.json，写 5 到 10 个真实的测试场景：

{
  "skill_name": "weekly-report",
  "evals": [
    {
      "id": 1,
      "prompt": "帮我写本周周报，这周完成了用户模块开发",
      "expected_output": "包含本周事项、问题、下周计划的 Word 文件"
    },
    {
      "id": 2,
      "prompt": "generate my weekly summary",
      "expected_output": "英文触发词也能正确调用 Skill"
    }
  ]
}

测试用例要覆盖边界情况：用户说话方式不标准、输入内容残缺、换一种语言触发——这些才是真正暴露问题的场景。

第二步：写断言（Assertions）

每个测试用例对应一组可量化的判断标准，叫做断言。比如：

• 输出文件是否为 .docx 格式？
• 文件里是否包含"下周计划"这个章节？
• 触发词变换后，Skill 是否依然被调用？

断言的原则是：客观可验证，不依赖主观感受。 能用脚本检查的，就用脚本检查，比人眼看更快更准。

第三步：跑评估，生成 benchmark

有了测试用例和断言，跑两组对比：一组用 Skill，一组不用 Skill（或者用旧版 Skill）。然后聚合结果：

python -m scripts.aggregate_benchmark workspace/iteration-1 --skill-name weekly-report

生成 benchmark.json，里面有每个测试用例的通过率、耗时、token 消耗，以及有 Skill 和没有 Skill 之间的差值。

这个差值，就是你这个 Skill 的实际价值。

第四步：开评估查看器，人工复核

跑完评估之后，用可视化查看器逐条看输出：

python eval-viewer/generate_review.py workspace/iteration-1 \
  --skill-name "weekly-report" \
  --benchmark workspace/iteration-1/benchmark.json

浏览器会打开一个界面。左边是每个测试用例的输入和输出，右边是断言的通过/失败明细。你可以对每个结果留下文字反馈，最后点"Submit All Reviews"保存。

先看评估结果，再改 Skill。 不要凭感觉改，要根据数据改。哪条断言失败了，去 SKILL.md 里针对性地修那一段。

第五步：触发词优化循环

description 写得好不好，直接影响触发率。这也是最容易被忽视的一步——大多数人写完 description 就不管了，但这恰恰是 Skill 效果差的最大原因。

来看一个真实的对比。同一个周报 Skill，两版 description：

优化前：

生成周报的工具，帮助用户整理本周工作内容，输出 Word 文件。

优化后：

把工作内容整理成 Word 格式周报。
当用户说「写周报」「生成周报」「weekly report」
「整理本周」「本周总结」「工作汇报」时必须使用本 Skill。
哪怕用户没有明确说"周报"，只要在整理
本周工作总结，也要触发。
不要因为任务简单就跳过本 Skill 自行处理。

跑触发率评估，结果如下：

|测试场景|优化前触发|优化后触发|
|---|---|---|
|"帮我写周报"|✅|✅|
|"generate my weekly summary"|❌|✅|
|"整理一下这周干了啥"|❌|✅|
|"本周工作汇报"|❌|✅|
|"weekly report 要交了"|❌|✅|

触发率：40% → 100%。

差距来自哪里？优化前的 description 只说了"这个 Skill 是什么"，没有告诉 Claude "什么时候必须用它"。Claude 有一个天然倾向——能自己处理的任务就不调用 Skill。你必须在 description 里主动打破这个倾向。

跑优化循环是把这个过程自动化：

python -m scripts.run_loop \
  --eval-set evals/trigger-eval.json \
  --skill-path my-skill/ \
  --max-iterations 5

它自动把测试集拆成训练集和测试集，跑多轮评估，每轮根据失败案例提出 description 的改写方案，最终返回得分最高的版本。直接替换 SKILL.md 顶部的 YAML 就好。

description 优化完，再看一次 benchmark，前后对比的样子大概是这样：

iteration-1 benchmark（优化前）
─────────────────────────────────────────
断言通过率（with skill）:   58%
断言通过率（without skill）: 12%
提升差值:                   +46%

失败断言明细：
  ✅ 输出文件为 .docx 格式
  ✅ 包含"本周完成事项"章节
  ❌ 包含"下周计划"章节        ← 模板缺失
  ❌ 英文触发词能正确调用       ← description 覆盖不足
  ❌ 输入残缺时主动询问用户     ← 步骤说明未覆盖

iteration-2 benchmark（优化后）
─────────────────────────────────────────
断言通过率（with skill）:   100%
断言通过率（without skill）: 12%
提升差值:                   +88%

失败断言明细：
  ✅ 输出文件为 .docx 格式
  ✅ 包含"本周完成事项"章节
  ✅ 包含"下周计划"章节
  ✅ 英文触发词能正确调用
  ✅ 输入残缺时主动询问用户

这张表说明了一件事：没有 Skill 的 Claude，通过率永远是 12%。有了经过评估迭代的 Skill，通过率是 100%。这个差距，就是你搭 Skill 的价值所在。

---

整个评估流程加起来：写用例 → 写断言 → 跑 benchmark → 看 viewer → 改 Skill → 再跑。不需要每次都跑完整循环，第一次认真跑一遍，后续迭代只需要验证改动点就够了。

---

第六步：打包

测试满意之后，一行命令打包：

python -m scripts.package_skill my-skill/

生成 .skill 文件，可以直接分享，也可以自己存档备用。

---

#最后说一句

这六步写出来不复杂，但真正做一遍，你会在某个地方卡住。

可能是 description 写了半天触发率还是上不去。可能是 benchmark 跑出来数据难看，但不知道该改哪里。可能是第一步的三个问题想了很久，发现自己根本没想清楚要解决什么问题。

这很正常。

Skill 不是教程看完就会的东西。它是一个需要迭代的工程，第一次做会有很多地方不顺。重要的是把它做出来，跑起来，用真实的任务去测它。

哈佛商学院的研究说，真正用好 AI 的人完成任务比别人快 25%，质量高 40%。PwC 的数据说，掌握 AI 技能的人薪资溢价 56%。

这些数字背后的人，不是比你更聪明，是比你早一步把流程跑通了。

去试。卡住了再说。

---

🔗 Skill 工程系列：
📝 认知基础：[[../../公众号/文章草稿/小白用好baoyu-skills深度教程|baoyu-skills深度教程]]（从"聊天心态"到"工程思维"）
🏗️ 工程哲学：[[../../已发布/20260405-Harness Engineering：真正拉开差距的，不是功能数量，而是工作秩序|Harness Engineering]]（本文的工程化实践）