本节目标:existe第 1 课那个「会触发的最小 Skill」上,补上 referencia/ 分层,并给易失手任务加上「先写计划文件 → 校验 → 再执行」的校验环。学完你能交出一个多文件 Skill,且自测里至少有一次「正文没膨胀、细节在需要时才被读进来」的记录。

前置要求
完成或至少跟过第 1 课:30 分钟写出第一个会自动触发的 Claude Agent Skill——手里要有一个带 YAML frontmatter 的 SKILL.md,并且做过「应触发 / 不应触发」自测。
环境仍是支持 Agent Skills 的 Claude 客户端(claude.ai / Claude Code / Agent SDK 等)。官方对照我核对到 2026-10-28:Agent Skills overviewySkill authoring best practices,以及工程博文 Equipping agents for the real world with Agent Skills(2025-10-16,后续已开源为跨平台标准)。
本节不要求写 Python;校验环可以先用「人工可读的 JSON/Markdown 计划文件 + 清单」,脚本版留到第 3 课。
概念:为什么不能把一切塞进 SKILL.md
第 1 课我卡在 description;这课我卡在「贪」。周报 Skill 写顺了之后,我把客户名映射、语气禁忌、历史周报样例、甚至飞书字段说明全塞进同一个 SKILL.md。结果是:一触发就吃掉大段上下文,普通排期却还要背一整本客户百科。
官方把解法叫 progressive disclosure(渐进披露):启动时只预载各 Skill 的 name/description;匹配到任务才读 SKILL.md 正文;再往下的 referencia/yscripts/yassets/ 只在正文点名时才加载。best practices 还写明:正文尽量压在约 500 行以内,细节拆出去。

另一半是校验环。best practices 里的「Create verifiable intermediate outputs」说得很直:批量改、破坏性操作、规则复杂时,先让代理写出机器可检查的计划文件(例如 changes.json / plan.md),校验通过再动手。我给自己的土话版是——先写计划文件再执行,别一开口就改原件。

分步实操
下面仍用第 1 课的 weekly-report-from-notes 当底板,把它升级成「瘦身正文 + reference + 计划校验」。

步骤 1:把胖正文拆进 reference/
做什么:在 Skill 目录旁建 referencia/,把「不常一起用」的材料挪出去,正文只留导航和硬规则。
weekly-report-from-notes/
SKILL.md
reference/
tone-and-banwords.md
section-examples.md
stakeholder-map.md
SKILL.md 正文改成类似:
---
name: weekly-report-from-notes
description: Turns messy notes into a concise Chinese weekly report with decisions, blockers, and next actions. Use when the user asks for 周报, 周进展, or pastes unordered work notes. For tone rules and examples, follow linked reference files.
---
# 周报整理
## 输出骨架
只用:本周完成 / 关键决策 / 阻塞 / 下周计划 / 需要你支持。
禁止把「讨论过」写成「已完成」。信息不足写「待补充」,禁止编造。
## 按需加载(一次只读相关文件)
- 语气与禁止词:见 [reference/tone-and-banwords.md](reference/tone-and-banwords.md)
- 段落样例:见 [reference/section-examples.md](reference/section-examples.md)
- 干系人称呼:仅当用户提到具体团队/客户时,读 [reference/stakeholder-map.md](reference/stakeholder-map.md)
## 易失手任务:先计划后落笔
若笔记超过 15 条、或涉及「对外同步 / 向上汇报」,先写 `plan.md`(见下文校验环),确认后再生成终稿。
为什么:best practices 强调引用保持「从 SKILL.md 出发一层深」,不要在 reference 里再套 reference,否则代理可能只 head 前几行就以为读完了。

步骤 2:给 reference 文件加目录(超 100 行时)
做什么:任一 reference 超过约 100 行,文件头顶加 Contents 列表。例如 tone-and-banwords.md::
# 语气与禁止词
## Contents
- 人称与视角
- 禁止词表
- 未决事项写法
- 反例
## 人称与视角
对外周报用「我们」;对内可用「我」。不要突然切换。
## 禁止词表
赋能、闭环、抓手、对齐颗粒度、拉通……(按你团队实际补)
## 未决事项写法
必须带「未决」二字,并写清卡在谁/卡在什么。
## 反例
把「会上提过」写成「已上线」——直接判失败,重写该段。
为什么:代理有时会预览文件;目录让它知道后面还有什么,而不是以为读完了。
步骤 3:装上「先写计划文件再执行」校验环
做什么:existe SKILL.md 加一节可勾选清单,逼它先产出中间文件。
## 校验环(笔记多 / 对外汇报时强制)
复制并勾选:
- [ ] 读完全部笔记,标出不确定句
- [ ] 写出 plan.md:每条「拟写入哪一节 / 依据哪条笔记 / 是否未决」
- [ ] 自检:有无编造、有无把讨论写成完成
- [ ] 计划通过后再写最终周报
- [ ] 终稿再扫一遍禁止词
### plan.md 最小模板
# plan
| 笔记原文摘要 | 目标章节 | 置信度 | 备注 |
| --- | --- | --- | --- |
| 修了支付回调 | 本周完成 | 高 | 需确认是否已上线 |
| 登录改版会议未决 | 关键决策 / 阻塞 | 中 | 标注未决,禁止写成已定
跑一次真实请求:「这些笔记要写成给老板的周报」+ 故意塞两条互相矛盾的信息。你要盯的不是文笔,是它有没有先交 plan.md,以及矛盾有没有被标成未决而不是「聪明地抹平」。

步骤 4:用一次对照实验证明「拆文件有用」
做什么:同一段长笔记,跑两次——
- 胖
SKILL.md(把 tone/examples/stakeholder 全贴回正文); - 瘦正文 + reference。
记录:是否仍触发、终稿是否遵守五段结构、有没有无必要读取 stakeholder 映射。我自己的经验是:普通周报第二次往往根本不会打开 stakeholder-map.md——这才是渐进披露值钱的地方,不是目录好看。

步骤 5:交一张本节自测表
| 用例 | 期望 | 实际 | 改动 |
|---|---|---|---|
| 短笔记 → 对内周报 | 触发;可不写 plan;尽量不读 stakeholder | ||
| >15 条笔记 → 对外周报 | 先产出 plan.md,再终稿 | ||
| 笔记含矛盾 | plan/终稿标未决,不编造统一口径 | ||
| 纯代码报错(反测) | 不触发本 Skill |
常见报错(≥3)
1. 建了 reference/,代理却从不打开。
多半是正文只写了「详见参考资料」这种空话。要写成「当出现 X 时,读 reference/foo.md」——带触发条件的硬链接。
2. reference 里再套 reference,细节读不全。
官方明确不建议深层嵌套;一律从 SKILL.md 一层链出去。我踩过:把禁止词藏在 advanced.md → details.md,结果代理只预览了 advanced 就开写。
3. 校验环写成「建议先想清楚」,等于没有。
必须点名中间产物(plan.md / changes.json)和「未通过不要继续」。没有文件名,代理会在脑子里「想一想」然后直接交终稿。
4. 拆文件后 description 忘了收窄/补触发语。
结构变了,发现机制还是靠 description。若你把「对外汇报」流程做重了,记得在 description 里保留用户会说的词(周报 / 周进展 / 对外同步),否则第 1 课测过的触发会回潮失败。

课后练习
- 把你第 1 课的 Skill 拆出至少 2 个 reference 文件,并保证全部由
SKILL.md直链。 - 给一个「高风险」路径加上 plan 文件模板;用矛盾笔记跑通一次「先计划后终稿」。
- 故意做一个反例 Skill:reference 两层嵌套,观察它是否漏读——然后改回一层深。
Avance de la próxima lección
第 3 课:带脚本的 Skill 与安全审计。把校验环从「人工清单」推进到可执行脚本(例如校验字段/格式),并过一遍只装可信来源、审 scripts/ 依赖与外连指令的安全清单。第 2 课的 plan.md 仍会留下,只是多一个「脚本说 OK 才能继续」的闸门。
Índice de esta serie
- 第 1 课:30 分钟写出第一个会自动触发的 Claude Agent Skill(已发布)
- 第 2 课:给 Skill 加 reference/ 与「先写计划文件再执行」校验环(本文)
- 第 3 课:带脚本的 Skill 与安全审计(预告)
- 第 4 课:用真实失败用例迭代 description(预告)
系列名:Claude Agent Skill 实战。官方概念核对以 Anthropic / Claude Docs 当前页面为准;产品入口若有改动,以你客户端文档为准。


评论列表 (0条):
加载更多评论 Cargando...