前阵子我把 Codex 社区里的技能仓库翻了个底朝天，从论文写作到 GIS 空间分析，从 HTML 页面优化到 AI 漫剧脚本，甚至还有让 AI 自己改进技能的自举玩法。装了一堆 skill 之后，我的 Codex 反而变“笨”了——每次下发任务，它都在花大量上下文挑技能。后来我做了一次彻底的大扫除，把几十个项目挨个过了一遍，最后真正留在手边的，其实只有五个。
这篇就把我筛选的过程、留下的技能、以及藏在 SKILL.md 背后的配置细节都写出来。每个技能我都会给到实际的调用逻辑和踩坑记录，不是空谈“这个技能好用”。如果你也在折腾 Codex，或者刚听说 skill 这个概念还没理清，这篇文章应该能帮你省掉不少试错时间。
1. 先把 Codex 的技能机制看明白
1.1 Codex 是什么，不是什么
Codex 是 OpenAI 出的编码代理工具，说白了就是一个跑在命令行里的 AI 程序员。它和普通聊天窗口最大的区别是：它能真正操作你的电脑——读文件、改代码、跑测试、执行命令、看报错再修复。你可以把它想成一个“带着终端权限的实习工程师”，你布置任务，它自己动手往下查。
我用 Codex 最重的场景是三类：老项目重构、跨文件追踪 BUG、以及把一些重复的代码生成任务彻底脚本化。如果你只是拿它写个 hello world，那确实有点浪费。
1.2 skill 的加载机制与目录约定
Codex 的 skill 本质上就是一组 Markdown 文件，它借鉴了不少 Agent Skills 的社区规范。常见目录约定是：
- 全局技能装在
~/.codex/skills/下 - 项目级技能放在当前项目的
.codex/skills/下
每个技能目录里必须有一个SKILL.md作为入口文件，用 YAML front matter 写name和description，正文就是这个技能的行为准则和操作步骤。Codex 接任务时，会根据任务的语义去匹配技能目录里的name和description，命中了就把对应 Markdown 当作上下文的一部分加载进来。
这个机制的关键在于：技能不是插件，不提供任何独立运行的能力，它只是给 Codex 附带了一套“专属工作手册”。
1.3 为什么 90% 的技能不值得装
我踩过最大的坑就是“技能收集癖”。GitHub 上一搜一堆 awesome-codex-skills，看着哪个都像神器，clone 下来就往全局目录里塞。结果呢？我第一次让 Codex 写一段日期处理逻辑，它莫名其妙调用了一个“旅游攻略技能”，输出直接跑偏。
原因不复杂：技能描述之间互相打架，或者任务语义匹配到了不相关的技能。技能一旦装多了，Codex 做每一步都要在脑子里过一遍“这个任务到底用哪个技能”，浪费大量上下文，回答质量直线下降。
所以我现在筛选技能的标准非常苛刻：要么这个技能对应的工作流我每周都会碰到，要么它能解决真实痛点，否则一律删掉。下面这五个，就是通过了这个标准的幸存者。
2. 留下的第一个：学术论文写作 Skill
2.1 它解决什么问题
学术写作有非常固定的结构：标题、摘要、引言、方法、结果、讨论。通用模型的通病是“写得像作文”——喜欢排比、堆形容词、空话连篇。论文写作 skill 的核心，就是把论文写作的规范固化下来，让 Codex 每次都按同一个严谨框架输出，而不是自由发挥。
我当时找的是一个参考 Nature 写作风格的开源技能，github 上的 repo 名字类似 nature-write-skill。这类技能大部分结构都一样：一个 SKILL.md 定义流程，seeds 目录里放不同的模板片段，比如摘要模板、方法描述模板、结果呈现模板。
2.2 核心机制拆解
我建议你打开 SKILL.md 看一眼，好的论文写作技能一定包含这几件事：
- 结构约束：明确要求按 IMRaD 框架组织内容，哪一段写什么。
- 语气约束：要求使用客观、被动的学术语气，避免“I think”“very”这类词。
- 统计表述规范：要求 p 值、置信区间、效应量等按学术格式书写。
- 引用格式：固定使用某种参考文献格式，比如 APA 或 Nature 风格。
我见过最实用的 SKILL.md 片段长这样：
--- name: academic-writing description: 用于撰写学术论文草稿，特别适合结构化的科研写作任务 --- # 学术写作规范 - 输出严格遵循 IMRaD 结构 - 结果部分必须先说明统计方法，再呈现数据 - 引用统一使用 [作者, 年份] 格式 - 禁止使用“显著提升”这类模糊表述，必须给出具体数值这段代码看起来简单，但作用很大：Codex 每次命中这个技能，就会把这段规范注入上下文，输出风格会明显收敛。
2.3 实操演示
我实际用的场景是整理实验数据。比如我把一份 CSV 丢给 Codex，说：
“用 academic-writing 技能，根据这份数据写论文的结果小节，并生成图像说明。”
它会先读取数据，识别变量类型，然后选择合适的统计方法，最后按照结果小节的格式输出。整个过程比我自己对着 blank page 发愁快得多。
有一点必须提醒：论文写作技能生成的内容属于“初稿水准”，数据和结论的准确性你仍然要亲自核对。尤其涉及统计分析部分，AI 容易一本正经地用错检验方法，这个坑我踩过不止一次。
3. 留下的第二个：GIS 空间分析 Skill
3.1 为什么它会出现在我的列表里
很多人以为 Codex 只适合写 Web 代码，但我在做一个区域数据可视化项目时发现，地理数据分析的代码反而是最需要“领域知识注入”的。原因是：GIS 处理的每一步都有隐含约定，比如坐标系、数据格式、拓扑关系。通用模型写出来的空间分析代码，“看起来能跑”，实际上一跑就崩。
GIS 空间分析技能解决的就是这个问题：它把常用的空间操作流程固定下来，让 Codex 拿到 shp 或者 geojson 时，按一套成熟模板去执行，而不是随机应变。
3.2 关键能力拆解
一个合格的 GIS 技能必须包含：
- 数据格式识别：自动判断是矢量还是栅格，是 shp、geojson 还是 tif
- 坐标系检查：先读
.crs属性，确认数据是不是同一个坐标系，再决定要不要转换 - 常用操作模板：裁剪、缓冲区、空间连接、面积统计、点密度分析
- 可视化输出：出图的配色、图例、标题规范
技能代码里通常会封装 GeoPandas、Shapely、Rasterio 这些库的固定用法，我给你们看一个典型的裁剪流程：
import geopandas as gpd # 读取区域边界和点数据 boundary = gpd.read_file("city_boundary.shp") points = gpd.read_file("poi_points.geojson") # 统一坐标系 points = points.to_crs(boundary.crs) # 空间裁剪 clipped = gpd.clip(points, boundary) # 统计 count_by_zone = clipped.groupby("zone_id").size()3.3 实操演示与注意点
我当时的任务是：给每个市州范围内的便利店 POI 做密度分布图。没有技能时，Codex 大概率会忘记检查坐标系，出来的分布图缺一块或者偏到海里去。启用 GIS 技能后，它会按固定流程先做 crs 检查，再做裁剪，最后输出图表和统计表。
两个最常见的坑：
- shp 文件的编码问题。很多国内数据是 GBK 编码，读取时要显式指定
encoding="utf-8"或用cp936解码，否则属性表全是乱码。 - 文件路径里的中文和空格。GeoPandas 在某些系统下对中文路径支持不太好，最稳妥的做法是先把数据处理成纯英文路径再开始分析。
空间分析技能具备一定的通用性，但如果是做遥感影像、栅格计算这类更专业的需求，建议另外再准备一个专门的遥感技能，不要试图让一个技能覆盖所有 GIS 场景。
4. 留下的第三个：HTML 页面优化 Skill
4.1 前端交付的痛点
让 AI 生成一个 HTML 页面，五分钟就能出“看起来很完整”的代码，但你要真的拿它上线，问题一大串：标题层级混乱、没有 alt 属性、图片没压缩、表单标签不关联、移动端适配一塌糊涂。HTML 页面优化技能，就是针对这些问题做的专项检查与修复。
4.2 自动检查与优化流程
这个技能最核心的部分，是它内置的“页面体检清单”。Codex 会按清单逐项扫描目标 HTML，把问题整理成表格，再生成修正代码。我调试过的技能里，高频检查项包括：
- 语义化标签：h1-h6 是否按层级连续使用，section/article/header/footer 是否合理
- 图片优化：是否缺 alt，是否直接丢了个 5MB 的原图，有没有加 loading="lazy"
- 可访问性：表单是否有 label，按钮是否只靠颜色区分，对比度是否达标
- 性能：有没有随手引入大体积 CDN 库、script 是否阻塞页面渲染
- SEO 基础：title、description、canonical、结构化数据是否齐全
用这个技能处理一个简陋页面时，Codex 会先给你一份问题清单，再给出修复完的完整 HTML。清单长这样：
| 检查项 | 当前状态 | 建议 |
|---|---|---|
| 图片 | 缺少 alt，大图未压缩 | 补全 alt，添加 loading="lazy" |
| 标题层级 | h3 直接出现在 h1 之前 | 调整为 h1 > h2 > h3 顺序 |
| 可访问性 | checkbox 无关联 label | 添加 for 与 id 绑定 |
4.3 实操演示与使用边界
我一般会在两类场景里用这个技能：一是帮朋友快速优化活动落地页，二是让 Codex 对我自己写的半成品页面做自查。调用方式不复杂，让它“用 html 页面优化技能审查 index.html，输出问题清单和修复版代码”，它就会自己跑一遍。
真正想在生产环境用，还是建议接 Lighthouse 流水线做自动化检查，AI 技能更适合做“一次性检查 + 快速修复”，别指望它替代专业的前端工程。
5. 留下的第四个：AI 漫剧脚本与分镜 Skill
5.1 短剧内容生产的基本盘
我最近在帮一个内容团队做 AI 漫剧的前期脚本测试。所谓 AI 漫剧，其实就是用 AI 生成漫画分镜，再配上旁白、音乐、动态效果，合成短视频。这类内容生产最大的瓶颈不是画图，而是脚本——一集就一分钟，节奏稍慢，完播率马上掉下来。
AI 漫剧脚本技能干的活，就是把短剧行业的内功心法写成规则，让 Codex 生成脚本时自动带上行业套路：前三秒要抛钩子，中间要有反转，结尾必须留悬念。
5.2 技能里固化的“剧本公式”
我留下的是一个社区里评价还不错的 AI 漫剧技能，它的 SKILL.md 里直接写死了脚本结构：
--- name: ai-comic-script description: 生成适合 AI 漫剧的一分钟短剧脚本与分镜表 --- # 短剧脚本规范 - 一集时长 60 秒，对白不超过 12 句 - 结构：钩子(3s) → 铺垫(10s) → 冲突(20s) → 反转(15s) → 悬念(12s) - 分镜表必须包含：景别、运镜、画面描述、旁白、字幕 - 题材只允许健康向上，禁止任何低俗或敏感内容这个“题材只允许健康向上”的约束在技能描述里写死，很有必要。因为做内容生产工具，第一步就是内容边界控制，直接写进技能文档，每次调用都会被强制带上。
5.3 实操演示
我给它一个很简单的指令：
“用 ai-comic-script 技能，写一个职场反转题材的 60 秒剧本，一个实习生用一段话让老板当场愣住。”
它会生成这样的分镜表：
| 分镜 | 景别 | 画面描述 | 旁白 | 时长 |
|---|---|---|---|---|
| 1 | 中景 | 老板皱眉看着实习生 | “这个项目必须三天完成” | 5s |
| 2 | 特写 | 实习生平静抬头 | “我已经做完了” | 4s |
| 3 | 近景 | 老板拿过文件，脸色变化 | “这数据你哪来的？” | 6s |
这里特别有用的是：技能会把“反差点”自动埋在第四五个分镜里，省掉了让人工反复改稿的时间。内容团队拿这个做初稿，再人工润色，效率比从零写翻了几倍。
6. 留下的第五个：技能自改进（self-improving-agent）
6.1 什么是技能自改进
这个技能比较另类，它不是一个具体业务技能，而是一套“让 Codex 自己维护技能库”的方法。说白了就是：让 Codex 在实战失败之后，把教训回写到 SKILL.md 里，下次不再犯同样的错。
很多人的 skill 都是死的——装上去之后就再也不更新了。但技能文档本质上是一段文字，既然是文字，那 Codex 自己就能改。自改进技能利用的就是这一点。
6.2 具体的玩法设计
我自己的做法是准备一个全局技能，描述是“评审和改进其他技能”。它的 SKILL.md 里写了这样的指令：
--- name: skill-refiner description: 当任务失败或技能表现不稳定时，分析原因并更新对应技能的 SKILL.md --- # 技能迭代规则 1. 回顾最近一次失败的任务，定位是哪一步缺少规则 2. 将失败教训抽象成一条可执行的规则 3. 找到对应技能的 SKILL.md，在合适位置追加该规则 4. 规则必须具体，禁止模糊表述，例如“注意数据格式”改为“读取前必须用 .crs 检查坐标系”这个玩法有点递归的味道：我用一个技能去更新另一个技能，而且每次迭代都是真实的经验沉淀。
6.3 实操案例：一次真实的迭代
我之前那个 GIS 空间分析技能，第一次用的时候在坐标系检查上翻了车。它拿到一份数据，没检查 crs 就直接做了空间连接，结果匹配区域完全错误。我把这个失败告诉 Codex，让它启动 skill-refiner，它就在 GIS 技能里加了一条：
"执行裁剪或连接之前，先用.crs属性打印当前坐标系，并与目标坐标系对比，确认一致后再继续。"
之后再跑同类任务，Codex 就再也没犯同样的错。这就是技能自改进最实在的用法：每一次翻车，都是在给技能库打补丁。
7. 过滤技能时我是怎么避坑的
7.1 判断一个 Skill 值不值得留的 4 个标准
经过这一轮折腾，我总结出一套判断标准，现在看到新技能都会快速过一遍：
- 触发率：装完两周，如果一次都没触发，直接删。描述写得太泛的技能，命中率极低。
- 描述质量：好的描述应该具体到“什么场景、什么任务、什么输入输出”。写得太长会污染上下文，写得太短会误触发。
- 依赖复杂度：需要装一堆第三方库、还要配外部服务的，慎重。技能越重，越容易出问题。
- 与主流程的融合度：技能跟你的日常工作流关联越紧，价值越大。装一堆“看着好玩”的技能，只会让 Codex 在选择时精神分裂。
我在删技能时特别果断。Codex 的上下文资源有限，每多一个技能，就多一分选择负担。我现在全局技能保持在五个以内，配合项目级技能按需加载，稳定性和响应速度都改善明显。
7.2 Codex 本地配置要点
再顺带提一下 Codex 本体的配置。Codex 的配置文件一般是codex.json，里面可以指定模型、组织、以及接入兼容接口。我最常改的一个字段是 model：
{ "model": "gpt-5.2-codex", "org": "your-org-id" }如果你想把 Codex 接到第三方模型服务上，比如接到 DeepSeek，也可以在其配置里把模型的 provider 改成一个兼容 OpenAI 接口的自定义端点，然后对应修改模型名。这类兼容接口在社区里有很多教程，但本质上就是 model、base_url、api_key 三个字段的替换。切换之后别忘了跑一条最简请求做连通性测试，我遇到过不少次配置看着没问题，实际请求直接超时的。
属性说明：上面这段 JSON 里的 org 字段按你的实际情况替换，格式是通用示例，不同版本配置项略有差异。
7.3 常见报错与排查速查表
最后把我在配置和使用 Codex 时遇到过的典型报错整理一张速查表，对应排查思路都写在表里，方便你直接对照参考：
| 报错信息 | 常见原因 | 排查与处理 |
|---|---|---|
| the 'gpt-5.6-sol' model is not supported | 配置里用了旧的内部模型别名，当前服务端不支持 | 打开配置文件，把 model 改为官方当前支持的模型名 |
| 无法加载组织设置 | 登录凭证失效或组织上下文不对 | 重新登录账号，检查 org 字段与账号权限 |
| endpoint 请求无响应 | 本地网络配置异常，或 API 端点不可达 | 检查本地网络与服务端连通性，更换网络环境后重试 |
| skill 不生效 | 技能目录名与 SKILL.md 里的 name 不一致，或 description 匹配不上 | 检查目录命名与 front matter，name 必须一致 |
| 手机号验证收不到验证码 | 短信通道延迟或拦截 | 检查短信拦截列表，稍等重试，必要时联系官方客服通道 |
这表里的报错，我基本都亲身碰过。印象最深的是模型名那个问题，我照着某个旧教程配置了一串 gpt-5.6-sol，结果一运行就报 not supported。后来想明白，模型名这种东西和版本强相关，教程的时效性远比想象中短，一旦换了版本，旧配置就废了。
我个人在实际操作中的体会是：技能的价值不在数量，而在精准。翻过上百个技能之后，我现在对“货架”这两个字有了新的理解——货架上摆的东西越多，你找到真正要用的那一个就越慢。筛选出五个能打的技能，远比囤两百个吃灰的技能实用。建议你也找一个空闲的下午，打开自己的 Codex 配置目录，把那些装了两周都没触发过的技能删掉，只留下真正为你工作流服务的几个。最后再分享一个小技巧：每次完成一个重复性任务，顺手把解决思路固化成 SKILL.md。几个月之后，你会发现 Codex 越来越懂你的工作方式，那才是最值得留下的“技能”。
