1. 引言

在前几篇文章里，博主已经编写了Codex相关的文章，有兴趣的童鞋可以先阅读：

• 《Codex 完整指南（一）：快速入门｜工程级 AI 编程代理》
• 《Codex 完整指南（二）：核心概念详解｜工程级 AI 编程智能体》
• 《Codex 完整指南（三）：OpenAI 官方实战指南整理｜251 篇（最新）》
• 《Codex 完整指南（四）：多端使用全景图｜IDE、CLI、Cloud 与团队集成》
• 《Codex 完整指南（五）：config.toml 配置详解｜模型、审批与沙箱机制》
• 《Codex 完整指南（六）：Rules、AGENTS、Prompts 与 MCP》

Agent Skills（代理技能） 可以为 Codex 扩展面向特定任务的能力，一个技能会将指令、资源以及可选脚本打包在一起，使 Codex 能够可靠地遵循某一工作流，你可以在团队之间共享技能，或将其分享给社区，技能都是基于开放的 Agent Skills 标准构建。

---

2. Agent skill 定义

描述：为 Codex 赋予新的能力与专业知识
原文地址：https://developers.openai.com/codex/skills

一个技能通过位于 SKILL.md 文件中的 Markdown 指令 来表达某种能力，技能文件夹中还可以包含脚本、资源和素材，供 Codex 在执行特定任务时使用。

技能使用渐进式披露（progressive disclosure）来高效管理上下文，在启动时，Codex 只会加载每个可用技能的名称和描述。随后，Codex 可以通过以下两种方式激活并使用技能：

显式调用（Explicit invocation）：可以在提示中直接包含技能。通过运行 /skills 斜杠命令来选择技能或输入 $ 来提及某个技能

隐式调用（Implicit invocation）：当你的任务与某个技能的描述匹配时，Codex 可以自行决定使用该技能。无论采用哪种方式，一旦技能被调用，Codex 都会读取该技能的完整指令以及技能目录中包含的所有附加参考资料。

---

当 Codex 从这些位置加载技能时，如果存在同名技能，则会用优先级更高的作用域中的技能覆盖优先级较低的，下表按优先级从高到低列出了技能作用域及其位置：

作用域	位置	建议
REPO	$CWD/.codex/skills 启动 Codex 时的当前工作目录	如果你在某个仓库或代码环境中，团队可以提交仅与该工作目录相关的技能，例如只适用于某个微服务或模块的技能
REPO	$CWD/../.codex/skills 在 Git 仓库中启动 Codex 时，位于 CWD 上一级的目录	当仓库存在多级子目录时，组织可以在父目录中提交适用于共享区域的技能
REPO	$REPO_ROOT/.codex/skills 在 Git 仓库中启动 Codex 时的最顶层根目录	适用于整个仓库的通用技能。它们可被任何子目录中的技能覆盖
USER	$CODEX_HOME/skills （macOS 和 Linux 默认：~/.codex/skills）	用户个人目录中的技能，适用于用户可能使用的任何仓库
ADMIN	/etc/codex/skills	机器或容器中的系统级共享技能，适用于 SDK 脚本、自动化以及默认的管理员技能
SYSTEM	随 Codex 一起打包	面向广泛用户的通用技能（如 skill-creator、plan 技能），对所有用户可用，可被上层作用域覆盖

Codex 支持 符号链接（symlink） 的技能文件夹，在扫描这些位置时会跟随符号链接的目标路径。

---

也可以在 ~/.codex/config.toml 中按技能粒度进行启用或禁用目前属于 实验性功能，未来可能会调整，你可以使用 [[skills.config]] 条目来禁用某个技能，而无需删除它，然后重启 Codex：

[[skills.config]]
path = "/path/to/skill"
enabled = false

3. 创建技能

描述：使用 Codex 创建自定义工作流，并在项目之间强制执行最佳实践
原文地址：https://developers.openai.com/codex/skills/create-skill

技能（Skills）让团队能够沉淀组织内部知识，并将其转化为可复用、可共享的工作流，技能可以帮助 Codex 在不同用户、代码仓库和会话之间保持一致的行为，尤其适用于希望自动应用标准约定和检查的场景。

一个技能是一个小型的组合体，包含以下内容：

• 名称
• 描述（说明技能的作用以及何时使用）
• 可选的指令正文

Codex 在运行时上下文中只会注入技能的名称、描述和文件路径，指令正文不会被注入，除非该技能被明确调用。

---

3.1 什么时候需要创建技能

当你希望在团队中共享行为、强制统一工作流，或将最佳实践编码一次并在各处复用时，应使用技能。典型使用场景包括：

• 标准化代码审查清单和约定
• 强制执行安全或合规检查
• 自动化常见分析任务
• 提供 Codex 可自动发现的团队专属工具

不建议将技能用于一次性提示或探索性任务；应保持技能聚焦、单一职责，而不是试图建模大型多步骤系统。

---

3.2 创建技能

3.2.1 使用技能创建器

Codex 内置了一个用于创建新技能的技能，使用该方法可以获得引导，并对技能进行迭代优化。

可通过 Codex CLI 或 Codex IDE 扩展调用技能创建器：

$skill-creator

也可以添加你希望该技能实现功能的上下文说明。

$skill-creator

Create a skill that drafts a conventional commit message based on a short summary of changes.

创建器会询问：

• 技能的作用
• Codex 何时应自动触发该技能
• 运行类型（仅指令 / 脚本支持）

于是继续输入：

Example trigger requests:
1) 根据以下改动摘要帮我写一条 conventional commit message：<改动摘要>
2) 把这段改动说明转换成符合 Conventional Commits 的提交信息：<改动说明>
3) 生成一条 conventional commit：<一句话总结/要点列表>

Conventional Commit constraints: default (standard types feat/fix/docs/style/refactor/perf/test/build/ci/chore/revert; optional scope; use ! + BREAKING CHANGE footer when breaking; add Refs footer if issue id present)
shell

输出结果是一个 SKILL.md 文件，包含名称、描述和指令，目录在 skills/draft-conventional-commit/SKILL.md，内容如下：

3.2.2 手动创建技能

当你需要完全控制，或直接在编辑器中操作时，可使用该方式。

Step1：选择存放位置（仓库级或用户级）

# 用户级技能（macOS/Linux 默认）
mkdir -p ~/.codex/skills/<skill-name>

# 仓库级技能（提交到代码仓库中）
mkdir -p .codex/skills/<skill-name>

Step2：创建 SKILL.md

---
name: <skill-name>
description: <功能说明及使用时机>
---

<指令、参考资料或示例>

重启 Codex 以加载该技能。

---

3.3 理解技能格式

技能使用 YAML front matter + 可选正文 的格式。必填字段：

• name：非空，最多 100 个字符，单行
• description：非空，最多 500 个字符，单行

Codex 会忽略多余的键，正文部分可以包含任意 Markdown 内容，会保存在磁盘上，且不会注入运行时上下文，除非技能被明确调用。

除了内联指令外，技能目录通常还包含：

• 脚本（如 Python 文件）：用于确定性处理、校验或调用外部工具
• 模板和结构定义：如报告模板、JSON/YAML Schema、配置默认值
• 参考数据：如查找表、提示语、固定示例
• 文档：说明假设条件、输入或预期输出

示例目录结构：

技能指令可以引用这些资源，但它们仍保留在磁盘上，从而使运行时上下文保持小且可预测。真实世界的模式和示例可参考 agentskills.io，以及 github.com/openai/skills 上的技能目录。

---

3.4 选择技能的保存位置

Codex 会从以下位置加载技能（仓库级、用户级、管理员级和系统级）。根据技能适用对象选择合适位置：

• 当技能应随代码库一起使用时，保存到仓库的 .codex/skills/
• 当技能应作用于本机所有仓库时，保存到用户技能目录
• 仅在受管环境中使用管理员/系统级位置（如共享机器）

完整的支持路径和优先级规则，请参阅 Skills 概览中的 “Where to save skills” 部分。

---

3.5 示例技能

示例技能如下：

---
name: draft-commit-message
description: Draft a conventional commit message when the user asks for help writing a commit message.
metadata:
  short-description: Draft an informative commit message.
---

Draft a conventional commit message that matches the change summary provided by the user.

Requirements:

- Use the Conventional Commits format: `type(scope): summary`
- Use the imperative mood in the summary (for example, "Add", "Fix", "Refactor")
- Keep the summary under 72 characters
- If there are breaking changes, include a `BREAKING CHANGE:` footer

触发该技能的示例提示：

Help me write a commit message for these changes: I renamed `SkillCreator` to `SkillsCreator` and updated the sidebar.

更多示例技能和创意请参阅 github.com/openai/skills 仓库。

编写技能时，建议遵循原则：

• 明确触发条件：描述用于告诉 Codex 何时触发技能
• 保持技能小而精：优先使用窄范围、模块化技能
• 优先使用指令而非脚本：仅在需要确定性或外部数据时使用脚本
• 假设无上下文：指令应假定 Codex 只知道输入内容
• 避免歧义：使用祈使句、分步骤指令
• 测试触发条件：确认示例提示能按预期激活技能

---

3.6 引入技能方式

① 团队级技能（随代码走）

<repo>/
└── .codex/
    └── skills/
        └── <team-skill>/
            └── SKILL.md

② 个人常用技能

~/.codex/skills/<skill-name>/

③ 使用符号链接共享技能

ln -s ~/company-skills/review-skill ~/.codex/skills/review-skill

---

3.7 问题排查

① 技能未显示（Skill doesn’t appear）

如果技能未出现在 Codex 中，请确认：

• 已启用技能并重启 Codex
• 文件名严格为 SKILL.md
• 文件位于受支持路径（如 ~/.codex/skills）

如果你在 ~/.codex/config.toml 中禁用了某技能，请移除或修改对应的 [[skills.config]] 条目并重启 Codex。

如使用符号链接目录，请确认目标路径存在且可读。Codex 也会跳过 YAML 格式错误 或 name/description 超出长度限制 的技能。

---

② 技能未触发（Skill doesn’t trigger）

若技能已加载但未自动运行，最常见原因是触发条件不明确。

• 确保 description 中明确说明何时使用该技能
• 使用与描述匹配的提示进行测试

若多个技能意图重叠，请缩小描述范围，以便 Codex 选择正确技能。

---

③ 启动校验错误（Startup validation errors）

如果 Codex 在启动时报校验错误，请根据提示修复 SKILL.md 中的问题，最常见原因是 多行 或 超长 的 name 或 description，修复后重启 Codex 以重新加载技能。

4. 常见主流的 Skills 仓库

随着 Agent Skills 标准逐步统一，社区已经出现了一批可直接复用或作为模板的 Skills 仓库。下面列出目前较为主流、与 Codex 兼容度高的仓库，并说明推荐的引入方式。

4.1 openai/skills（官方推荐）

仓库地址： https://github.com/openai/skills

定位:

• OpenAI 官方维护
• 提供一组 可直接使用 / 可参考实现 的 Codex Skills
• 覆盖规划、写作、代码、流程类技能
• 非常适合作为团队技能模板

引入方式一：直接克隆到用户级技能目录

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

引入方式二：只引入单个技能

mkdir -p ~/.codex/skills
cp -r skills/<skill-name> ~/.codex/skills/

重启 Codex 后即可通过 /skills 或 $<skill-name> 使用。

---

4.2 agentskills/agentskills

仓库地址： https://github.com/agentskills/agentskills

定位：

• Agent Skills 规范仓库
• 定义 SKILL.md 格式、字段约束、设计原则
• 包含示例与工具说明
• 更偏「写技能的人必看」

推荐用途

• 校对你写的技能是否符合规范
• 作为内部技能编写指南
• 不建议直接整体引入作为可执行技能

引入方式：不建议整体放入 .codex/skills，建议作为文档仓库单独 clone 阅读

git clone https://github.com/agentskills/agentskills

---

4.3 anthropics/skills（Claude 社区示例）

仓库地址： https://github.com/anthropics/skills

定位：

• Claude 社区公开 Skills 示例
• 包含较完整的目录组织、指令写法
• 对 Codex 高度可借鉴（SKILL.md 结构基本一致）

推荐用途

• 参考复杂技能如何拆分资源 / 模板 / 文档
• 借鉴 description 与 trigger 的写法

引入方式（选择性）

建议只复制单个技能目录，而不是整体引入。

git clone https://github.com/anthropics/skills
cp -r skills/<skill-name> ~/.codex/skills/

导入后重启内容如下：

---

4.4 agentskills.io（社区索引 / 市场）

网站地址：https://agentskills.io

定位

• 社区 Skills 聚合索引
• 可按类别搜索（写作 / 代码 / 分析 / DevOps 等）
• 指向 GitHub 仓库或可安装源

推荐用途

• 找灵感 / 找现成技能
• 快速定位某类工作流是否已有成熟实现

引入方式

1. 在 agentskills.io 找到技能
2. 跳转对应 GitHub 仓库
3. 复制技能目录到：

~/.codex/skills/

5. 文末

至此，本文已经系统梳理了 Codex Agent Skills 的概念、创建方式以及社区中常见的 Skills 资源，帮助大家理解如何将零散的 Prompt 升级为可复用、可共享的工程化能力。希望本文的内容能对大家在实际使用 Codex 构建个人或团队工作流时有所帮助，感谢大家的阅读，本文完！