GPT Codex 中文指南

主题

Codex Skills 怎么用？安装、创建与 SKILL.md 配置保姆级教程（2026最新） ​

更新时间：2026年8月4日

搜索 Codex Skills、Codex Skill 安装 或 Codex Skills 怎么用 的人，通常不是想再看一遍 Codex 安装教程，而是想解决三个更具体的问题：技能文件放在哪里、怎样让 Codex 识别、什么时候应该用 Skill 而不是提示词或 MCP。

先给结论：**Skill 是一套可重复使用的任务说明，核心文件是 SKILL.md。**它适合沉淀 SEO 发布、代码审查、文档生成、测试验收等固定工作流。临时要求写在当前提示词里；项目长期规则写在 AGENTS.md；需要访问外部实时数据或执行外部动作时，再配置 MCP。

国内开发路径

若你需要中文界面、高额度 GPT 编程模型或 Codex 国内使用方案，可以了解第三方平台 ZeoGPT。它不是 OpenAI 官方产品，先用公开仓库或脱敏代码测试，不要上传 API Key、.env、客户数据和生产日志。

Codex Skills 是什么 ​

Codex Skill 可以理解为“带触发说明的标准操作手册”。一个 Skill 通常包含：

  • name：技能名称；
  • description：什么任务应调用它；
  • 正文步骤：执行顺序、边界、验证方法和输出格式；
  • 可选的 scripts/、references/、examples/ 或 assets/；
  • 可选元数据：展示名称、依赖工具、默认提示词和调用策略。

它和普通提示词最大的不同，是可以被重复发现、按任务复用，并放到用户级或仓库级目录里。OpenAI 官方 Codex 仓库当前会扫描 SKILL.md，且区分 user、repo、system 与 admin 等作用域。产品版本会继续变化，实际目录和界面以 Codex Skills 官方文档 与当前客户端为准。

Skills、AGENTS.md、MCP 和 Plugins 怎么选 ​

需求应选机制典型例子
只对当前任务有效当前提示词“只修改这两个文件并运行构建”
仓库长期约束AGENTS.md技术栈、禁止目录、测试命令
重复执行的工作流程Skill发布文章、代码审查、生成周报
访问外部数据或服务MCPGitHub、数据库、浏览器、设计工具
打包分发多种能力PluginSkills、MCP、工具和资源的组合包

不要把所有内容都塞进一个 SKILL.md。如果一句规则对仓库内每次任务都有效，它更适合写入 Codex AGENTS.md 项目规则教程；如果需要连接外部工具，参考 Codex MCP 配置指南。

Codex Skills 安装位置怎么选 ​

最常见的是两种作用域。

用户级 Skill ​

适合你在多个仓库中都会使用的流程，例如代码审查、技术文章编辑、Excel 分析或发布检查。用户级目录跟随本机 Codex Home，具体路径可能因系统和安装方式不同而变化。

建议先在 Codex 当前界面的 Skills 管理入口确认实际目录，或输入 /skills 查看已发现的技能。不要仅凭第三方教程猜测路径，更不要把技能放进安装程序目录。

项目级 Skill ​

适合只服务当前仓库的流程，例如：

  • VitePress 新文章必须更新侧边栏、Sitemap 和 llms.txt；
  • 后端改动必须运行某组测试；
  • PR 审查必须按安全、兼容性、测试、回滚四项输出；
  • 文档只能修改指定目录。

项目级 Skill 应随仓库版本控制，并避免包含本机绝对路径、真实密钥或个人账号信息。它与项目根目录的 AGENTS.md 分层规则配合使用效果更稳定：AGENTS.md 管长期规则，Skill 管具体流程。

创建第一个 SKILL.md ​

下面用“VitePress SEO 文章发布”做一个最小示例。目录名应清晰、稳定，Skill 文件名使用大写 SKILL.md：

text
.codex/
└─ skills/
   └─ vitepress-seo-publisher/
      └─ SKILL.md

SKILL.md 可以这样写：

markdown
---
name: vitepress-seo-publisher
description: Publish a new VitePress SEO article and verify discovery surfaces.
---

## VitePress SEO Publisher

Use this skill when adding a new search-targeted article.

1. Check existing titles for keyword cannibalization.
2. Add a new Markdown file; do not overwrite an existing URL.
3. Add title, description, keywords, date, updated, and one H1.
4. Add 5-10 relevant internal links.
5. Run the repository build and SEO QA commands.
6. Verify canonical, sitemap inclusion, and broken internal links.
7. Return the final article URL and validation result.

这份最小模板最重要的不是字数，而是三件事：description 写清触发场景，正文写清边界，最后给出可验证的交付标准。

如何调用 Codex Skill ​

当前 Codex CLI 已提供 /skills 入口，用于查看和选择可用技能。常见使用方式有两类：

  1. 显式选择：先输入 /skills，选择目标 Skill，再描述本次任务。
  2. 在提示词中点名：明确要求使用某个 Skill，并补充本次任务的文件、范围与验收标准。

示例：

text
请使用 vitepress-seo-publisher skill。
目标：新增一篇 Codex Skills 中文教程。
限制：不覆盖旧文件，不删除旧 URL，只修改文章和发现入口。
验证：运行构建与站点 QA，并返回正式文章链接。

即使 Skill 已经写得很完整，本次任务仍要说明目标和范围。Skill 是复用流程，不是替代任务上下文。

一个好用的 Skill 应该怎样写 ​

1. 触发条件具体 ​

description 不要只写“帮助处理代码”。应写明“当用户要求审查 Git Diff、列风险并生成测试清单时使用”。描述越具体，越容易在正确任务中被发现。

2. 先写边界，再写步骤 ​

对于会编辑文件、调用接口或发布内容的 Skill，应先说明：

  • 允许修改哪些目录；
  • 哪些文件不得覆盖；
  • 是否允许联网、提交或部署；
  • 需要保护哪些敏感信息；
  • 失败时如何停止和报告。

3. 把稳定知识与易变信息分开 ​

稳定流程可以写在正文；版本号、模型列表、搜索排名和外部 API 字段容易变化，应该在执行时重新核对。不要把“当前最新版”永久写死在 Skill 中。

4. 复杂资料放 references ​

正文应短而可执行。长规范、字段表、示例输出放在 references/，批量处理脚本放在 scripts/。这样既便于维护，也能减少每次任务加载的无关内容。

5. 给出明确验收 ​

好的 Skill 会要求“构建通过、测试通过、链接可访问、输出变更文件”，而不是只说“完成后检查一下”。可验证的结束条件能显著减少半成品。

Codex Skills 不生效怎么办 ​

按下面顺序排查：

  1. 文件名是否确实为 SKILL.md，而不是 skill.md 或 SKILL.md.txt；
  2. 文件开头是否有完整 YAML frontmatter；
  3. description 是否为空或格式错误；
  4. Skill 是否放在当前版本可发现的用户级或项目级目录；
  5. 项目是否被信任，仓库级配置是否允许加载；
  6. 输入 /skills 后能否在列表中看到；
  7. 新增 Skill 后是否需要新建任务或按当前界面提示刷新；
  8. 是否把 AGENTS.md、MCP 配置误当成 Skill；
  9. 是否引用了不存在的脚本或本机专属绝对路径。

如果 /skills 完全看不到目标技能，先查目录和 frontmatter；如果能看到但执行方式不稳定，重点改 description、步骤边界和验收条件。涉及登录、配置层和客户端异常，可继续查看 Codex API 与 config.toml 排错。

三个实用 Codex Skill 方向 ​

代码审查 Skill ​

输入是需求、Diff 和测试结果，输出按严重程度列问题，并要求每条问题包含文件位置、影响和修复建议。可以结合 Codex 代码审查清单。

Bug 修复 Skill ​

固定流程是复现、定位、最小修复、添加回归测试、运行验证、总结风险。禁止顺手重构和扩大依赖。

SEO 发布 Skill ​

先查搜索意图和站内重复，再写文章、同步发现入口、构建、检查 canonical 与 Sitemap，最后返回完整 URL。它比单纯的“写一篇文章”提示词更容易稳定复用。

FAQ ​

Codex Skills 是插件吗 ​

不是。Skill 主要是一套可复用的任务说明；Plugin 可以打包 Skills、MCP、工具、资源和其他能力。只需要标准流程时，先写 Skill 通常更轻。

Skill 和 AGENTS.md 能同时用吗 ​

可以。AGENTS.md 负责仓库长期规则，Skill 负责某类任务流程。如果两者冲突，应按当前 Codex 的作用域和优先级规则处理，并检查嵌套目录中的 AGENTS.md。

Skill 可以自动调用脚本吗 ​

可以在 Skill 中说明应运行的仓库脚本或附带 scripts/，但脚本仍受当前沙箱、审批和权限设置限制。不要在脚本中硬编码密钥。

为什么别人安装的 Skill 我这里没有 ​

可能是作用域、目录、版本、产品形态或团队策略不同。先用 /skills 查看本机实际清单，再核对官方文档，不要假设每个客户端的技能完全相同。

相关教程 ​

本文依据 2026年8月4日的 Bing 结果、OpenAI Codex 官方仓库与公开文档整理。功能名称和目录规则可能继续变化，请以实际客户端和官方说明为准。

独立中文教程站，不是 OpenAI 官方网站。产品信息请以官方资料为准。

© 2026 gpt-codex.com · 关于本站 · 编辑规则 · 隐私声明