这篇讲什么 / What this covers
这篇讲 Codex 里的 skills：它们是什么、为什么会出现在 /skills 菜单里、怎么显式调用、怎么写自己的 SKILL.md、什么时候应该用 skill，什么时候只需要普通 prompt、AGENTS.md、MCP 或插件。
This guide explains Codex skills: what they are, how /skills exposes them, how to invoke them, how to write SKILL.md, and when to use a skill instead of a prompt, AGENTS.md, MCP, or a plugin.
版本提醒 / Version note: Codex skills、插件和桌面版能力更新很快。本文按 2026-05-22 的 Codex 桌面版 / CLI 0.125.x 整理。实际可用 skill 以你当前会话里的
/skills列表为准。
一句话理解 / One-sentence definition
中文：Codex skill 是一组可被 Codex 按需加载的本地说明、脚本、模板或参考资料；它把“重复使用的一套工作流”变成可发现、可复用、可团队共享的能力。
English: A Codex skill is a local bundle of instructions, scripts, templates, or references that Codex can load on demand, turning a repeated workflow into a discoverable and reusable capability.
/skills 是什么 / What /skills does
| 项目 / Item | 中文解释 | English explanation |
|---|---|---|
/skills | 打开当前会话能看到的 skill 列表。 | Opens the list of skills visible to the current session. |
$SkillName | 在提示里点名调用某个 skill。 | Explicitly asks Codex to use a skill by name. |
| 自动触发 / Auto-selection | 当任务明显匹配 skill 描述时，Codex 可以主动加载。 | Codex may load a skill when the task clearly matches its description. |
SKILL.md | 每个 skill 的说明入口，包含名称、描述、步骤和约束。 | The instruction entry point for a skill. |
| skill 附件 / Skill assets | 可包含脚本、模板、参考文件、示例。 | May include scripts, templates, references, and examples. |
/skills 不是“运行所有技能”，也不是“安装技能”。它更像一个可发现目录：告诉你当前会话有哪些能力可以调用。
/skills does not run every skill and does not install skills. It is a discovery surface for capabilities visible in the current session.
Codex 里常见的 skill 类型 / Common skill types in Codex
| 类型 / Type | 中文说明 | English explanation | 例子 / Examples |
|---|---|---|---|
| 系统技能 / System skills | Codex 自带或宿主环境提供，通常不可直接编辑。 | Built into Codex or provided by the host environment. Usually read-only. | imagegen, openai-docs |
| 插件技能 / Plugin skills | 来自已启用插件，通常伴随 MCP、应用或模板。 | Provided by enabled plugins, often with MCP tools or artifact workflows. | browser-use:browser, documents:documents, presentations, spreadsheets |
| 用户技能 / User skills | 你放在本地 Codex skills 目录里的自定义工作流。 | Custom workflows stored in your local Codex skills directory. | release-check, seo-audit, migration-plan |
| 项目技能 / Project skills | 跟某个仓库一起维护，团队共享。 | Repo-scoped skills shared with the project/team. | repo-qa, design-system-review |
| 临时技能 / Thread-provided skills | 当前会话或运行环境临时注入。 | Temporarily provided by the current thread/environment. | Workspace-specific review or export workflows |
Skill、AGENTS.md、slash command、MCP、plugin 的区别
| 你要做什么 / Goal | 用什么 / Use | 中文解释 | English explanation |
|---|---|---|---|
| 给整个项目一套长期规则 | AGENTS.md | 写仓库约定、测试命令、代码风格、不可碰区域。 | Persistent repo instructions: conventions, test commands, style, boundaries. |
| 重复执行一套工作流 | skill | 例如“发布检查”“SEO 审计”“文档渲染验证”。 | Reusable workflow like release QA, SEO audit, or render verification. |
| 临时复用一句 prompt | 普通 prompt / snippet | 不值得做成 skill。 | A prompt snippet is enough. |
| 连接外部系统 | MCP | 数据库、浏览器、GitHub、内部 API。 | Connects Codex to external systems. |
| 打包技能 + 工具 + 应用 | plugin | 团队分发一整套能力。 | Ships skills, tools, and apps together. |
| 看当前有哪些技能 | /skills | 发现和选择。 | Discover and select. |
经验判断：如果一个流程需要“步骤 + 约束 + 示例 + 可能的脚本”，就值得做成 skill。只有一句话的，别做。
Rule of thumb: if the workflow needs steps, constraints, examples, and maybe scripts, make it a skill. If it is one sentence, keep it as a prompt.
一个 skill 长什么样 / What a skill looks like
my-skill/
SKILL.md
scripts/
check-links.mjs
templates/
pr-description.md
references/
release-policy.md最小 SKILL.md：
---
name: release-check
description: Run this skill when the user asks to prepare a release, verify changelog, run tests, or create a release checklist.
---
# Release Check
1. Read AGENTS.md and package scripts.
2. Inspect git status and changed files.
3. Run the repo's fastest relevant tests first.
4. Verify changelog, version, and migration notes.
5. Produce a release checklist with blockers first.中文重点：
name要短、稳定、可记忆。description要写“什么时候用”，不是广告语。- 正文写执行步骤、禁止事项、输出格式。
- 有脚本就放
scripts/，有模板就放templates/，有长资料就放references/。
English essentials:
- Keep
nameshort, stable, and memorable. descriptionshould say when to use it, not market it.- Body should define steps, constraints, and output format.
- Put scripts in
scripts/, templates intemplates/, long references inreferences/.
如何调用 / How to invoke a skill
| 调用方式 / Invocation | 示例 / Example | 适合场景 / Best for |
|---|---|---|
| 显式点名 / Explicit mention | Use $release-check to prepare this PR. | 你明确知道要用哪个 skill。 |
从 /skills 选择 / Pick from /skills | 输入 /skills 后选择 | 忘了名字，想看当前可用列表。 |
| 自然语言触发 / Natural trigger | “帮我做发布前检查” | skill 描述写得足够清楚时。 |
| 与文件结合 / With files | Use $seo-audit on these MDX files. | skill 需要读具体文件。 |
| 与工具结合 / With tools | Use $browser to inspect localhost. | skill 背后需要浏览器、文档、表格等工具。 |
英文模板：
Use $release-check on the current repo.
Scope: changed files only.
Output blockers first, then commands run, then remaining risks.
Do not commit unless I ask.中文模板：
使用 $release-check 检查当前仓库。
范围：只看本次改动文件。
输出：先列阻塞问题，再列已运行命令，最后列剩余风险。
不要提交，除非我明确要求。写好 description 的方法 / How to write a good description
| 差 / Weak | 好 / Strong |
|---|---|
Helps with releases. | Use when the user asks to prepare a release, verify changelog/version, run pre-release tests, or produce a go/no-go checklist. |
SEO skill. | Use for auditing MDX article metadata, internal links, canonical slugs, hreflang, thin sections, and sitemap readiness. |
Documents. | Use when creating, editing, redlining, or visually verifying .docx documents. |
好的 description 要包含触发词、任务边界、产出类型。不要只写“强大”“高效”“自动化”。
A strong description includes trigger phrases, boundaries, and expected output. Avoid vague words like powerful, efficient, or automated.
技能设计清单 / Skill design checklist
| 检查项 / Check | 中文问题 | English question |
|---|---|---|
| 触发清楚 | Codex 什么时候应该用它？ | When should Codex use it? |
| 边界清楚 | 哪些事不该做？ | What should it avoid? |
| 输入清楚 | 需要哪些文件、链接、数据？ | What files, links, or data are required? |
| 输出清楚 | 最终给用户什么格式？ | What should the final output look like? |
| 工具清楚 | 要不要浏览器、表格、文档渲染、MCP？ | Does it need browser, spreadsheet, document render, or MCP tools? |
| 验证清楚 | 怎么知道做完了？ | How do we know it is done? |
| 风险清楚 | 是否可能改文件、跑命令、花钱、泄露数据？ | Could it edit files, run commands, cost money, or expose data? |
什么不该做成 skill / What should not be a skill
- 只用一次的任务。
- 一句话就能说清的偏好，例如“回答短一点”。
- 会频繁变化的临时业务数据。
- 私密 token、密码、客户资料。
- 需要人类判断伦理、法律、财务风险的最终决策。
Do not turn one-off tasks, tiny preferences, fast-changing data, secrets, or final high-stakes decisions into skills.
团队共享建议 / Team-sharing guidance
| 做法 / Practice | 中文说明 | English note |
|---|---|---|
| 版本化 | skill 跟代码一起 review，避免口口相传。 | Version skills with code review. |
| 写 owner | 每个 skill 标明维护人。 | Assign an owner. |
| 写禁区 | 明确不能改哪些目录、不能跑哪些命令。 | Define forbidden paths and commands. |
| 先只读 | 新 skill 先跑只读审计，再允许改文件。 | Start read-only before allowing edits. |
| 留示例 | 给 2-3 个真实调用例子。 | Include 2-3 real invocation examples. |
| 定期清理 | 过期 skill 比没有 skill 更危险。 | Stale skills are worse than no skills. |
常见问题 / FAQ
/skills 里没有我想要的 skill 怎么办？
先确认它是否安装在当前 Codex 能读取的位置，插件是否启用，当前会话是否加载了对应能力。If it is a project skill, make sure the repo path and skill directory are visible to Codex.
skill 会自动运行命令吗？
skill 本身只是指令和资源；是否运行命令取决于 Codex 的工具权限、当前 approval policy、以及用户请求。A skill can tell Codex what to do, but permissions still matter.
skill 和 prompt library 有什么区别？
Prompt library 是文本模板；skill 是可被发现、可带资源、可指导工具使用的工作流。A prompt is text; a skill is a reusable workflow package.
skill 名字一定要 $ 吗？
$SkillName 是显式点名的常见写法；/skills 是发现入口。你也可以自然语言说“用 release-check skill”。The $ form is a clear explicit mention.
Codex skills 和 Claude Code skills 一样吗？
概念相似，都是按需加载的工作流说明，但目录、触发、宿主工具、插件生态和可用命令不一定相同。不要把 Claude Code 的 /commands、hooks 或目录结构直接照搬到 Codex。
推荐的第一批 Codex skills / First skills to build
| Skill | 中文用途 | English use |
|---|---|---|
repo-tour | 新仓库导览：架构、关键目录、测试入口。 | Codebase tour: architecture, directories, test entry points. |
bug-audit | 按调用链查 bug，不急着改。 | Bug audit through call paths before editing. |
release-check | 发布前测试、版本、changelog、风险清单。 | Pre-release tests, version, changelog, risk list. |
seo-mdx-audit | 内容站 MDX 的 metadata、内链、slug、薄内容检查。 | Metadata, links, slugs, and thin-content review for MDX sites. |
test-generation | 先读现有测试风格，再补最小测试。 | Read existing test style, then add minimal tests. |
migration-plan | 大改前输出阶段计划和回滚点。 | Plan phases and rollback points before large changes. |