把重复工作流沉淀成 Codex Skill：从零到 GitHub 托管实战

如果你每周都要把同一段要求重新发给 AI，这篇文章就是写给你的。比如每周五，你都要告诉 Codex：先整理本周成果，再提炼问题和经验，最后列出下周行动，不要编造数据，每个行动都要有完成标准。一次这样写，叫提示词。每周都这样写，背后其实是一套固定工作流。把这套工作流整理成一个文件夹，让 Codex 以后遇到类似任务就知道什么时候接手、按什么步骤执行、结果达到什么标准，这就是 Skill。Skill 的本质，是把脑子里的做事方法变成一套可以重复执行的系统。接下来我会用“每周复盘”作为贯穿示范，带你走完从找到工作流到上传 GitHub 的完整路线。不需要先会编程。

Codex Skill 到底是什么？它和普通提示词有什么区别？

Skill 是把普通提示词固化下来的系统，提示词只解决当前对话的一次任务，Skill 解决一类任务。你可以把 Codex 想成一位能力很强、但刚入职的新同事。它懂写作、代码、表格和分析，但不知道你在什么情况下会启动某项工作，不知道你习惯先做什么后做什么，不知道哪些公司规则不能违反，更不知道输出必须包含哪些栏目、做到什么程度才算合格。Skill 就是你交给这位新同事的岗位说明书、标准作业流程加必要工具和资料。

一份 Skill 通常会告诉 Codex 四件事：

1. 什么时候使用：哪些任务和说法应该触发它。
2. 怎么执行：收到任务后按什么步骤工作。
3. 可以用什么：脚本、参考资料或模板放在哪里。
4. 什么算完成：最终输出必须满足哪些标准。

普通提示词通常只服务当前对话。Skill 会保存在固定目录中。之后你可以用 $skill-name 点名，也可以让 Codex 根据任务自动判断是否使用。提示词解决一次任务，Skill 固化一类任务。

怎么判断一个工作流值不值得做成 Skill？

只有会重复发生、有稳定输入输出、包含固定步骤的任务才值得做成 Skill，临时任务或一句话能说明白的事不要做。不要看到任何提示词都急着做 Skill，先用下面四个问题筛选：

1. 这件事是不是会重复发生？
2. 它有没有相对稳定的输入和输出？
3. 中间是否存在固定步骤、规则或判断标准？
4. 如果换一个 AI，你是不是还要重新解释一遍？

其中三个回答“是”，通常就值得沉淀。适合做成 Skill 的例子包括：每周把零散记录整理成复盘和下周计划；每次写长文的提示词技能或者按照同一套标准如何起标题；发布产品前执行固定的检查清单；审核合同时检查相同的风险项；根据品牌规则回复客服消息；把固定格式的会议记录整理成任务清单；重复处理同一类 PDF、表格或接口数据。

不适合的例子也很明确：只会发生一次的临时任务；一句话就能说明白的简单操作；完全依赖临场创意、没有稳定步骤的任务；“帮我处理所有内容”这种没有边界的大目标。

我见过最容易犯的错误，是一上来就做“全能内容助手”。范围越大，触发越模糊，执行越不稳定。“帮我做内容运营”绝对不适合作为第一个 Skill，“把访谈记录整理成一篇符合固定结构的 𝕏 长文”就清楚得多。好的 Skill，不是无所不能，而是能把一件具体的事稳定做好。

动手第一步，如何把隐性工作流写到纸面上？

先填一张“工作流卡片”，把启动条件、用户输入、执行步骤、合格标准和异常处理全写下来。先不要急着创建文件，选一件你最近一个月重复做过至少两次的工作，然后写出下面这张工作流卡片：

工作流名称：

什么时候启动：

用户会提供什么：

执行步骤：
1.
2.
3.

最后输出什么：

什么结果算合格：

信息不足或出错时怎么办：

以“每周复盘”为例，卡片可以这样填：

工作流名称：
把一周的零散记录整理成复盘

什么时候启动：
用户提出周报、每周复盘、一周总结或工作回顾时

用户会提供什么：
一周内完成的事情、问题、数据和下周计划

执行步骤：
1. 提取事实和数据
2. 分类为成果、进展、问题和经验
3. 合并重复内容
4. 把未完成事项转成下周行动
5. 检查是否存在编造或空话

最后输出什么：
结构化周复盘和下周行动表

什么结果算合格：
保留原始数据；不虚构；行动有优先级和完成标准

信息不足时怎么办：
标记“待补充”，最多提出 3 个问题，不要猜

这张卡片很重要，因为 Skill 的 description、工作流程和质量标准基本都来自这里。如果你填不完，说明这件事可能还没有形成稳定工作流。这时先多做几次，记录自己每次如何判断，再回来做 Skill。不要把混乱包装成 Skill，先把工作流本身想清楚。

设计触发条件，为什么需要准备三个真实测试案例？

因为 Skill 的触发靠用户的自然语言，必须测试点名执行、自动触发和信息不足时的边界情况。接下来写三句用户可能真的会说的话。

第一句是明确点名：

请使用 $weekly-review 整理这周的记录。

第二句是自然表达：

帮我把这些流水账整理成周报，再列出下周优先级。

第三句是信息不完整的边界情况：

这周主要在做支付功能，帮我复盘一下。

这三句话分别测试点名后能不能正确执行、没点名时能不能自动触发、信息不足时会不会乱编。很多人只写“这个 Skill 能做什么”，却没有想过“用户会怎么说”。结果就是文件写得很长，但 Codex 根本不知道什么时候应该使用。触发案例不是宣传文案，而是 Skill 的入口测试。

规划文件结构，Skill 文件夹里到底该放什么？

最小只需要一个 SKILL.md 文件，随着需求增加再添加配置、脚本、参考资料和素材目录。一份 Skill 最小只需要一个文件：

your-skill/
└── SKILL.md

比较完整的结构是：

your-skill/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
├── references/
└── assets/

每个部分解决的问题不同，具体可以看下面这个对照表：

目录/文件	必要性	解决的问题	判断增加的标准
SKILL.md	必需	写触发条件、工作步骤和质量标准	只要有流程就必须有
agents/openai.yaml	推荐	控制界面里的名称、简介和默认提示	需要自定义展示信息时
scripts/	按需	放需要稳定执行的代码，如格式转换和数据校验	同一段代码每次都要重写时
references/	按需	放公司规则、术语、接口文档等长资料	背景资料很长，不是每次都要读时
assets/	按需	放最终交付会用到的模板、图片、字体等素材	每次交付都要套相同模板时

不要为了显得专业，先建立一堆空目录。Skill 会占用上下文，应该只保留完成任务真正需要的内容。先做最小可用版本，用到什么再增加什么。

初始化 Skill，怎么让 Codex 自动生成骨架？

命名只能用小写字母、数字和连字符，直接让 Codex 调用自带的 skill-creator 即可生成。Skill 名称只使用小写英文字母、数字和连字符，不要使用空格和中文，文件夹名称要和 Skill 名保持一致。例如 weekly-review、x-article-writer、check-release 或 contract-risk-checker。

新手最简单的做法，是直接让 Codex 调用自带的 skill-creator。把前面完成的工作流卡片发给 Codex：

请使用 skill-creator，把下面的工作流做成一个 Skill。

Skill 名称：weekly-review

工作流：
[粘贴你的工作流卡片]

要求：
1. 先创建在当前项目中；
2. 只创建真正需要的文件；
3. 完成后验证 Skill；
4. 告诉我如何测试和安装。

skill-creator 会使用初始化脚本，生成符合结构要求的文件夹。这次实际生成的是：

weekly-review/
├── SKILL.md
└── agents/
    └── openai.yaml

截图要点：在 Codex 中运行 skill-creator 初始化 weekly-review 后的终端，应能看到新建的 SKILL.md 与 agents/openai.yaml 两个文件。
图片来源：Unsplash

看到 SKILL.md 和 agents/openai.yaml，说明初始化完成。但这时只是有了空房子，真正决定 Skill 是否好用的，是接下来写进去的内容。

核心编写，如何打造一份高质量的 SKILL.md？

SKILL.md 分为 YAML 头部和 Markdown 正文，头部决定何时触发，正文决定触发后怎么做。文件开头必须是 YAML 头部：

---
name: weekly-review
description: 将一周的零散记录整理成结构化复盘和下周行动计划。用户提到周报、每周复盘、一周总结、工作回顾、学习复盘，或要求从流水账中提炼成果、问题、经验和下一步行动时使用。
---

这里最重要的是 description。它必须同时回答这个 Skill 能做什么，以及用户在什么场景下应该使用。不要只写“帮助用户复盘”，这句话没有具体场景。应该把“周报、每周复盘、一周总结、流水账”等真实触发方式写进去。Codex 会先读取 name 和 description 判断是否触发，然后才会读取正文。所以“什么时候使用”要写在 description 中，不要藏在正文最后。

正文不需要介绍 Skill 有多厉害，它是给另一个 Codex 实例看的执行说明。可以使用这套通用结构：

# Skill 名称

用一句话说明目标。

## 工作流程

1. 收集并检查输入
2. 按固定规则处理
3. 生成结果
4. 检查结果

## 信息不足或异常时

- 缺少重要信息时怎么处理
- 哪些内容不能猜测
- 什么时候应该停止并询问用户

## 输出格式

[固定栏目、顺序或模板]

## 质量标准

- 必须包含什么
- 不能出现什么
- 怎么判断已经完成

这次的每周复盘 Skill，核心流程是：

## 工作流程

1. 提取事实：识别已完成事项、进展、数据、问题和未完成事项。
2. 分类整理：归入本周成果、关键进展、问题与原因、经验与洞察。
3. 提炼重点：合并重复内容，不编造用户没有提供的事实。
4. 制定行动：把未完成事项和问题转成下周行动。
5. 检查输出：行动不超过 5 个，最高优先级不超过 3 个。

## 信息不足时

- 缺少日期、数据或负责人时，标记为“待补充”，不要猜测。
- 记录过少时，先输出可确认的内容，再提出最多 3 个问题。

## 质量标准

- 使用具体动词，避免“持续优化”“积极推进”等空话。
- 区分事实与推断。
- 每个行动都要有可以检查的完成标准。

截图要点：终端里查看 SKILL.md 的内容，展示 YAML 头部与「工作流程」「质量标准」等正文。
图片来源：Pexels

写正文时记住三条：只写完成任务必须知道的内容；越容易出错的环节，规则越要具体；能用 30 行说清楚，就不要写 300 行。Skill 不是知识百科，而是执行手册。

验证与安装，如何确保 Skill 能被正确读取？

用 skill-creator 验证格式，然后把整个文件夹复制到 ~/.codex/skills/ 目录。写完后不要直接宣布完成，先让 skill-creator 验证：

请使用 skill-creator 验证 ./weekly-review。
如果发现格式、命名或 YAML 问题，直接修复后重新验证。

验证器会检查文件夹名称和 Skill 名称是否一致、YAML 格式是否正确、name 和 description 是否存在、名称是否符合规则。成功时会看到类似 Skill is valid! 的通过提示。

然后把整个 Skill 文件夹安装到 Codex 的 Skill 目录。默认通常是 ~/.codex/skills/。Codex 不同版本或文档里也出现过 .agents/skills 的写法，本质一样，选一个保持前后一致即可，这里沿用 .codex/skills/。

macOS 或 Linux 可以执行：

cp -R ./weekly-review ~/.codex/skills/

也可以直接告诉 Codex：

请把 ./weekly-review 安装到我的 Codex Skills 目录。

截图要点：skill-creator 验证通过的终端输出，以及 ~/.codex/skills/weekly-review 安装后的目录结构。
图片来源：Pixabay

如果安装后没有立刻出现，新开一个 Codex 任务；仍然没有，再重启 Codex。结构校验通过，只能证明文件格式正确，它还不能证明这套工作流真的好用。

真实测试与排障，跑不通的时候该改哪里？

拿之前准备的三个案例逐个测，根据没触发、顺序乱、乱编等具体问题针对性修改对应配置。回到前面准备的三个案例，逐个测试。

测试 1：明确点名

请使用 $weekly-review 整理下面的记录。

检查是否按照 Skill 规定的栏目和顺序输出。

测试 2：不点名

把这些流水账整理成周报，再列出下周优先级。

检查 description 是否足够清楚，能让 Codex 自动识别。

测试 3：信息不完整

这周主要在做支付功能，帮我复盘一下。

检查它是否明确标记缺失信息，而不是虚构日期、数据和负责人。

我实际测试时，输入了首页上线、支付联调故障、证书过期、页面修复和下周 A/B 测试等零散记录。Skill 自动整理出了本周成果、关键进展、问题与原因、经验与洞察、带优先级和完成标准的下周行动以及需要补充的信息。

截图要点：输入零散记录后，weekly-review 自动整理出的「本周成果 / 关键进展 / 问题与原因 / 经验与洞察 / 下周行动」输出。
图片来源：Gratisography

如果结果不理想，不要马上推翻整个 Skill。先判断问题发生在哪里，对照下表进行排查：

现象	排查方向	修改位置
没有自动触发	触发词不够丰富	改 description
执行顺序不稳定	步骤描述有歧义	改工作流程
总是出现空话	缺乏约束	增加质量标准
信息不足时乱编	缺少边界规则	增加异常处理规则
同一段代码反复生成	没有固化逻辑	把代码放进 scripts/
SKILL.md 越写越长	资料干扰主流程	把长资料放进 references/

测试的目的不是证明第一版正确，而是找到下一次应该改哪里。

代码托管，怎么把 Skill 安全上传到 GitHub？

在 GitHub 建空仓库，清理敏感信息后用 Git 命令初始化并推送到远端。Skill 在本地跑通后，再上传 GitHub。GitHub 能帮你备份工作流、记录每次修改、在多台设备之间同步、分享给团队或粉丝，出问题时还能回到旧版本。

先在 GitHub 创建一个空仓库。

图片来源：Unsplash

如果 Skill 包含公司流程、客户案例或内部规则，选择 Private。公开之前，检查并删除 API Key、Token、密码和账号、客户数据、公司内部地址以及未公开的业务规则。

然后在本地项目目录执行：

git init -b main   # 需要 Git ≥ 2.28；老版本用 git init && git branch -m main
git add .
git commit -m "feat: add my first Codex skill"
git remote add origin <你的仓库地址>
git push -u origin main

以后每次修改，只需要：

git add .
git commit -m "docs: improve skill workflow"
git push

上传前可以用 git status 和 git diff --cached 确认即将提交的文件中没有敏感信息。

截图要点：Skill 已 push 到私有 GitHub 仓库的页面，能看到仓库内的 SKILL.md、agents/ 等文件。

到这一步，你完成的已经不只是一段提示词。你拥有了一套可以安装、测试、修改、同步和分享的个人工作流。

新手最容易踩的 5 个坑

1. 把聊天记录直接塞进 SKILL.md：聊天记录不是工作流，先提炼触发条件、步骤、异常处理和验收标准。
2. 一个 Skill 想解决所有问题：范围越大，自动触发和输出越不稳定。先从一个明确输入、一个明确输出开始。
3. 只有步骤，没有完成标准：“生成报告”不是验收标准，“包含 5 个固定栏目，每个行动有优先级和完成标准”才是。
4. 验证通过就认为已经完成：验证器只能检查结构，真正的质量必须用正常、模糊和缺失信息三类任务测试。
5. 把敏感信息上传到公开仓库：GitHub 的 Public 代表任何人都可能看到，不确定时先使用 Private。

实用摘要与操作清单

沉淀 Skill 的核心是把“我每次都要重新解释”，变成“它以后知道该怎么做”。

1. 找出最近一个月重复做过两次以上的任务。
2. 填写工作流卡片（启动条件、输入、步骤、输出、合格标准、异常处理）。
3. 写三个真实触发案例（点名、自然表达、信息缺失）。
4. 让 Codex 调用 skill-creator 生成最小可用骨架。
5. 编写 SKILL.md 的 YAML 头部和 Markdown 执行正文。
6. 验证并安装到 ~/.codex/skills/ 目录。
7. 用三个案例测试，根据结果针对性排障。
8. 清理敏感信息，推送到 GitHub 私有仓库。

常见问题 (FAQ)

Q: Skill 必须会编程才能做吗？
不需要。只要能把工作流卡片填清楚，直接让 Codex 调用 skill-creator 生成骨架即可。

Q: 提示词和 Skill 的根本区别是什么？
提示词解决当前对话的一次任务，Skill 保存在固定目录，解决一类重复任务，可点名或自动触发。

Q: Skill 的文件夹名称有什么限制？
只能用小写英文字母、数字和连字符，不能用空格和中文，且要和 Skill 名称保持一致。

Q: Codex 没有自动触发 Skill 怎么办？
检查 SKILL.md 的 description，把用户可能说的真实触发词和具体场景写进去。

Q: 安装后看不到 Skill 怎么办？
新开一个 Codex 任务，或者重启 Codex。

Q: SKILL.md 正文应该写多长？
只写完成任务必须知道的内容，能用 30 行说清楚就不要写 300 行。

Q: 验证通过是不是就代表 Skill 好用了？
不是。验证只检查文件格式，真正好不好用必须用真实任务测试。

Q: 上传 GitHub 前必须做什么？
检查并删除 API Key、密码、客户数据等敏感信息，不确定就先选 Private 仓库。

关于作者

Punk｜中科大 MBA｜HerName 首席设计师｜Stanley 商学院执行院长。专注 AI 提示词与 Learn in Public 实践。