参考资料

• Agent Skills 规范
• MCP 规范

Skill（07） - 模板、参考资料与资源文件

读完后，你应能完成以下任务：

• 绘制“Skill（07） - 模板、参考资料与资源文件 / 三类最常用的资源文件”的关键对象与数据流，解释“目录名是约定，不是强制。”，并用源码位置、日志或 Trace 标注证据。
• 为“Skill（07） - 模板、参考资料与资源文件 / 怎么「正确引用」——这是关键”设计正常与异常输入，验证“资源文件建好了，必须在 SKILL.md 正文里点名，否则 Claude 根本不会去看（回顾第 03 章「没被点名 = 不存在」）。”，输出首个偏差位置与回归测试结果。
• 实现“Skill（07） - 模板、参考资料与资源文件 / 模板怎么写：用占位符”的最小代码或配置，检验“占位符风格用 {{xxx}}、[xxx]、 都行，统一一种即可，方便 Claude 识别和你自己检查。”，输出命令、结果与 Diff，并说明不适用边界。

本章目标：动手实践第 3 层——学会用 reference/ 放参考资料、templates/ 放模板，并在正文里正确引用它们。学完你会得到一个「带模板」的完整技能。

一、三类最常用的资源文件

第 06 章讲了「细节外置到第 3 层」，那到底外置成什么？实践中最常用三类：

类型	放哪	装什么	典型用途
参考资料	reference/	又长又偶尔查的文档	API 文档、规范手册、错误码表
模板	templates/	现成的样板文件	报告模板、邮件模板、配置样板
清单	reference/ 或正文	检查项列表	审查 checklist、上线清单

目录名是约定，不是强制。但用 reference/、templates/ 这种通用名，团队一看就懂。

二、怎么「正确引用」——这是关键

资源文件建好了，必须在 SKILL.md 正文里点名，否则 Claude 根本不会去看（回顾第 03 章「没被点名 = 不存在」）。引用就是写清相对路径 + 什么时候用它：

## 流程
1. 套用 `templates/report.md` 模板组织内容。
2. 排版细节见 `reference/style-guide.md`，需要时查阅。
3. 提交前对照 `reference/checklist.md` 逐项自查。

三个要点：

• 路径相对于技能根目录：templates/report.md 指的是技能文件夹下的 templates/report.md。
• 说清「何时用」：不只写文件名，还要告诉 Claude 在流程的哪一步、为什么要打开它。
• 路径必须真实存在：写了 reference/api.md，文件就得真在那，否则引用失效。

三、模板怎么写：用占位符

模板的精髓是占位符——预留好「待填的空」，让 Claude 复制后替换：

# {{title}}

**日期**：{{date}}

## 概述
{{summary}}

正文里配一句指引，明确「占位符要填满」：

套用 templates/report.md，把所有 {{...}} 占位符替换为实际内容，不要残留。

占位符风格用 {{xxx}}、[xxx]、<xxx> 都行，统一一种即可，方便 Claude 识别和你自己检查。

四、清单（checklist）：让产出不漏项

清单是性价比极高的资源。它把「专家脑子里的检查项」固化下来，确保每次都不漏。比如一个代码审查清单：

# 代码审查清单
- [ ] 是否有 SQL 注入风险（拼接 SQL）？
- [ ] 密钥/密码是否硬编码？
- [ ] 异常是否被吞掉（空 catch）？
- [ ] 边界条件（空值、0、超长输入）是否处理？
- [ ] 是否有对应的测试？

正文里让 Claude「逐项对照」：

审查时，逐条对照 reference/checklist.md，每一项给出「通过 / 有问题 / 不适用」。

清单短的话直接写进正文也行；项目多、会复用，就独立成文件。

五、完整示例：一个「带模板 + 清单」的周报技能

weekly-report/
├── SKILL.md
├── templates/
│   └── report.md           # 周报模板
└── reference/
    └── checklist.md        # 周报自查清单

SKILL.md 正文（节选）：

## 流程
1. 收集用户本周的工作内容。
2. 套用 templates/report.md，填满所有 {{...}} 占位符。
3. 完成后对照 reference/checklist.md 自查，确认没漏项。

这样，技能本体（正文）依旧很薄，模板和清单都在第 3 层按需加载。Demo 里有这个技能的完整可用版本。

六、常见错误

• ❌ 建了资源文件，正文却没引用：最高频的错。文件成了摆设，Claude 永远看不到。
• ❌ 引用路径写错：正文写 templates/report.md，文件实际在 template/report.md（少了 s）。
• ❌ 模板占位符风格混乱：一会儿 {{x}} 一会儿 [x]，Claude 和你都容易看花。
• ❌ 只丢文件不说「何时用」：正文只写「见 templates/report.md」，没说在哪步、干嘛用，Claude 可能用不对时机。
• ❌ 把该常驻的核心步骤也外置了：每次都要执行的主流程应留在正文，别为了「外置」而外置（回顾第 06 章决策表）。

七、最佳实践

• 先在正文写好「指路」，再去建文件：想清楚「这一步要用什么资源」，引用和文件一起落地。
• 模板用统一占位符 + 明确「填满别残留」的指令。
• 清单用 - [ ] 复选框格式，让 Claude 逐项核对、产出整齐。
• 引用时带上「何时、为何」：不只给路径，还给使用时机。
• 改完用 Demo 套路验证：装上、触发、看它有没有真的去读那个资源文件（可在资源文件里埋暗号）。

八、动手实践：07 章 Demo · 带模板 + 清单的周报技能

一个完整、可直接用的技能，演示「正文指路 → 模板套用 → 清单自查」的完整配合。

8.1 结构

weekly-report/
├── SKILL.md                 # 正文：流程里点名了模板和清单
├── templates/
│   └── report.md            # 周报模板（带 {{占位符}}）
└── reference/
    └── checklist.md         # 自查清单（复选框格式）

8.2 装上试试

cp -r weekly-report ~/.claude/skills/

开新会话，正常说话：

帮我整理一份本周周报：周一修了登录 bug，周三上线了支付功能，搜索还在做大概一半，下周要做对账。

技能会被触发，Claude 会套用模板、填占位符、再按清单自查。

8.3 看点

1. 打开 SKILL.md，注意流程第 2、3 步分别点名了 templates/report.md 和 reference/checklist.md——正是这两句「指路」让第 3 层文件能被加载。
2. 注意模板里的 {{...}} 占位符，和正文里「替换占位符，不要残留」的指令配合。
3. 注意清单用 - [ ] 格式，让 Claude 能逐项核对。

8.4 验证「引用」的作用（推荐做一次）

把 SKILL.md 里「对照 reference/checklist.md 自查」这句删掉，再生成一次周报。你会发现 Claude 不再做清单自查了——因为清单没被点名，等于不存在。改回来，对比效果。这能让你彻底记住第 03/07 章的核心：没被正文引用的资源，不会被加载。

8.5 你会收获什么

• 一个能直接用的真实技能。
• 亲手验证「引用关系」如何决定资源是否生效。

8.6 配套实践材料

以下材料已并入正文，便于阅读时直接对照和练习。

weekly-report/reference/checklist.md

# 周报自查清单

生成周报后，逐项对照检查：

- [ ] 所有 {{...}} 占位符都替换了，没有残留
- [ ] 「本周完成」每条都有明确结果，不是「做了 xx」这种没下文的描述
- [ ] 「进行中」标注了进度
- [ ] 「问题与求助」如实写，没有就写「无」
- [ ] 「下周计划」具体可执行，不是空话
- [ ] 全文没有编造的数据或进展

weekly-report/SKILL.md

---
name: weekly-report
description: 当用户需要把本周工作内容整理成一份结构化周报时使用。适用于汇总进展、整理成可提交的周报格式的场景。
---

# 周报生成

帮用户把零散的本周工作整理成一份规范周报。

## 流程
1. 收集用户本周的工作内容（做了什么、进展如何、遇到什么问题）。
2. 套用 `templates/report.md` 模板组织内容，把所有 {{...}} 占位符替换为实际内容，不要残留。
3. 完成后，逐项对照 `reference/checklist.md` 自查，确认没有漏项。

## 注意
- 内容忠于用户提供的事实，不编造进展或数据。
- 语言简洁，每条进展一句话说清「做了什么 + 结果」。

weekly-report/templates/report.md

# {{name}} 的周报

**周期**：{{start_date}} ~ {{end_date}}

## 一、本周完成
- {{done_1}}
- {{done_2}}

## 二、进行中
- {{doing_1}}（进度 {{progress_1}}）

## 三、问题与求助
- {{blocker_1}}

## 四、下周计划
- {{plan_1}}
- {{plan_2}}

九、总结

• 怎么「正确引用」——这是关键：资源文件建好了，必须在 SKILL.md 正文里点名，否则 Claude 根本不会去看（回顾第 03 章「没被点名 = 不存在」）。
• 最佳实践：先在正文写好「指路」，再去建文件：想清楚「这一步要用什么资源」，引用和文件一起落地。
• 工程边界：路径必须真实存在：写了 reference/api.md，文件就得真在那，否则引用失效。
• 验证方式：改完用 Demo 套路验证：装上、触发、看它有没有真的去读那个资源文件（可在资源文件里埋暗号）。