现在使用 Claude Code 或 Codex 的人，大多已经接触过 Skill。
需要处理 PDF、生成文档、检查代码时，找到对应的 Skill，安装以后就能直接使用。Skill 可以给 Agent 增加一套现成的能力，这件事很多人已经很熟悉了。
但回到自己的日常工作，另一种情况仍然不断发生：
你每天都在做相似的任务，每次都要重新告诉 Agent 文件在哪里、按照什么顺序处理、哪些内容不能遗漏、最后要输出成什么样。第一轮结果通常还不够准确，你需要继续补充要求、指出问题，来
回沟通几次，它才能做到你真正想要的效果。
第二天打开新的会话，同样的过程又要重新来一遍。
这时缺的不是一份别人写好的 Skill，而是一份属于你自己的 Skill。
因为你真正需要保存的，不只是那段提示词，而是整段磨合过程中逐渐明确的工作流程、判断标准和验收要求。
下面用一个“自动整理周报”的例子，看看怎么把这些反复发生的沟通，变成 Claude Code 和 Codex 都能使用的 Skill。
先说清楚：Skill 到底是什么
Skill 本质上是一个目录，最低限度只需要一份 SKILL.md：
weekly-report/
├── SKILL.md
├── scripts/ # 可选：可执行脚本
├── references/ # 可选：按需读取的资料
└── assets/ # 可选：模板、字体、图片等产物素材SKILL.md 的开头是 YAML frontmatter，至少包含 name 和 description；后面才是 Agent 真正执行任务时读取的指令。
---
name: weekly-report
description: 汇总项目资料并生成面向主管的周报。用户提到周报、周会汇报、团队进展或本周工作总结时使用。
---
# Weekly Report
整理信息时，不要机械罗列“做了什么”，优先回答：
主管需要知道什么、当前卡点是什么、下一步由谁推进。Claude Code 与 Codex 的安装位置、扩展字段和调用方式并不完全相同，但共同骨架已经相当稳定：SKILL.md 负责入口，references/ 放条件性知识，scripts/ 处理确定性操作，assets/ 放最终产物需要使用的素材。
这套结构背后有一个关键机制：渐进式披露。
在遵循 Agent Skills 规范的宿主中，发现阶段通常只加载 Skill 的名称和描述。某个 Skill 被选中后，才读取完整 SKILL.md；更细的参考资料和脚本，则等真正用到时再读或执行。
所以 Skill 不是“越完整越好”。它更像一套路由系统：先用极少的信息找到正确能力，再逐层拿到完成任务所需的细节。
这也解释了一个常见误区：很多人花最多时间写正文，却随手写了一句模糊的 description。结果正文再好，Agent 根本进不去。
什么任务值得做成 Skill
先找工作流，不要先找题目。
下面三个信号出现得越多，任务越值得封装；同时满足重复、专有知识和高错误成本时，优先级通常很高。
1. 重复出现，而且步骤相对稳定
同一类任务每周、每天都要做；每次开新对话，都要重新解释输入在哪里、按什么顺序处理、输出长什么样。
这已经不是临时提示词，而是一套等待被封装的工作流。
2. 依赖模型不知道的领域知识
例如项目目录规范、公司内部术语、主管偏好的汇报方式、数据库表关系、发布前检查项。
模型不是不会推理，而是它根本没有这些上下文。你每次口头补充，本质上是在反复给一个新同事做入职培训。
3. 做错的代价高，需要稳定验收
内部草稿错一点，可以手改；要交付客户的文件、会影响生产环境的操作、固定格式的数据，则不能靠模型临场发挥。
这里需要封装的通常不是“怎么写得更漂亮”，而是不可遗漏的约束、确定性步骤和验收方式。
周报正好符合前两个条件，也经常符合第三个：它每周重复，需要从多个地方取数，还隐含着团队自己的表达规则。
从哪里开始
最省力的起点，是从一次成功协作中逆向工程。
假设周三下午要向主管汇报。你开了一个新会话，让 Agent：
1、从 Google Drive 找到最近的工作日志；
2、从 GitHub 汇总过去一周的提交；
3、提取已经完成的工作、下一步和卡点；
4、按公司的周报格式输出 Markdown。
第一次执行通常不会顺利。权限、时间范围、仓库位置、信息优先级，都可能需要反复纠正。
但最后一旦做对，不要急着关掉会话。最值钱的不是那份周报，而是“从失败到成功”的完整上下文：Agent 错在哪里，你补了什么，它最终用了什么标准。
此时可以让 Claude Code 或 Codex 的 Skill Creator 从当前会话中提炼一份可复用 Skill。即使不用创建器，也可以直接提出要求：
把刚才完成周报的过程整理成一个可复用 Skill。
保留真正影响结果的输入、判断标准、工具调用和验收规则；
删除只对本次任务有效的偶然细节；
把条件性资料放进 references；
把适合确定性执行的步骤做成 scripts；
最后给出触发与不触发该 Skill 的测试请求。这条路对新手尤其友好：需求不是靠想象写出来的，而是从真实任务中长出来的。
如果还没有成功会话，就把 Agent 当成需求分析搭档：
我要创建一个生成团队周报的 Skill。
输入可能来自 Google Drive 工作日志和 GitHub 提交记录；
输出给主管阅读，需要突出进展、风险、阻塞和下一步；
每次默认汇总过去五个工作日。
先通过提问找出缺失的输入、边界、异常情况和验收标准。
信息足够后，再设计 Skill 的目录与内容。这里人的工作不是亲手写完每一行，而是把意图说透：任务为什么存在，什么结果算好，哪些边界不能越过，哪些决定可以交给模型。
Skill 写得好不好，往往取决于这些信息是否说清楚。
别急着写规则，先跑一个没有 Skill 的基线
更可靠的开发方式，是先让 Agent 在没有 Skill 的情况下做一次真实任务。
记录它失败的地方：
找不到输入，是缺工具还是缺路径？
选错信息，是缺业务判断标准还是缺示例？
时间范围不稳定，是自然语言不够清楚，还是应该交给脚本？
输出格式漂移，是缺模板还是缺验收？
做了不该做的事，是权限边界没有写清楚，还是触发范围太宽？
假设需求是汇总上一个完整工作周，也就是周一到周五。第一次跑周报，Agent 却抓了最近七个自然日，漏掉上周一、上周二，还混入了本周记录；它把 28 条 commit message 全部贴进正文；最后还把“等待测试环境”写成了“项目延期”。
这三个错误都出现在一份周报里，根因却不一样：一个是时间计算，一个是信息选择，一个是团队语义。先把问题记下来，后面再决定它应该落进 description、正文、reference 还是 script。这样写出的每条规则都有来历，不是凭空脑补。
不要一上来脑补五十条规则。规则越多，冲突越多，模型的注意力越分散，你自己也越难维护。
优化同样如此。结果不好时，不要只说“再试一次”。先判断缺的是工具、资料、原则、确定性程序，还是可观察的验收标准。
第一大坑：Agent 根本不触发 Skill
自动触发主要依赖 name 和 description。写正文时再认真，也救不了一个模糊入口。
名称：短、具体、能看出动作
使用小写字母、数字和连字符，目录名与 name 保持一致。例如：
weekly-report
pdf-processing
github-ci-repair名字不是越抽象越高级。productivity-helper 几乎没有判断力，weekly-report 一眼就知道解决什么问题。
描述：同时回答“做什么”和“什么时候用”
差的写法：
description: 帮助整理工作资料。它既可能漏掉周报，也可能在用户随便查看一份文档时误触发。
更好的写法：
description: 汇总工作日志与代码提交，生成面向主管的周报。用户提到周报、周会汇报、团队进展、本周总结或项目状态更新时使用；只查看单份日志或单次提交时不使用。假设第二次跑周报时，时间和内容都对了，但用户只说“打开今天的工作日志”，Skill 也被触发。这个失败与正文无关，应该收窄 description，再用正反请求重测。
写 description 时有三个实用原则：
1、使用用户真的会说出口的话，而不是只有作者才懂的内部术语；
2、把最关键的能力和触发词放在前面；
3、只加入能阻止明显误触发的边界，不要穷举世界上所有反例。
然后准备两组测试：
应该触发：
- 帮我整理这周的项目进展，下午周会要讲。
- 汇总上一个完整工作周的日志和提交，写给主管。
不该触发：
- 打开今天的工作日志。
- 看一下这个 commit 改了什么。
- 把这份 Markdown 改得简洁一点。不要只测一句“帮我写周报”。用户不会永远使用标准关键词。触发测试应该包含口语、简称、含蓄表达和相邻但不该触发的任务。
还要接受一个事实：简单的一步任务即使碰到关键词，Agent 也可能直接完成，而不加载 Skill。测试用例应该足够真实、复杂，确实能从 Skill 中获益。
第二大坑：把所有任务都写成死板 SOP
Skill 的自由度应该由任务风险决定。
如果任务有多个合理答案，需要结合上下文判断，就给目标、原则和优先级，不要规定每一步怎么走。
周报的指令可以是：
周报是给主管看的，不是个人流水账。
选择信息时优先判断“这件事是否会影响目标、风险或下一步决策”，
而不是机械罗列所有完成事项。
默认优先级：阻塞与风险 > 关键进展 > 下一步行动 > 一般活动。这几句话没有规定每周必须写几段，却给出了稳定的选择标准。没有 blocker 时，Agent 可以省略；某项指标波动很小，也可以判断是否值得占用主管注意力。
反过来，如果任务有客观对错，偏离步骤会造成实际问题，就降低自由度。例如固定表单校验、财务计算、发布日期检查、API 参数生成。
可以用一个简单尺度判断：
开放场景：写原则和结果标准；
有偏好但允许变化：写推荐流程，给参数和示例；
脆弱且高风险：写固定脚本、严格输入输出和停止条件。
不要迷信“SOP 越细，结果越稳”。对需要判断的任务，过窄的 SOP 往往会让 Agent 在稍有变化时直接失灵。
第三大坑：SKILL.md 越写越长
公开规范建议主 SKILL.md 控制在 500 行以内，但 500 行是上限提醒，不是目标。
问题不只是 token 成本。未来一个任务可能同时使用多份 Skill。一旦结果跑偏，你必须能快速看懂入口文件，找到是哪条指令、哪份资料或哪个脚本造成的。
拆分时，不要按“文件看起来整齐”来拆，要按信息的使用方式拆。
放进 SKILL.md 的内容
Skill 的目标与边界；
核心判断原则；
每次都要遵守的约束；
高层执行流程；
什么时候读取哪份 reference、运行哪个 script。
放进 references/ 的内容
公司术语和业务规则；
输出格式的详细说明；
只在特定场景使用的案例；
数据库 Schema、API 文档；
进度落后、风险升级等特殊写法。
例如：
如果本周出现延期、风险升级或依赖阻塞，
先读取 [延期汇报示例](references/delayed-project.md)，
再撰写风险与下一步部分。把文件移出去以后，还要在入口中写清楚“什么时候读”。没有路由说明的 reference，等于仓库里一份没人知道存在的文档。前面把“等待测试环境”误判成“延期”，就适合通过公司术语 reference 纠正。
放进 scripts/ 的内容
适合交给脚本的，通常是重复、确定、容易被自然语言执行错的操作：
取上一个完整工作周的提交；
调用固定 API；
排序、去重和计算；
校验字段与文件格式；
把稳定的数据转换流程跑一遍。
原任务是“自己想办法抓取上一个完整工作周的 commit”，加入脚本后变成“执行 scripts/get_previous_workweek_commits.py，再根据返回结果提炼进展”。
Agent 少做了一次临场编程，也修掉了基线测试中“最近七个自然日”和“上一个完整工作周”混用的问题。
但别把脚本神化。脚本不是越多越好，新脚本必须实际运行验证；出现环境差异、报错或需要修改时，Agent 仍可能读取源码。准确的说法是：脚本能把确定性逻辑固定下来，并且在正常执行时避免反复把实现过程塞进上下文。
放进 assets/ 的内容
模板、字体、图标、图片、样板工程等会被复制或加工进最终产物的文件，应该放在 assets/，而不是伪装成 Agent 指令。
一份公司周报模板属于 asset；“什么时候使用这个模板、哪些字段不得删”才属于指令。
把修正后的骨架放在一起
weekly-report/
├── SKILL.md
├── scripts/
│ └── get_previous_workweek_commits.py
├── references/
│ ├── company-terms.md
│ └── delayed-project.md
└── assets/
└── weekly-report-template.mdSKILL.md 不复述所有资料，只保留骨架：
---
name: weekly-report
description: 汇总工作日志与代码提交，生成面向主管的周报。用户提到周报、周会汇报、团队进展、本周总结或项目状态更新时使用；只查看单份日志或单次提交时不使用。
---
# 目标
生成一份便于主管快速判断进展、风险和下一步行动的周报。
# 原则
- 不写流水账，只保留影响目标、风险或决策的信息。
- 优先级：阻塞与风险 > 关键进展 > 下一步 > 一般活动。
- 不推测缺失事实；数据不足时明确标记。
# 执行
1. 确认项目、汇报对象和时间范围；未指定时使用上一个完整工作周（周一至周五）。
2. 读取工作日志，并读取 `references/company-terms.md`，按团队定义区分等待、阻塞与延期。
3. 执行 `scripts/get_previous_workweek_commits.py` 获取提交记录。
4. 按主题合并重复事项，提取结果、影响、阻塞和负责人。
5. 使用 `assets/weekly-report-template.md` 输出。
6. 如果出现延期或风险升级，读取 `references/delayed-project.md`。
7. 对照原始资料复核日期、数字、负责人和遗漏项。它没有穷举所有情况，只保留不能丢的判断标准、数据入口和验收动作。前面三个失败，也分别有了去处：时间范围归脚本，筛选标准归正文，团队语义归 reference。
Skill 写完，不等于开发完成
至少做三层验证。
第一层：结构验证
检查目录名、frontmatter、必填字段、相对路径和脚本依赖。公开规范有 skills-ref validate；Claude Code 和 Codex 的创建器也各自提供验证工具。
这一步只能发现“文件写错了”，发现不了“判断写坏了”。
第二层：触发验证
准备一组应该触发和不该触发的真实请求，检查漏触发与误触发。不要测试十个同义句，要覆盖边界：直接说周报、含蓄说周会准备、只查看日志、只解释一次提交。
第三层：行为验证
用同一批任务比较：
没有 Skill 时的结果；
使用 Skill 后的结果；
修改 Skill 后的新结果。
检查的不是文字是否一模一样，而是关键事实有没有漏、时间范围是否正确、格式是否稳定、风险是否被识别、执行成本是否下降。
复杂或高风险 Skill 可以再开一个独立 Sub-Agent 做验收。给它干净上下文、原始输入、实际产物和检查清单，不要提前告诉它“哪里可能有错”。否则它不是独立评估，只是在复述主 Agent 的怀疑。
维护 Skill：别让修补变成垃圾堆
Skill 的价值来自复利：每次执行都暴露一个实际问题，每次修正都让下一次更快、更稳。
糟糕的维护方式，是每失败一次就在末尾追加一条“永远不要……”；几个月后，文件充满重复、冲突和只为某次偶发错误存在的补丁。
维护时先删冗余，让同一原则只保留一个权威位置；再重整骨架，确保入口文件能迅速看出目标、边界、流程和资源路由；最后把只在部分场景使用的资料移到 references。
模型升级时，也值得重新跑一遍旧 Skill。过去为了补偿弱模型而写的繁琐规则，新模型可能已经不再需要。能删掉的补丁，比新增一条规则更有价值。
每次真实工作流跑完后，可以让 Agent 复盘：
复盘刚才的执行过程：
列出实际发生的错误、原因和影响；
判断它属于工具、资料、规则、脚本还是验收缺口；
只提出能防止同类错误再次发生的最小修改；
先给修改建议和 diff，不要直接把新规则散落写进 Skill。重点是“最小修改”。不要把一个案例直接升级成全局戒律，也不要让 Agent 在没有审查的情况下随意改写长期资产。
Claude Code 与 Codex：骨架相同，落点不同
以下信息核对于 2026 年 8 月。产品变化快，实际使用时仍应以官方文档为准。
Claude Code 支持根据 description 自动选择，也可以用 /skill-name 显式调用。项目级 Skill 放在 .claude/skills/<skill-name>/SKILL.md，个人 Skill 放在 ~/.claude/skills/<skill-name>/SKILL.md。它还扩展了调用控制、Sub-Agent 执行和动态上下文注入等能力。
Codex 支持根据 description 隐式选择，也可以用 $skill-name 显式调用。项目级 Skill 可放在仓库路径下的 .agents/skills，个人 Skill 可放在 $HOME/.agents/skills。它还可以使用 agents/openai.yaml 配置展示信息、依赖和是否允许隐式调用。
斜杠命令、美元符号、具体路径和扩展字段都属于宿主实现，不要写进“所有 Agent Skills 都必须如此”的通用规则。可以先用开放规范设计目录和 SKILL.md，再为目标宿主补充平台配置，并在那个宿主里实际测试。
不要假设“格式兼容”就等于“行为一致”。不同模型、不同工具权限、不同上下文策略，都会影响同一份 Skill 的触发和输出。
Skill 不是提示词收藏夹
一份有价值的 Skill，转移的是人的判断：
什么信息值得看；
什么情况必须停下来确认；
哪些步骤可以自由发挥；
哪些步骤必须交给确定性程序；
什么结果才算完成。
模型会越来越强。Skill 没必要用几百条规则把模型锁死，它更该保存模型无法凭空知道的上下文、边界和判断标准。
人掌舵，Agent 执行。Skill 是两者之间可以反复打磨的操作界面。
