第十一章 Skills 实战：把工作 SOP 打包成技能

11.1 一段让我顿悟的对话

跟一个朋友聊 AI 工具，他说："Codex 我也用，就是每次都要写一长串 prompt 才能得到想要的结果，烦。"

我问："那你为什么不把这串 prompt 存起来？"

他说："存哪儿？记事本？每次复制粘贴？"

我说："不是。Skills。"

他愣了一下："什么 Skills？"

那一刻我意识到：Skills 是 Codex 里被严重低估的功能。它不只是"存 prompt"，而是把你某一类工作的"完整 SOP"——包括 prompt、模板、参考资料、脚本——打包成一个 AI 可以"按需调用"的技能。

学会 Skills，你才真正从"会用 Codex"升级到"用 Codex 改造工作流程"。

11.2 什么是 Skill

一个 Skill 就是一个自包含的"AI 岗位 SOP"。

具体来说：

• 它是一个文件夹
• 里面有一份 SKILL.md（核心指令）
• 可能还有 scripts/（脚本）、references/（资料）、assets/（模板）
• 当 Codex 检测到适合调用这个 Skill 的场景，会自动加载并执行

类比一下：

11.3 Skill 跟 AGENTS.md 的关系

很多人困惑：AGENTS.md 和 Skills 有啥区别？

简单记：

• AGENTS.md 管"项目里的所有事"（怎么写代码、用什么工具、什么风格）
• Skill 管"某一类具体任务"（写周报、整理发票、做新闻雷达）

两者不冲突，互相补充：

项目级（AGENTS.md）              任务级（Skills）
┌──────────────┐                ┌──────────────┐
│ 这是什么项目  │                │ 周报 Skill    │
│ 用什么技术栈  │                │ 发票 Skill    │
│ 什么规范      │      ──→       │ 新闻 Skill    │
│ 什么边界      │                │ 评审 Skill    │
└──────────────┘                └──────────────┘
   背景知识                          可调用工具

11.4 Skill 跟 Prompt 模板的关系

很多人把 Skill 误解为"高级版 Prompt 模板"。其实差别不止一个数量级：

最关键是按需加载。系统初期只让 AI 看到 Skill 的"名字 + 一句描述"。当用户提到相关任务时，AI 才"展开"完整内容。这个机制让你拥有上百个 Skills 也不会撑爆 Codex 的上下文。

11.5 一个 Skill 的物理结构

最简单的 Skill 只有一份 SKILL.md：

weekly-report/
└── SKILL.md

完整的 Skill 可能是：

weekly-report/
├── SKILL.md              # 核心指令
├── scripts/              # 确定性脚本
│   ├── extract_data.py   # 提取本周日志
│   └── format_report.py  # 格式化输出
├── references/           # 参考资料
│   ├── 周报示例-good.md
│   └── 周报示例-bad.md
└── assets/               # 模板与素材
    └── template.md       # 周报模板

SKILL.md 是必须的，其他三个目录都是可选的。

11.6 SKILL.md 的标准结构

头部（YAML Front Matter）

---
name: 周报生成
description: 根据本周工作日志，生成一份结构化的周报草稿
keywords: [周报, 周记, 周总结, weekly, report]
version: 1.2.0
author: cassius
last_updated: 2026-04-19
---

字段说明：

• name：技能名（人话，越具体越好）
• description：一句话说明，Codex 通过这句话判断是否调用此 Skill
• keywords：触发关键词（中英都可）
• version / author / last_updated：元数据

正文（5 个核心部分）

## 何时使用

当用户提到以下场景时调用：
- 写周报 / 周记 / 周总结
- 月度复盘
- 阶段性工作回顾

不调用此 Skill 的场景：
- 写日报（用 daily-report Skill）
- 写月报（用 monthly-report Skill，季度的也用月报）

## 输入

需要从用户处获得：
- 本周日志路径（默认 ~/Documents/work-log/）
- 周报受众（默认"直属经理"）
- 是否需要 KPI 数字（默认是）

如果用户没说，主动问。

## 步骤

1. 读取日志目录下本周（周一到周五）的所有 .md 文件
2. 按"完成 / 进行中 / 待办 / 风险"四类提取关键事件
3. 套用 assets/template.md 模板填充
4. 如果用户要 KPI，从 references/kpi-fields.md 找出本岗位常见 KPI 项，请用户填写
5. 生成 weekly-report-YYYY-MM-DD.md 到当前目录
6. 末尾附"下周计划"（基于本周遗留 + 周历）

## 输出

- 文件：weekly-report-YYYY-MM-DD.md
- 格式：Markdown
- 长度：500-800 字
- 风格：客观、简洁、用动词开头

## 验收标准

完成后让用户确认：
- 4 个分区都不为空（如某项确实没有，写"无"）
- 无主观情绪化用词（"忙死了"、"很累"等）
- 数字有依据（不要瞎编）
- 末尾有"下周计划"

如果用户提出修改，记录到 references/feedback.md 用于后续迭代。

几个写法要点

要点 1：description 写"什么时候调用"，不写"做什么"

[差] description: 一个生成周报的工具
[好] description: 根据本周工作日志，生成一份结构化的周报草稿

第一种 Codex 不知道何时该用；第二种"本周日志 + 周报"两个关键词让它一眼看到匹配信号。

要点 2：步骤用"动词开头"，AI 才好执行

[差] 周报应该结构化
[好] 1. 读取本周日志
     2. 按四类提取
     3. 填入模板
     4. 生成文件

要点 3：明确"何时不调用"

防止 Skill 被"过度调用"。比如用户说"写月报"，不应该调用周报 Skill。

11.7 实战：从零写一个 Skill

我们把"周报生成"从想法做成可用的 Skill。

第 1 步：找一个"重复 3 次以上"的任务

随便找你最近一个月做了 3 次以上的相似任务。比如：

• 每周一次的周报
• 每天一次的日报
• 每次客户咨询的回复模板
• 每次新文章的封面图

我们以"周报"为例。

第 2 步：把任务步骤口述出来

不要先写文档，先口述。打开录音，说一遍你怎么写周报：

我每周五下午写周报。先打开 Obsidian，找到本周的日记，把每天写的事看一遍，挑出主要的几件。然后打开飞书，新建周报文档。我会按"完成、进行中、风险、下周"四块写。完成那块要写 3-5 件，最重要的放第一。每件配上数字依据，不能空说。下周那块要 3 件以内，对应明确的目标。最后发给经理之前自己读一遍，删掉所有"我觉得"、"应该是"这种虚词。

第 3 步：把口述变成 SKILL.md

---
name: 周报生成
description: 根据本周日志，生成一份按"完成/进行中/风险/下周"四块结构化的周报草稿
keywords: [周报, 周记, 周总结, weekly]
version: 1.0.0
---

## 何时使用

用户说"写周报"、"我要写周报"、"帮我整理周报"时调用。

## 输入

- 本周日志路径（默认 ~/Documents/diary/）
- 时间范围（默认本周一到本周五）

如未提供，主动问。

## 步骤

1. 读取日志目录下日期为本周一到本周五的 .md 文件
2. 按"完成 / 进行中 / 风险 / 下周计划"四块提取
3. 完成块：3-5 件，最重要在前，每件附数字依据（无数字时写"已完成"）
4. 进行中块：列出 + 当前进度 + 预计完成日期
5. 风险块：列出 + 影响 + 我打算怎么办
6. 下周计划块：≤3 件，对应明确目标
7. 全文删掉主观虚词："我觉得"、"应该是"、"可能"、"大概"、"差不多"
8. 输出到当前目录 weekly-report-YYYY-WW.md（WW = 周数）

## 输出

- 文件：weekly-report-YYYY-WW.md
- 格式：Markdown
- 长度：300-600 字
- 风格：动词开头、客观、有数字

## 验收

完成后让用户确认：
1. 四块都有内容
2. 完成块每件都有"数字"或"已完成"
3. 没有主观虚词
4. 下周计划 ≤3 件

第 4 步：放到正确的位置

Skills 可以放在三个层级（跟 AGENTS.md 类似）：

周报这种通用任务，放全局：

mkdir -p ~/.codex/skills/weekly-report
# 把 SKILL.md 放进去

第 5 步：测试

新开 Codex 会话，说：

帮我写周报

如果 Skill 正确加载，Codex 会回应类似：

好的，我看到有"周报生成"Skill 可以用。
请问：
1. 你的本周日志在哪个目录？（默认 ~/Documents/diary/）
2. 时间范围是本周一到本周五吗？

成功！它已经"知道"用什么 Skill 了。

第 6 步：迭代

第一版 Skill 一般不完美。每次用完想想"这次哪里别扭"，更新 SKILL.md。两三个版本就稳定了。

11.8 用辅助文件强化 Skill

只用 SKILL.md 已经能干很多事，但加上辅助文件，Skill 会"更聪明"。

scripts/：确定性的事让脚本做

AI 擅长"理解和创造"，但不擅长"精确计算"。比如"算一下本周工作时长"，与其让 AI 估算，不如写个脚本：

# scripts/calc_hours.py
import os
from datetime import datetime, timedelta

def calc_weekly_hours(diary_dir):
    today = datetime.now()
    monday = today - timedelta(days=today.weekday())
    total = 0
    for day in range(5):
        date = (monday + timedelta(days=day)).strftime("%Y-%m-%d")
        path = os.path.join(diary_dir, f"{date}.md")
        if os.path.exists(path):
            with open(path) as f:
                content = f.read()
                # 简单计算"投入时间"行
                for line in content.split("\n"):
                    if "投入" in line and "小时" in line:
                        # 解析数字...
                        ...
    return total

在 SKILL.md 里调用：

## 步骤

...
3. 运行 scripts/calc_hours.py 算出本周总工时
4. 在周报开头加一行"本周投入：X 小时"
...

references/：领域知识

放一些"AI 不一定知道，但你工作中要的"知识：

• references/kpi-fields.md：你公司各岗位的 KPI 字段定义
• references/team-glossary.md：团队黑话词典
• references/good-examples.md：好周报的范例
• references/bad-examples.md：差周报的反例（什么不能写）

SKILL.md 引用：

## 步骤

...
5. 写完后对照 references/good-examples.md 自检
...

assets/：可填充的模板

<!-- assets/template.md -->
# 周报 - {{ week_label }}

## 本周完成
{{ completed_items }}

## 进行中
{{ in_progress_items }}

## 风险
{{ risks }}

## 下周计划
{{ next_week_plans }}

---
本周投入：{{ total_hours }} 小时

SKILL.md 直接说"用 assets/template.md 填充"。

11.9 进阶：Skills 之间的组合

复杂场景，让多个 Skills 配合：

"做下周内容计划" 任务
       │
       ├─→ 调用 weekly-report Skill 拿到本周回顾
       ├─→ 调用 trend-monitor Skill 拿到行业最新动向
       ├─→ 调用 content-calendar Skill 排下周日程
       └─→ 输出 next-week-plan.md

你不用预先写"组合 Skill"。Codex 会自己根据任务需要，按顺序调用合适的 Skills。

11.10 团队 Skills 库

为什么团队需要

一个人写 10 个 Skills 是个人提效，团队 50 人都用同样的 Skills 是组织提效。后者收益是前者的 50 倍。

怎么搭建团队 Skills 库

方案 1：Git 仓库

建一个 team-skills 仓库，每个 Skill 一个文件夹：

team-skills/
├── README.md
├── prd-review/
│   └── SKILL.md
├── meeting-minutes/
│   └── SKILL.md
├── customer-faq/
│   ├── SKILL.md
│   └── references/
│       └── faq-history.md
└── ...

每个团队成员把这个仓库 clone 到 ~/.codex/skills/：

git clone https://github.com/yourteam/team-skills ~/.codex/skills/team

更新只需 git pull。

方案 2：共享网盘

不会用 git 的团队，可以用 OneDrive、坚果云、飞书云盘。每人把同步目录链接到 ~/.codex/skills/team/。

方案 3：内网 Skills 商店

大公司可以做一个内部 Skills 网站，团队提交 PR 上架。Codex Pro / Enterprise 支持自定义 Skills 源。

团队 Skill 的命名规范

[业务域]-[操作]
例：
- sales-quote-generator      销售-报价单生成
- support-ticket-classifier  客服-工单分类
- hr-resume-screener         HR-简历筛选

避免冲突，避免歧义。

团队 Skill 的迭代

新人入职第一天就能用上 50 个团队 Skills，工作 3 个月后被建议补充新 Skills（基于他遇到的高频任务）。

这是组织级的"AI 反哺"——人用 AI 提效，反过来又用经验丰富 AI。

11.11 常见问题

Q1：Skill 会不会被"误调用"？

会。如果你写的 description 太宽泛，Codex 可能在不该用时用。解决：description 写具体、加"何时不使用"段。

Q2：Skill 太多了 Codex 会不会卡？

不会。按需加载机制保证只加载用到的。但一般个人 50 个、团队 200 个内是合理上限。

Q3：Skill 改了之后，已有会话会立即生效吗？

不会。需要新开会话或手动 /skills reload。

Q4：能不能让 Codex 帮我写 Skill？

完全可以，而且推荐。你可以说：

我每周要做"X 任务"，步骤是 A、B、C。
帮我把这变成一个 Skill 放到 ~/.codex/skills/x-task/。

Codex 会起草，你审核调整。

Q5：Skill 可以跨工具吗？

部分可以。OpenAI 推出 Skills 格式后，社区开始让 Claude Code、Cursor 也支持。但成熟度不一，最稳妥的做法是 Skill 主要服务 Codex，AGENTS.md 跨工具通用。

11.12 一份"建议拥有"的 Skills 清单

下面 10 个 Skills，建议每个 Codex 用户都搞一份：

附录 C 提供这 10 个 Skills 的可直接复用模板。

11.13 本章小结

• Skill = 自包含的"AI 岗位 SOP"，是 prompt 的工程化升级
• AGENTS.md 管项目，Skills 管任务，互补
• 一个 Skill = SKILL.md（必）+ scripts / references / assets（选）
• SKILL.md 五段：何时用 / 输入 / 步骤 / 输出 / 验收
• description 写"何时调用"，不写"做什么"
• 重复 3 次以上的任务都该 Skill 化
• 团队级 Skills 库收益是个人的 50 倍
• 附录 C 有 10 个开箱即用的 Skills

下一章：第十二章 · 自动化与定时任务，让 Codex 自己起床干活。