每周五都要交一遍的那笔「税」每周五下午我都要把同一件事重新做一遍跟 agent 描述「我的周报长这样」。结构是固定的四块、语气要简洁务实、篇幅不超过一屏、数字必须具体——这些我讲过不下二十遍。但每次新开一个会话它统统不记得。今天我从零讲一遍下周它又忘光我再讲一遍。这就是我用 agent 以来交得最冤的一笔税每次新会话我的偏好、写作风格、领域词汇、质量标准全被清零。我明明已经教会过它很多次它却每次都像第一天上班。后来我搞懂了 skills 这回事。它把「我的周报长这样」写成一次、存起来以后 agent 每次都会自动用。写一次用一年还能在我的新经验里长出新的——就像种子落地生根自己发芽。skills再配上/loop就能把一些重复的事情自动化的给处理掉。2. skills 是什么agent 怎么用它2.1 一个 skill 的解剖经验包不是长 promptskill 在 Claude Code 里就是一个文件夹放在.claude/skills/下。文件夹里最关键的是一个SKILL.md文件其余都是可选配件weekly-report/skill 就是一个文件夹SKILL.md必须frontmatter 正文references/参照素材示例、团队规范scripts/可执行脚本收集、校验assets/静态资源图片、模板SKILL.md是唯一必须存在的文件由两部分组成开头---包裹的 frontmatterYAML和正文。frontmatter 里最核心的两个字段是name和description后面会细讲。skill 是「可复用经验包」不是长 prompt。长 prompt 是把一段话每次重新粘进去skill 是把一段流程、一套判断标准、一组检查项打包成文件让 agent 在需要时自己取用。两者最大的区别是「反复照做」——只有你反复在做、且每次都希望结果稳定的那件事才值得写成 skill。打个比方MCP 是厨房——它提供锅碗瓢盆工具skills 是菜谱——它告诉 agent 这道菜按什么步骤做、放多少盐。工具可以借菜谱是你自己的手艺。2.2 三层渐进披露frontmatter 常驻正文按需skill 最聪明的设计是「渐进披露」progressive disclosure。它把内容切成三层按需加载不把整个 skill 一次塞进上下文不匹配 → 静默匹配 → 触发frontmatter 常驻name description约百级 tokens每个会话都在模型判断description 与当前任务匹配不加载不占上下文加载 SKILL.md 正文Instructions / Examples / Troubleshooting正文指向 references/ 文件时按需深潜加载示例 / 规范任务完成正文与引用物退出上下文逐层拆开看第一层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)》那篇里实现过一个技能注册表目录里只存 namedescription 当索引正文用getPrompt()按需取。当时我是在造一个「壳」现在我是往这个壳里放东西——壳怎么造的决定了我能往里面放什么。这两件事是一体两面理解了「描述常驻、正文懒加载」你写 skill 时就知道该把什么放 frontmatter、什么放正文、什么放 references。两个实用提醒。一是别装太多 skill每个常驻约百级 tokens装几十个累积起来也会占上下文预算大致是上下文的 2% 量级多了用/context看有没有被排除的警告。二是这条渐进披露原则是跨工具通用的——Agent Skills 是开放标准.claude/skills/里写好的 skillCodex 等同类工具也能识别换个工具你的经验还在。2.3 三种形态干活、当背景知识、引导创建不是所有 skill 都是拿来「被调用干活」的。按用途我把它分成三种任务 skill工作流。这是最常见的像菜谱一样走完一段流程。周报 skill 就是这个类型。默认由模型自动触发。背景知识 skilluser-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. 你的经验怎么变成 skills3.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-reportname就必须是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 NameH1与 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 一个完整案例周报 skillweekly-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.jsSKILL.mdskill 本体frontmatter 加正文。references/last-week-example.md上周真实周报Claude 拿不准风格时对照体现渐进披露第三层。references/team-style.md团队提交规范时间、渠道、保密项低频细节放这层换团队只换这个文件。scripts/validate.js校验脚本写完 skill 跑一遍查合规。README.md安装说明。SKILL.md 全文。下面是完整文件每个设计决策处我都用 HTML 注释写了「为什么这么写」——这些注释是给读者看的教学素材真实安装时删掉即可--- # frontmatterskill 的「身份证」与「激活开关」 # 说明frontmatter 是 --- 包裹的 YAML 块Claude Code 会解析它来识别这个 skill。 # 这里用 # 写的都是 YAML 注释只给读者看不影响解析。真实 skill 最少只需要 # name description 两个字段下面逐个解释「为什么这么写」。 # 注意frontmatter 里禁止出现 XML 尖括号即小于号与大于号字符Claude Code 会解析失败。 # nameskill 的唯一标识必须用 kebab-case全小写字母/数字段间单连字符 # 并且必须与所在目录名完全一致。两者不一致会导致 skill 无法被正确识别—— # 这是 Claude Code 的命名契约也是最常见的「写好了但加载不上」的原因。 name: weekly-report # descriptionskill 的「激活开关」是 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 !-- 为什么要有 Troubleshootingskill 不是万能的用户输入千变万化。 写清楚「写不出来 / 风格不对」时怎么办模型才不会硬编、硬套或中途放弃。 这是 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 从项目根跑一句就能验证nodeexamples/skill-demo/weekly-report/scripts/validate.js脚本的关键逻辑是把它要校验的「契约」先声明成常量再逐条检查constSKILL_FILESKILL.mdconstOPTIONAL_DIRS[references,scripts]constKEBAB_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-caseBadName[校验失败] 目录名「BadName」不是 kebab-case应全小写字母/数字段间用单个连字符1文件名小写skill.md[校验失败] 文件名大小写不对磁盘上是「skill.md」必须全大写「SKILL.md」。Claude Code 对文件名大小写敏感写错会静默失败——文件在但 skill 加载不上。1name 与目录名不一致[校验失败] nameanother-name与目录名ok-dir2不一致Claude Code 要求两者完全一致1frontmatter 后正文为空[校验失败] SKILL.md 正文为空frontmatter 之后必须写 Instructions / Examples / Troubleshooting 等正文1references 里文件名非 kebab-case[校验失败] 「references/Bad Name.md」文件名不是 kebab-case主干「Bad Name」应全小写、段间单连字符1skill 目录不存在[校验失败] skill 目录不存在path1怎么把它变成你自己的。整个 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 步的做法5. 结语生根发芽复利慢慢长回到开头那笔税。周报 skill 写完之后每周五我再也不用重新描述一遍「我的周报长这样」了。说出「写周报」三个字agent 就按我的结构、我的语气、我的篇幅把草稿交上来我只需要补一句「这周还推进了活动场地的事」。skills 是 Claude Code 的复利。每一个 skill 每次只省几分钟但按周、按月、按团队积累几分钟就滚成小时。更妙的是那层「生根发芽」我上个月给周报 skill 加了一条「问题要带负责人」这个月它写出来的周报就默认带上了——新经验长在旧经验上不用重新教。如果你现在正在某件「每周重复、每次重新描述」的事情上那这件事就是你的第一个 skill 的种子。这篇文章说的判断标准、四问法、description 公式、正文三件套都是为这一刻准备的。
