用 Codex 久了，发现自己攒了一堆万能咒语。比如每次让它建新 Python 项目，都得复制粘贴同一大段话，用 uv 管理依赖、目录按 src 布局、必须配 ruff 和 pytest、README 要带徽章…… 几十行，存在备忘录里，每次开新项目翻出来贴一遍，改需求了还得回去改那段话。时间一长，这些咒语散落在各

用 Codex 久了，发现自己攒了一堆万能咒语。比如每次让它建新 Python 项目，都得复制粘贴同一大段话，用 uv 管理依赖、目录按 src 布局、必须配 ruff 和 pytest、README 要带徽章…… 几十行，存在备忘录里，每次开新项目翻出来贴一遍，改需求了还得回去改那段话。时间一长，这些咒语散落在各种地方，自己都记不清最新版在哪。后来才知道，这件事 Codex 官方早有正规解法，叫 Skill。把这套流程写成一个文件，Codex 就永久记住了，之后不用再贴那一长串，一句帮我建个新项目它就照着自己定的规范来。更妙的是它的加载方式，Codex 平时不会把所有 Skill 的完整内容都塞进上下文，它只记住每个 Skill 的名字和一句描述，只有真要用到某个 Skill 时，才去读它的完整内容，所以你哪怕写了几十个 Skill，也不占用平时的对话空间。这篇就手把手带你写一个自己的 Skill，从最简单的纯文字版，到进阶带脚本的版本。跟着敲，十分钟你就有了第一个专属技能。

Skill 到底是什么

一句话：Skill 就是一个文件夹，里面放一份告诉 Codex遇到某类活该怎么干的说明书。 这个文件夹里，唯一必须有的东西是一个叫 SKILL.md 的文件。它开头有一小段元数据（名字和描述），下面是给 Codex 看的具体步骤。就这么简单，一个纯文字的 SKILL.md 就是一个能用的 Skill 了。如果需求复杂点，文件夹里还可以放这些可选的东西：

scripts/：可执行脚本，需要确定性结果时用（比如一段必须精确执行的构建逻辑）
references/：参考文档，给 Codex 补充背景知识
assets/：模板、资源文件，比如项目脚手架的模板但记住，这些都是可选的。官方也建议：能用文字说清楚的，就别写脚本，只有当你需要精确、可重复的行为，或者要调外部工具时，才上脚本。

先搞清楚它放在哪、怎么被触发

在动手前，得先明白两件事，不然写完了不知道 Codex 能不能找到、会不会用。 第一，放哪。 Codex 会从几个位置扫描 Skill，最常用的是这两个：

项目级：放在项目里的 .agents/skills/ 目录下。适合团队协作，把 Skill 提交进 Git，所有人 clone 下来就都有了。
用户级：放在你个人目录的 ~/.agents/skills/ 下。适合自己的通用技能，不管在哪个项目都能用。这篇的例子放用户级，因为建新项目这种事跟具体某个仓库无关。 第二，怎么触发。 有两种方式：
显式调用：在对话里用 $技能名 直接点名，或者输入 /skills 从列表里选，想精确控制用哪个时用这个。
隐式调用：正常描述任务，Codex 发现内容跟某个 Skill 的描述对上了，自动就用了。这里藏着一个关键点，隐式触发全靠写的那句 description。 描述写得准，Codex 才知道什么时候该拿出这个技能。所以描述里要把什么时候用、什么时候不用讲清楚，并且把关键触发词放前面。

写第一个 Skill

做一个真实例子：一个按我的规范新建 Python 项目的 Skill。 第一步，建目录。

mkdir -p ~/.agents/skills/new-python-project

第二步，在里面建一个 SKILL.md，内容如下：


name: new-python-project
description: 当用户要新建、初始化一个 Python 项目或搭项目脚手架时使用。按团队规范生成目录结构、依赖管理和基础配置。不用于给已有项目加功能。

按以下规范初始化一个新的 Python 项目：

1. 用 `uv` 初始化项目，不要用 pip + venv。
2. 采用 src 布局：源码放在 `src/包名/` 下。
3. 必备开发依赖：`ruff`（lint + format）、`pytest`（测试）。
4. 生成 `pyproject.toml`，配置好 ruff 和 pytest 的基础规则。
5. 建一个 `tests/` 目录，放一个能通过的占位测试。
6. 生成 `README.md`，包含项目名、安装步骤、运行测试的命令。
7. 建好后运行一次 `uv run pytest` 确认能跑通，把结果告诉我。

注意看那段元数据里的 description，特意写清了什么时候用（新建/初始化项目）和什么时候不用（不用于给已有项目加功能），这就是让隐式触发准确的关键。 第三步，就没了。 Codex 会自动检测到新 Skill，如果它没出现，重启一下 Codex 就行。

试一下效果

现在打开 Codex，随便找个空目录，直接说一句大白话：

帮我在这里新建一个叫 datakit 的 Python 项目因为这句话正好撞上了 Skill 描述里的新建 Python 项目，Codex 会自动加载 new-python-project 这个 Skill，然后严格按写的七步来：用 uv 初始化、建 src 布局、配好 ruff 和 pytest、写 README、最后跑一遍测试给你看。也可以不靠它自己猜，直接显式点名： $new-python-project 项目名叫 datakit 效果一样，只是更精确，整个过程一个字的规范都没重复写，全在那份 SKILL.md 里了。以后规范变了，改那一个文件就行，不用再翻备忘录。

什么时候该加脚本

上面的纯文字 Skill 已经能覆盖大多数场景了，但有些活，需要它每次都分毫不差地执行，这时候就轮到 scripts/ 上场。举个例子。假设建项目这步里，有一段生成配置文件的逻辑，希望它完全固定、不受模型自由发挥影响，可以把这段逻辑写成脚本：

mkdir -p ~/.agents/skills/new-python-project/scripts

在 scripts/ 里放一个 init_config.py（或 shell 脚本），把那段确定性的逻辑固化进去。然后在 SKILL.md 里，把对应那步改成「运行 scripts/init_config.py 生成配置」。判断标准很简单：

步骤描述清楚、允许模型灵活处理 → 用文字就够了。
必须精确、可重复，或要调外部工具 → 写成脚本。别一上来就写脚本。文字版好维护、好读、改起来快，脚本是给非它不可的场景准备的。

几个让 Skill 更好用的习惯

一个 Skill 只干一件事。 别把建项目 + 发布 + 写文档塞进一个 Skill，拆成三个，职责单一，Codex 才好精准匹配。 描述里带上触发词。 因为 Codex 装了很多 Skill 时，会自动把描述缩短显示，所以要把最关键的使用场景和触发词放在描述开头，缩短了也不影响匹配。 用祈使句写步骤，输入输出写明确。 生成 pyproject.toml，包含 ruff 配置比处理一下配置强得多，你写得越具体，它执行得越稳。 写完拿几种说法测一下。 用不同的大白话去触发，确认该出现的时候出现、不该出现的时候不乱触发，再微调描述。

写在最后

Skill 这东西，本质是把你脑子里那套这活儿该怎么干的经验，从一次性的口头指令，变成了一份可以反复调用、持续迭代的资产。以前我们用 AI，靠的是当场把要求讲清楚，讲一次用一次。有了 Skill，你讲清楚一次，它就永久记住，而且团队里每个人都能共享同一套标准。这中间的差别，用久了会越来越明显——会写 Skill 的人，等于给自己配了一队随叫随到、还从不忘事的专属助手。今天这个「新建 Python 项目」只是最基础的例子。你完全可以照着这个套路，把自己天天重复的活——生成周报、按规范提 PR、跑固定的检查流程——一个个都教给 Codex。写第一个的时候花十分钟，之后每次都省十分钟。

给 Codex 写第一个 Skill，把重复 Prompt 固化成工作流