12 · Skill

📚 系列导航：上一篇 11 Subagent 派分身干脏活。这一篇封装另一种能力——把反复执行的步骤打包成 Skill。

---

01 Skill 是什么

Skill = 带 SKILL.md 文件的目录 + 可选脚本和参考资料，打包成一项「专项本事」交给 Codex。

my-skill/
├── SKILL.md          # 必需：YAML frontmatter（name + description）+ 正文指令
├── scripts/          # 可选：可执行脚本
└── references/       # 可选：参考文档

TIP

能用指令说清的就别写脚本——让 Codex 照着自然语言步骤干更灵活。只有需要「确定性行为」或调外部工具时才值得捆脚本。

判断标准： 当你不断将相同说明、检查清单或多步骤程序粘贴到聊天中时，就该创建 Skill。

与 Subagent 的区别： Subagent 有独立上下文窗口和独立工具；Skill 没有独立上下文，是在 Codex 主上下文中展开的指令集。

---

02 存放位置

手写 Skill 的存放位置（注意！不是 ~/.codex/skills/）：

作用范围	放哪	谁可用
当前目录	$CWD/.agents/skills	该目录下
仓库根	$REPO_ROOT/.agents/skills	整个仓库
用户级	$HOME/.agents/skills	你这个用户的所有仓库
机器级	/etc/codex/skills	该机器所有用户

Codex 会从当前目录往上扫到仓库根，沿途每一级的 .agents/skills 都读。

WARNING

例外：$skill-installer 安装器会把精选 Skill 装到 ~/.codex/skills/——那是安装器行为，不是手写位置。自己手写一律走 .agents/skills，安装器装的留在原地别动。

同名不合并： 两个同名的 Skill 不会覆盖，都会出现在技能选择器里。所以跨层别用相同名字。

---

03 SKILL.md 结构

---
name: code-review
description: 对我的代码变更做一次结构化审查，列出所有发现的问题。当用户说「帮我看看改动」「审查代码」时使用。
---

按以下顺序审查代码变更：
1. 可读性：命名有没有歧义？注释是否过时？
2. 正确性：逻辑错误？边界情况？
3. 安全：用户输入直接拼接？凭证泄露？
4. 测试：现有测试覆盖了这次变更吗？

description 是匹配算法的钩子，不是写给人看的简介。 把核心触发词前置，因为初始清单有字符预算（约 2% 或 8000 字符），装太多 Skill 时描述会被压缩。

---

04 渐进式披露

平时 Codex 只看到每个 Skill 的「名称 + 一句 description + 文件路径」。用到时才展开完整 SKILL.md 正文。所以装再多 Skill 也不撑上下文——但初始清单有预算，装太多时 Codex 会先缩短描述，极多的会直接忽略并给出警告。

---

05 触发方式

维度	显式调用	隐式调用
怎么触发	打 $ 或 /skills 选	正常说需求，Codex 自己匹配 description
Codex 做不做判断	不做，点名即用	做，拿你的话比对 description
准不准取决于	你点对没有	description 写得好不好

显式调用时 Codex 不做任何匹配判断，直接加载完整 SKILL.md。

---

06 管理

创建：

$skill-creator

它会问三个问题：这个技能做什么？什么时候触发？纯指令还是带脚本？答完自动生成目录和 SKILL.md。

安装现成的：

$skill-installer linear

禁用（不删文件）：

# ~/.codex/config.toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

改完重启 Codex 生效。

---

07 小结

知识点	一句话
Skill 是什么	带 SKILL.md 的目录，打包成一项本事
存放位置	.agents/skills（手写），不是 ~/.codex/skills/
必需字段	name + description（用于语义匹配）
渐进式披露	平时只露一句，用时展开全文
触发方式	显式 $ / 隐式按描述匹配
管理	$skill-creator 建，$skill-installer 装，config.toml 禁用

NOTE

下一篇：13 Memory：让 Codex 跨会话记住你。