自己动手编写 skills：让你的知识可以生根发芽～

houwenjin

667人浏览 · 2026-08-18 00:23:57

houwenjin · 2026-08-18 00:23:57 发布

每周五都要交一遍的那笔「税」

每周五下午，我都要把同一件事重新做一遍：跟 agent 描述「我的周报长这样」。

结构是固定的四块、语气要简洁务实、篇幅不超过一屏、数字必须具体——这些我讲过不下二十遍。但每次新开一个会话，它统统不记得。今天我从零讲一遍，下周它又忘光，我再讲一遍。

这就是我用 agent 以来交得最冤的一笔税：每次新会话，我的偏好、写作风格、领域词汇、质量标准全被清零。我明明已经教会过它很多次，它却每次都像第一天上班。

后来我搞懂了 skills 这回事。它把「我的周报长这样」写成一次、存起来，以后 agent 每次都会自动用。写一次，用一年，还能在我的新经验里长出新的——就像种子落地生根，自己发芽。

skills再配上/loop，就能把一些重复的事情自动化的给处理掉。

2. skills 是什么，agent 怎么用它

2.1 一个 skill 的解剖：经验包，不是长 prompt

skill 在 Claude Code 里就是一个文件夹，放在 .claude/skills/ 下。文件夹里最关键的是一个 SKILL.md 文件，其余都是可选配件：

SKILL.md 是唯一必须存在的文件，由两部分组成：开头 --- 包裹的 frontmatter（YAML），和正文。frontmatter 里最核心的两个字段是 name 和 description，后面会细讲。

skill 是「可复用经验包」，不是长 prompt。 长 prompt 是把一段话每次重新粘进去；skill 是把一段流程、一套判断标准、一组检查项打包成文件，让 agent 在需要时自己取用。两者最大的区别是「反复照做」——只有你反复在做、且每次都希望结果稳定的那件事，才值得写成 skill。

打个比方：MCP 是厨房——它提供锅碗瓢盆（工具）；skills 是菜谱——它告诉 agent 这道菜按什么步骤做、放多少盐。工具可以借，菜谱是你自己的手艺。

2.2 三层渐进披露：frontmatter 常驻，正文按需

skill 最聪明的设计是「渐进披露」（progressive disclosure）。它把内容切成三层，按需加载，不把整个 skill 一次塞进上下文：

逐层拆开看：

第一层，frontmatter 常驻。每个会话开始，Claude Code 只把每个 skill 的 name 和 description 放进上下文，成本约百级 tokens。这层信息只够 Claude 判断「眼前这个请求要不要用这个 skill」。
第二层，正文按需。description 命中当前任务，才把 SKILL.md 正文整段加载进来。经验法则是正文控制在 500 行以内，超过的细节往下层放。
第三层，references 深潜。正文里可以写「对照 references/last-week-example.md 的风格」，Claude 需要时才去读那个文件。

我盯着这个机制看的时候，想起我之前在《[自己动手写Agent Harness【agent tools】：给它装手和眼睛——工具注册与执行流水线(https://blog.csdn.net/houwenjin/article/details/163831930)》那篇里实现过一个技能注册表：目录里只存 name+description 当索引，正文用 getPrompt() 按需取。当时我是在造一个「壳」，现在我是往这个壳里放东西——壳怎么造的，决定了我能往里面放什么。 这两件事是一体两面：理解了「描述常驻、正文懒加载」，你写 skill 时就知道该把什么放 frontmatter、什么放正文、什么放 references。

两个实用提醒。一是别装太多 skill，每个常驻约百级 tokens，装几十个累积起来也会占上下文预算（大致是上下文的 2% 量级），多了用 /context 看有没有被排除的警告。二是这条渐进披露原则是跨工具通用的——Agent Skills 是开放标准，.claude/skills/ 里写好的 skill，Codex 等同类工具也能识别，换个工具你的经验还在。

2.3 三种形态：干活、当背景知识、引导创建

不是所有 skill 都是拿来「被调用干活」的。按用途，我把它分成三种：

任务 skill（工作流）。这是最常见的，像菜谱一样走完一段流程。周报 skill 就是这个类型。默认由模型自动触发。
背景知识 skill（user-invocable: false）。不是流程，是一块常备知识，比如团队编码规范、某套 API 的用法。把 user-invocable: false 写进 frontmatter，它就不出现在 / 命令菜单里，只在 agent 需要时当背景知识加载。
引导式创建工具。skill 还可以是「用来造 skill」的元技能，官方仓库里的 skill-creator 就是典型，下面 4.1 节细讲。

这里牵扯到 frontmatter 里两个关键的调用开关，很多人写 skill 时从来没注意过：

disable-model-invocation: true：关掉模型自动触发。写 true 后，只有用户显式点名调用时 skill 才运行。适合有副作用、怕误触的操作（比如会对外发送的命令）。
user-invocable: false：把 skill 从 / 命令菜单里藏起来。适合只想让模型自动用的背景知识。

一句话记：disable-model-invocation 管「模型能不能自动调」，user-invocable 管「用户能不能显式调」。两者一组合，就得到四种调用权限。这不只是开关，是你对「这个 skill 该不该由模型自作主张」的表态。

3. 你的经验怎么变成 skills

3.1 判断标准：反复照做，才值得写

回到开头那笔税。不是所有事都值得写成 skill，判断标准其实就三条：

反复出现：你一个月至少做几次。只做过一次、以后大概率不再做的事，别写。
可复用：同样的套路能套在不同场景。比如周报、会议纪要、项目复盘，结构差不多，一次写清处处可用。
有固定套路：你心里已经有一套稳定的做法，不是每次临场发挥。

反过来，一次性的事——「帮我算一下这个报销单」「把这个表格转成 PDF」——交给 agent 顺手做掉就行，写成 skill 是过度投资。

最直接的挖金矿方式：你反复喂给 agent 的那段上下文，就是最值得固化的经验。 如果你发现自己第三次对 agent 说「按我们团队的格式写会议纪要」「记得先跑测试再提交」，别光顾着烦——这就是 skill 的种子。我那个周报 skill，就是从「每周五重新描述一遍我的周报」这个重复动作里长出来的。

3.2 从哪挖：四问法

确定「这件事值得写」之后，怎么把模糊的经验抽成 skill？我习惯用四个问题过一遍，这也是 Anthropic 官方指南推荐的规划方式：

要达成什么？ 一句话说清这个 skill 的产出。周报 skill 的答案是「产出一篇符合作者个人风格的周报」。
需要什么多步工作流？ 把这件事拆成步骤。写周报 = 收集事项 → 确认范围 → 按结构组织 → 套风格 → 自查。
需要哪些工具？ 如果流程里要调工具（跑脚本、读文件、查数据），在 skill 里点出来。周报不需要工具，但如果你要 skill 收集本周的 git 提交，就得让它跑命令。
哪些领域知识要嵌进去？ 这个 skill 必须知道哪些「常识」？周报 skill 要嵌入作者的结构、语气、篇幅规范。

四问过后，你就得到一份用例，也就是 skill 的「验收标准」。我习惯写成一句话：触发条件（Trigger）+ 步骤（Steps）+ 期望结果（Result）。 比如周报 skill 的用例是：用户说「写周报」→ 按五步走 → 输出一屏内、四块结构、作者语气的周报。后面写正文、做验证，都围绕这一个用例展开，不跑偏。

3.3 一张转化清单：Anthropic 九类 + 你的扩展

Anthropic 公开过内部几百个 skill 的分类框架，一共九类，覆盖从开发到运维的全流程。我把它抄下来，给每类配一句「长什么样」：

类别	长什么样	官方例子
库 / API 参考	帮你正确用某个库、避开它的坑	billing-lib（计费库的坑）
产品验证	跑一遍流程证明东西能用	signup-flow-driver（无头浏览器跑注册全流程）
数据获取与分析	连上数据系统拉指标	funnel-query（从数据平台拉漏斗数据）
业务流程自动化	重复的例会活一键生成	standup-post（站会发言）
脚手架 / 模板	生成特定技术栈的样板	new-workflow（内部组件结构）
代码质量 / 评审	强制质量标准、换双眼睛挑毛病	adversarial-review（用全新子代理批判式评审）
CI/CD 与部署	盯流程、拉取、推送、部署	babysit-pr（盯 PR、重试 flaky CI、处理冲突）
运维手册	多工具排障流程、产出结构化报告	*-debugging 系列
基础设施运维	日常维护与清理	*-orphans（清理孤儿资源）

这份清单有个特点：九类里绝大多数是开发场景。但 skill 这个东西完全不限于写代码——你只要把「经验」换成你那一行的「经验」，处处能用。我给它加了三类扩展：

业务知识：你行业里那套判断标准、术语、禁区。比如「合规审核 skill：知道哪些条款必须人工签字、哪些可以自动化」。
办公流程：周报、会议纪要、项目复盘、出差报销。本文的案例就是这一类。
个人管理：你的阅读笔记整理法、复盘模板、知识管理习惯。

每次你写 skill 前，都值得拿这张扩展后的清单对照一遍：我这件事落在哪一格？大多数人的第一个 skill，都是从「业务流程自动化」和「办公流程」这两格里长出来的。

4. 动手编写 skills

两条路：让 agent 帮你建，或者自己动手。先介绍快的，再讲透自己写的每一步。

4.1 路径一：让 agent 帮你建

三条由浅入深的路，任选。

最省事的：一句话让当前 agent 生成骨架。 你直接在对话里说「帮我把『写周报』这个反复做的事做成一个 skill，先给我一个骨架」，当前这个 agent 就会按它知道的约定生成一个带 frontmatter 的 SKILL.md。生成之后你再往里填你的经验。骨架不一定完美，但能帮你跳过「从空白文件开始」的启动成本。我自己写第一个 skill 时就是这条路，把生成的骨架改成自己的结构，比凭空写快很多。

更规范的：用 skill-creator 元技能。 Anthropic 官方仓库里带了一个叫 skill-creator 的元技能——一个专门用来造 skill 的 skill。你给它一句描述「A skill that 帮我写周报」，它会引导你走完用例定义、frontmatter 生成、验证整个流程。官方指南的说法是，用它 15 到 30 分钟就能做出一个能用的 skill。适合你第一次写、想有人带路的时候。

要造「命令型」skill：用 command-creator 引导流程。 官方已经把手写 slash 命令并进了 skills 体系：.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都会生成一个 /deploy，效果一样。社区里的 command-creator 把「把一个命令固化成 skill」拆成了六步引导：

判断位置：这个 skill 放用户级（所有项目生效）还是项目级（仅当前项目，可进 Git 仓库）？项目级更推荐，能版本化管理。
选模式：是「命令技能」（用户显式调用、有副作用、要审批门控）还是「知识技能」（模型自动触发、无副作用）？
收参数：这个命令接不接受参数？参数是什么类型？不可逆操作前要不要停下来等审批？
生成指令：把命令拆成带编号的阶段，每个有副作用的阶段加「STOP and wait for user approval」这类护栏。
创建文件：写到 <项目>/.claude/skills/<名字>/SKILL.md，配套文件放旁边。
测试：跑一遍，确认触发和行为都符合预期。

这六步和「自己动手」要过的关口一模一样，只是有引导。下面我按自己动手的路，把每一步讲透。

4.2 路径二：自己动手——命名契约、description 公式、正文结构

自己写 skill，最怕的不是写不好，是写好了却加载不上。先讲最容易踩坑的命名契约。

命名契约（严格遵守，出错是静默的）。

文件名必须是全大写 SKILL.md。 写成 skill.md 或 Skill.md 会「静默失败」：文件在、目录在，但 skill 就是不加载。大小写敏感，还不报错——这是我见过最坑的一条。
目录名必须 kebab-case：全小写字母/数字，段间用单个连字符，比如 weekly-report、my-skill-2。不能有空格、下划线、双连字符、大写。
frontmatter 的 name 必须和目录名完全一致。目录叫 weekly-report，name 就必须是 weekly-report。不一致，skill 无法被正确识别。
目录里不放 README.md（会有约定冲突）。name 最长 64 字符，不能用 claude、anthropic 这两个保留字。
frontmatter 里禁止出现 XML 尖括号（小于号、大于号字符）。 这个我单独拎出来讲，因为读者照抄最容易带进坑。

那个尖括号的坑，是我写本文那个周报 demo 时真实踩到的。一开始我想在 frontmatter 的教学注释里写「不要写 <代码块> 这样的标签」，结果 skill 直接解析失败。Claude Code 解析 frontmatter 时对尖括号很敏感，哪怕是写在 # 注释里也不行。

最后我只能用文字描述：「禁止出现 XML 尖括号（即小于号与大于号字符）」——你能看到，连我自己写的这行注释里都没有一个真的尖括号。这个教训我写进了 demo 的注释里，提醒读者别踩。

description 公式（激活开关）。

skill 的正文写得再好，description 没写对也等于没写——我要立第二个判断：description 是 skill 的激活开关，没写对等于白写。 它太重要了，单独拆开讲。

Claude 判断「要不要调用这个 skill」的唯一依据，就是常驻上下文里那行 description。而模型天生有「欠触发」倾向——宁可不用，也不乱用。所以 description 不能写成说明书，要写成搜索引擎的查询词。我按这个公式写：

做什么 + 何时用 + 关键能力（触发词）

拿周报 skill 的 description 对照：

按作者个人风格写周报：先收集本周事项，再按固定结构组织、套用语气与篇幅规范，最后自查清单兜底。当用户要求写/发周报、总结本周工作、整理周五的工作汇报草稿时使用。触发词：写周报、本周总结、周报草稿、weekly report、summarize this week。

前半句是「做什么」，中间「当用户要求…时使用」是「何时用」，最后把用户可能的口语说法（中文加英文）都埋进去当触发词。有个硬性上限：description 最长 1024 字符，越精简越好。

「Helps with weekly reports」这种写法就是典型的白写。 它没给 Claude 任何触发依据——什么时候该用？用户说什么算「weekly reports」？模型拿不准，就不触发。把触发词写得越具体，自动触发越可靠。

正文结构（Instructions / Examples / Troubleshooting 三件套）。

正文是给 Claude 的操作说明（SOP），按需加载，所以可以写详细。推荐骨架：

# Skill Name（H1，与 name 一致）
## Instructions：把流程拆成编号步骤，每一步说清动作和产出。
## Examples：给「用户一句话 → 模型怎么处理」的示范，模型从例子里学得最快。
## Troubleshooting：写清「做不出来 / 风格不对 / 用户变卦」时怎么办，模型才不会硬编或中途放弃。

写正文有几个硬规矩：

SKILL.md 全文控制在 500 行以内，详细素材放 references，由正文按需指向。
护栏用 IMPORTANT: / NEVER: 显式标注，比普通描述更不容易被忽略。
写清「期望输出」和「错误处理」，这两块是 skill 稳定复现的关键。

参数与动态注入（skill 也能带参数、跑命令）。

skill 不是死文档，它支持两类动态内容：

$ARGUMENTS：用户调用时跟在 skill 名字后面的文本。比如用户说「写周报：上线了新功能，修复了 3 个 bug」，这些内容就出现在 $ARGUMENTS 里，正文可以直接引用。还有 $ARGUMENTS[0]（按位置取）、$0 这类简写，以及 arguments 里声明的具名参数。
!`cmd`：反引号里写 shell 命令，调用瞬间执行并把输出替换进去。比如正文里写「先读一下 !`git status --short` 再列本周改动」，Claude 看到的就是命令的真实输出。这让 skill 可以当迷你工作流用，进上下文之前先做预处理。

4.3 一个完整案例：周报 skill（weekly-report）

理论讲完，来看一个能照抄的完整案例。我做了一个周报 skill，办公场景、非开发，你在哪个行业都能照着改成自己的。

从痛点出发。 痛点就是开头那笔税：每周五重新描述一遍「我的周报长这样」。我用 3.2 的四问法定用例——Trigger：用户说「写周报」；Steps：收集 → 确认范围 → 按四块结构组织 → 套作者风格 → 自查；Result：一屏内、四块结构、作者语气的周报。

目录结构。 这是最终的文件布局：

examples/skill-demo/
├── PRACTICE.md
└── weekly-report/
    ├── README.md
    ├── SKILL.md
    ├── references/
    │   ├── last-week-example.md
    │   └── team-style.md
    └── scripts/
        └── validate.js

SKILL.md：skill 本体，frontmatter 加正文。
references/last-week-example.md：上周真实周报，Claude 拿不准风格时对照，体现渐进披露第三层。
references/team-style.md：团队提交规范（时间、渠道、保密项），低频细节放这层，换团队只换这个文件。
scripts/validate.js：校验脚本，写完 skill 跑一遍查合规。
README.md：安装说明。

SKILL.md 全文。 下面是完整文件，每个设计决策处我都用 HTML 注释写了「为什么这么写」——这些注释是给读者看的教学素材，真实安装时删掉即可：

---
# ====== frontmatter：skill 的「身份证」与「激活开关」 ======
# 说明：frontmatter 是 `---` 包裹的 YAML 块，Claude Code 会解析它来识别这个 skill。
# 这里用 `#` 写的都是 YAML 注释，只给读者看，不影响解析。真实 skill 最少只需要
# name + description 两个字段，下面逐个解释「为什么这么写」。
# 注意：frontmatter 里禁止出现 XML 尖括号（即小于号与大于号字符），Claude Code 会解析失败。

# name：skill 的唯一标识，必须用 kebab-case（全小写字母/数字，段间单连字符），
# 并且必须与所在目录名完全一致。两者不一致会导致 skill 无法被正确识别——
# 这是 Claude Code 的命名契约，也是最常见的「写好了但加载不上」的原因。
name: weekly-report

# description：skill 的「激活开关」，是 Claude 判断「这个请求要不要调用本 skill」的
# 唯一依据（frontmatter 常驻上下文，约百级 tokens）。所以它必须按公式写：
#   做什么 + 何时用 + 关键能力（触发词）
# 关键：Claude 有「欠触发」倾向，描述写得模糊（比如 "Helps with weekly reports"）
# 就很难被触发。要写成像搜索引擎的查询词——把用户可能的口语说法（中文 + 英文）
# 都埋进去，触发词越具体，自动触发越可靠。字数上限 1024 字符，越精简越好。
description: 按作者个人风格写周报：先收集本周事项，再按固定结构组织、套用语气与篇幅规范，最后自查清单兜底。当用户要求写/发周报、总结本周工作、整理周五的工作汇报草稿时使用。触发词：写周报、本周总结、周报草稿、weekly report、summarize this week。

# disable-model-invocation：默认不写（即保持启用模型自动触发）。
# 为什么保持默认：这个 skill 的价值恰恰是「用户一说写周报，Claude 自动就会」，
# 关掉自动触发就等于把 skill 废了一半。虽然周报最终要对外发送（有副作用），
# 但触发词足够具体（用户主动说「写周报」才触发），误触风险低。
# 若你担心误触导致误发，可改成 `disable-model-invocation: true`，
# 这样只有用户显式点名调用时本 skill 才运行——这是「要不要让模型自动触发」的取舍示范。
---

# Weekly Report

<!-- 正文第一行是 H1，写 skill 名字，与 frontmatter 的 name 保持一致。
     正文是给 Claude 的完整操作说明（SOP），按需加载——只有触发时才注入，不常驻上下文，
     所以正文可以写详细。经验法则：SKILL.md 全文 < 500 行，更细的参照物放 references/（渐进披露）。
     本 demo 的正文里嵌了大量教学注释（HTML 注释），是给读者看设计思路的；
     真正安装使用时，这些注释可以删掉以节省上下文。 -->

你是「把作者个人周报经验打包成可执行 SOP」的助手。作者每周五都要写周报，以下是作者多年积累的固定套路：结构、语气、篇幅、自查项。请严格按这套套路产出，不要自由发挥成「通用周报」。

## Instructions

<!-- 为什么分这五步：写周报这件「小事」在作者脑子里是自动完成的，但对模型是黑盒。
     把它显性化成 5 个可执行步骤，模型才能稳定复现作者的套路——每一步都是作者真实动作的还原，
     不是凭空设计的流程。 -->

1. **收集本周事项**
   先收集本周做过的事。如果用户说话时已经带了内容（比如「这周做了 X 和 Y」），直接用；
   否则按下面几个方向一次问完，别挤牙膏：
   - 本周完成了哪些关键任务 / 里程碑？
   - 有没有可量化的数据（数字、百分比、交付量）？
   - 有没有卡住的问题，或需要领导/同事支持的事？
   - 下周大致计划是什么？
   <!-- $ARGUMENTS 是 Claude Code 的参数注入机制：用户调用 skill 时跟在后面的文本。
        比如用户直接说「写周报：上线了新功能，修复了 3 个 bug」，这些内容就会出现在
        $ARGUMENTS 里，不用再逐条问。这是「参数与动态注入」的落地示例。 -->

2. **确认范围**
   向用户复述你要写哪些内容、覆盖哪一周（如「本周 = 8/11 ~ 8/15」），得到确认再动笔。
   <!-- 为什么要有这一步：周报有「对外发送」的副作用，写错范围（漏了一周、多写了一周）
        代价高。先确认范围 = 把控制权留在用户手里，也是「期望输出先行」的护栏。
        这是经验里「防止翻车」的那部分，同样值得写进 skill。 -->

3. **按固定结构组织**
   严格按下面 4 块组织，顺序不能乱。缺内容就如实省略或问用户，不要硬凑：
   1. **本周核心进展**：3-5 条，每条约 1-2 行，最重要的放最前。
   2. **成果亮点**：可量化的数据或里程碑（没有就整节省略，不要写「暂无亮点」）。
   3. **问题与需要支持**：卡点、风险、需要谁配合（没有就省略）。
   4. **下周计划**：2-4 条，动词开头（「完成」「推进」「上线」）。
   <!-- 为什么结构这么具体：这是「个人风格」的骨架部分。作者固定用 4 块、顺序固定，
        读者照抄后要把它换成自己的结构——skill 的正文就是「你的经验说明书」。 -->

4. **套用作者个人风格**
   语气与篇幅是「作者风格」的灵魂，必须严格遵守：
   - **语气**：简洁、务实、数据说话；第一人称「我」；不用形容词堆砌，不写「深化」「赋能」「抓手」等空词。
   - **篇幅**：全文不超过一屏（约 200-350 字），重点前置，能一句话说清的不写两句。
   - **句式**：短句为主，一条一行；数字要具体（「修复 3 个 bug」而不是「修复了一些 bug」）。
   <!-- 这就是文章标题说的「把个人风格教给 agent」：风格不是玄学，是可描述的语气规则 +
        篇幅约束 + 句式习惯。写清楚这些，模型才能模仿得像。 -->

5. **自查清单（落笔前逐项核对）**
   写完对照下面清单检查，任何一项不满足就改：
   - **结构**：是否正好 4 块、顺序是否正确？
   - **语气**：有没有空词 / 形容词堆砌？读起来像不像作者本人？
   - **篇幅**：是否超过一屏？重点是否前置？
   - **事实**：数字、人名、日期是否都来自用户，没有编造？
   - **敏感**：有没有把不该写进周报的内部信息（预算、薪资、抱怨）写进去？
   <!-- 为什么要有自查清单：skill 是「经验包」不是「长 prompt」，经验里最值钱的部分
        往往是「写完要检查什么」。清单是质量兜底，防止模型跑偏，也是风格稳定复现的关键——
        这正是「经验」和「流程」的区别。 -->

## Examples

<!-- 为什么要有 Examples：模型是从例子学习的，光讲步骤不够直观。
     给「用户一句话 → 模型怎么处理」的示范，等于给模型一根模仿的拐杖。
     注意这里示范的「处理过程」比「最终结果」更重要。 -->

### 例 1：用户说「帮我写周报」

- 用户没给素材，`$ARGUMENTS` 为空 → 走 Instructions 第 1 步收集事项。
- 你问：「好，我先收集这周的内容。本周完成了哪些关键任务？有可量化的数据吗？有卡住的问题吗？下周大致计划？」
- 拿到答案后：确认范围 → 按 4 块结构组织 → 套语气篇幅 → 自查清单。
- 输出一屏内的周报，末尾问一句：「要按这个发出去吗？还是需要调整哪一块？」

### 例 2：用户说「总结一下这周，我做了 A、B、C」

- `$ARGUMENTS` 已带 A/B/C → 不用追问「本周做了啥」，直接进入确认范围。
- 但数据、问题、下周计划可能仍缺 → 一次问完这三个方向。
- 输出结构与例 1 相同。

## Troubleshooting

<!-- 为什么要有 Troubleshooting：skill 不是万能的，用户输入千变万化。
     写清楚「写不出来 / 风格不对」时怎么办，模型才不会硬编、硬套或中途放弃。
     这是 skill 的「错误处理」部分——正文结构约定里，Instructions / Examples /
     Troubleshooting 三件套是 Claude Code skill 的推荐骨架。 -->

- **素材很少，写不满 3-5 条核心进展**：不要编造。明确告诉用户「目前只有 N 条」，给出可补充的追问方向，让用户决定是否就以 N 条输出。
- **用户说「这次不要按我风格，随便写」**：这是明确的风格豁免。跳过第 4 步「套个人风格」，按通用周报写，并先跟用户确认这是临时豁免。
- **风格不对（用户觉得不像自己）**：先认错，然后对照自查清单第 2、3 项逐条修正——大概率是空词多了或篇幅超了。修正后再让用户读一遍。
- **用户只要一句话总结，不要完整周报**：尊重原意，只输出一句话总结，不要强行套 4 块结构。
- **不确定某条信息是否该写进周报（敏感/不确定）**：问用户，不猜。

references 放什么。 两个文件，都是渐进披露第三层的「深潜素材」：

last-week-example.md：上周真实周报，Claude 拿不准句式、篇幅时对照。这文件会随每周真实周报更新，替换文件即可，不动 SKILL.md 正文。
team-style.md：团队周报提交规范——每周五 18:00 前发、邮箱标题 周报-姓名-YYYY-MM-DD、纯文本不带附件、抄送直属领导、不写预算薪资和负面评价。它是「低频细节」，只在要确认发送格式时才翻出来；换团队只换这个文件。

scripts 里放什么。 validate.js 是一个零依赖的静态校验脚本，专门查 skill 是否符合命名契约。写完 skill 从项目根跑一句就能验证：

node examples/skill-demo/weekly-report/scripts/validate.js

脚本的关键逻辑，是把它要校验的「契约」先声明成常量，再逐条检查：

const SKILL_FILE = 'SKILL.md'
const OPTIONAL_DIRS = ['references', 'scripts']
const KEBAB_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/   // kebab-case：全小写，段间单连字符

// ① 目录存在
// ② 目录名是 kebab-case
// ③ SKILL.md 存在且文件名全大写
//    —— Windows 不区分大小写，必须 readdirSync 取磁盘真实文件名核对，
//        才能抓出「写错大小写」的情况
// ④ frontmatter 含 name + description，且 name 与目录名一致
// ⑤ frontmatter 之后正文非空
// ⑥ references/ scripts/ 若存在，其文件名也须 kebab-case

核心是一处 Windows 特有的坑：文件系统不区分大小写，fs.existsSync('SKILL.md') 对 skill.md 也会返回 true，所以必须用 readdirSync 把磁盘上的真实文件名拿出来比对，才能抓出大小写写错。本机真实跑一遍（Node v22.12.0），输出是：

$ node examples/skill-demo/weekly-report/scripts/validate.js
全部检查通过：weekly-report skill 合规（目录 weekly-report/）

退出码 0。为了确认脚本真能抓到错，我用临时目录故意构造了 6 类坏文件，每类都能精确报错并退出码 1：

构造的错误	脚本输出	退出码
目录名非 kebab-case（`BadName`）	`[校验失败] 目录名「BadName」不是 kebab-case（应全小写字母/数字，段间用单个连字符）`	1
文件名小写 `skill.md`	`[校验失败] 文件名大小写不对：磁盘上是「skill.md」，必须全大写「SKILL.md」。Claude Code 对文件名大小写敏感，写错会静默失败——文件在但 skill 加载不上。`	1
name 与目录名不一致	`[校验失败] name（another-name）与目录名（ok-dir2）不一致，Claude Code 要求两者完全一致`	1
frontmatter 后正文为空	`[校验失败] SKILL.md 正文为空：frontmatter 之后必须写 Instructions / Examples / Troubleshooting 等正文`	1
references 里文件名非 kebab-case	`[校验失败] 「references/Bad Name.md」文件名不是 kebab-case（主干「Bad Name」应全小写、段间单连字符）`	1
skill 目录不存在	`[校验失败] skill 目录不存在：<path>`	1

怎么把它变成你自己的。 整个 demo 随文章放在 examples/skill-demo/ 里，你把 weekly-report/ 整个目录复制到 .claude/skills/ 下就能用。但记住一点：照抄示例没有意义。 这份 skill 里的「个人风格」是示例作者的，你要把结构、语气、篇幅换成你的，references/ 换成你上周的真实周报。skill 的价值就是把「你的经验」固化下来——周报结构是你的，四块变三块、语气更活泼、篇幅更长，都随你。

4.4 写完怎么验：别急着宣布成功

写完 skill 到「它真的能用」之间，隔着一层验证。静态校验脚本只挡了第一关——命名和格式合规；真正要验的是「会不会触发」和「输出对不对」，这两关要动真实对话。

第一关，触发测试。 写一个 should-trigger 矩阵：10 到 20 条用户可能说的话，分两类。一类「应该触发」（比如「帮我写周报」「这周总结一下」），一类「不该触发」（比如「帮我算一下报销」）。然后一条条真发出去，数有多少条自动触发了 skill，目标是不低于 90%。Anthropic 的建议是：先挑你用例里最难的一例，迭代到它稳定工作，再把这套方法扩展到其他用例。 不要一上来就追求全覆盖。

第二关，输出质量。 同一个请求跑 3 到 5 次，比输出的结构稳不稳定。周报 skill 的验收标准就是那几句：是不是正好四块、顺序对不对、篇幅超没超一屏、数字是不是都来自用户。跑几次如果每次都变形，说明你的 Instructions 还不够明确。

第三关，回归。 改完 description 再全量跑一遍 should-trigger 矩阵。最常见的回归就是：你为了让某个触发词更精准，把 description 收窄了，结果之前能触发的话现在不触发了。所以任何 frontmatter 改动后，都要把整套矩阵重跑一遍。

验证时最容易碰到的四种症状，我整理成一张对照表：

症状	最可能的原因	修法
skill 完全不触发	description 没写触发词 / 写得太模糊	按「做什么 + 何时用 + 关键能力」重写，把用户口语说法埋进去
不该触发时也触发	触发词太宽泛	收敛触发词，加「仅当…时用」的限定
触发了但指令被忽略	正文堆砌、没分层	正文压到 500 行内，Instructions 步骤化，加 `IMPORTANT:` / `NEVER:`
输出不稳定、每次不一样	步骤不够明确、缺自查清单	把「期望输出」和「自查项」写死，复用本文周报 skill 第 5 步的做法