Codex Skills怎么安装和创建？SKILL.md目录、触发方式与安全检查【2026年8月】

最后更新：2026-08-18

国内 Codex 与多模型 API 开发工具推荐

国内进行 Codex、代码、脚本或多模型 API 开发时，可以按任务选择以下第三方工具：

• 💻 Codex/编程训练（apibest）： apibest.orgCodex、代码、长文本和开发任务。
• 🔌 API/脚本接入（ZeoAPI）： zeoapi.com多模型 API 接入、脚本和原型测试。

以上均为邀请链接。apibest 与 ZeoAPI 均为第三方服务，不是相关模型厂商的官方网站或官方产品；所列型号与能力来自平台标称，具体功能与可用性以登录后的实际页面为准。请勿上传账号密码、API Key、合同或其他敏感资料。

本站为独立教程博客，并非 OpenAI 或 Codex 的官方网站，也不提供 AI 模型对话功能。文中涉及的目录路径、命令与功能均以官方文档和你本机的实际版本为准。

Codex Skills 是一种把可复用的说明、脚本和参考资源打包成“技能目录”的机制：你在一个目录里放一个 SKILL.md 主文件（可选再加脚本、模板、参考文档），Codex 在处理相关任务时可以自动匹配或被你显式点名调用这个技能，从而避免每次都重复粘贴同一段长提示。它适合解决的是“同一类工作流需要被反复执行、且步骤或规范比较固定”的场景，例如按团队规范生成提交信息、按固定模板做代码审查、执行某类重复的脚手架操作。

需要先说清一个前提：Codex 是一组持续迭代的编程工具，Skills 的具体读取目录、文件字段和触发细节可能随版本变化。本文给出的是官方仓库示例所展示的通用结构和思路，涉及路径与命令时请以你本机 codex 版本的文档为准，不要把某个版本观察到的规则当成永远固定的标准。

Codex Skills、普通提示词、AGENTS.md 与 MCP 的区别

很多人一开始会把 Skills 和其他几个概念混在一起。它们解决的问题层面并不一样：

机制	主要作用	生命周期	典型内容
普通提示词	单次告诉模型这次要做什么	一次性，用完即散	临时输入的自然语言指令
AGENTS.md	给某个仓库/项目设定长期的上下文与规范	跟随项目长期存在	项目约定、目录说明、注意事项
Codex Skills	封装可复用的工作流、说明与资源	可跨任务反复调用	SKILL.md、脚本、模板、参考文档
MCP	连接外部工具与数据源	作为外部能力接入	数据库、内部 API、文件服务等连接

一句话概括：AGENTS.md 回答“这个项目是什么、有哪些规矩”，Skills 回答“遇到这类任务应该怎么一步步做”，MCP 回答“怎么去访问外部的工具和数据”。MCP 负责连接外部工具与数据，Skill 主要封装可复用说明、资源和工作流，两者可以组合使用，但不是同一个概念，也不能互相替代。理解这一点后，你才能判断某个需求到底该写成一个 Skill，还是该配置一个 MCP，还是只需要在 AGENTS.md 里补一条约定。

技能目录与 SKILL.md 最小结构

官方仓库里保留了 docs/skills.md 文档，并链接到 developers.openai.com 上的 Skills 说明。OpenAI 当前源码显示，技能目录会根据作用范围从不同位置加载，而不是只有一个固定路径：

作用范围	当前可核验路径	适合场景
用户级	~/.agents/skills/<skill-name>/SKILL.md	多个项目都要使用的个人技能
仓库级	<项目目录>/.agents/skills/<skill-name>/SKILL.md	跟随仓库共享的团队工作流
项目配置级	<项目配置目录>/skills/<skill-name>/SKILL.md	由项目 Codex 配置层管理；官方仓库自身使用 .codex/skills/
旧版兼容	$CODEX_HOME/skills/<skill-name>/SKILL.md	仍可读取，但源码已标注为旧用户技能路径

Windows 中的 ~/.agents/skills 通常对应 %USERPROFILE%\.agents\skills。无论放在哪个作用域，每个技能都应使用独立子目录，并以 SKILL.md 作为必需入口文件。

一个最小可用的技能目录大致是这样：

.agents/
  skills/
    commit-message/
      SKILL.md

SKILL.md 通常包含一段清晰的技能描述和执行说明。核心是把三件事写明白：

• 这个技能是干什么的（名称与描述，用于语义匹配）；
• 什么时候应该用它（触发条件、适用场景）；
• 具体怎么做（步骤、约束、输出格式）。

一个示意性的最小 SKILL.md：

---
name: commit-message
description: 根据暂存区改动生成符合团队规范的提交信息；当用户要求写 commit message 或准备提交代码时使用。
---

# Commit Message Helper

1. 查看当前暂存的改动摘要。
2. 按 <类型>(<范围>): <简述> 的格式给出标题。
3. 正文分点说明改了什么、为什么改。

根据 OpenAI 官方仓库当前示例，SKILL.md 需要 YAML frontmatter，其中至少包含 name 和 description；正文再写工作流、约束和输出方式。官方示例还可能使用可选的 metadata，具体支持字段仍应以当前官方文档为准。

如何安装一个已有的 Codex Skill

安装现成技能，本质上就是把别人写好的技能目录放到你本机 Codex 能读取的技能目录下。通用流程如下：

1. 确认来源可信，拿到完整的技能目录（含 SKILL.md 和可选的 scripts、references、templates）。
2. 根据作用范围选择目录：只给当前仓库使用就放在项目的 .agents/skills/，跨项目使用则放在用户的 ~/.agents/skills/；已有 .codex/skills/ 项目按当前配置继续维护即可。
3. 把技能子目录整体复制进去，保持 SKILL.md 在子目录内。
4. 打开 SKILL.md 和 scripts 目录逐行审阅内容（安全检查见后文）。
5. 重新在该项目里发起相关任务，验证技能能否被识别。

如果你还没有装好 Codex 本体，或不清楚 CLI、插件如何登录，可以先看站内的 Codex下载安装教程2026：Codex CLI Windows、macOS、Linux登录与报错解决 和 Codex VS Code插件教程2026：安装、登录、Cursor/Windsurf使用与常见问题，把基础环境跑通再来配置技能。

需要提醒的是，网上关于“技能商店”“默认内置多少个技能”的说法差异很大，本文不对具体数量、默认启用范围或账户权益做承诺，请以你实际版本里能看到的为准。

如何从零创建一个自定义 Skill

从零写一个技能，建议按“先能跑、再优化触发、最后加资源”的顺序推进：

1. 在选定的技能根目录下新建一个语义清晰的目录名，例如项目级 .agents/skills/code-review/。
2. 在其中创建 SKILL.md，先写好名称、描述、适用场景和最核心的几步操作。
3. 用一个真实任务测试：直接点名让 Codex 使用这个技能，看步骤是否被正确执行。
4. 根据结果打磨描述文字，让它更容易被语义匹配，同时收紧步骤和输出约束。
5. 如果流程里有固定脚本或模板，再拆分到 scripts、templates 子目录，从 SKILL.md 引用它们。

写描述时有个实用原则：描述既要给人看懂，也要让模型能据此判断“当前任务是否该用它”。因此描述里最好包含具体的触发信号词，比如“当用户要求做代码审查、review PR、检查改动风险时”，而不是只写一句“帮助审查代码”。

如何通过名称、描述和任务语义触发技能

技能的触发通常有两条路径：显式调用和自动匹配。

• 显式调用：你在对话里直接指名要用哪个技能，这是最稳定、最可预期的方式，也便于调试。
• 自动匹配：Codex 根据技能的名称与描述，判断它是否适合当前任务，并在合适时自动采用。

要让自动匹配更可靠，关键在于把名称和描述写得“任务导向”：

• 名称用动作或场景命名，避免过于抽象；
• 描述里明确列出触发场景和典型说法；
• 步骤中避免与其他技能高度重叠的措辞，减少混淆。

调试期建议先固定用显式调用确认技能逻辑正确，再逐步依赖自动匹配，这样出问题时更容易定位是“逻辑问题”还是“匹配问题”。

scripts、references、templates 等可选资源怎么组织

当一个技能不只是说明、还需要携带脚本或素材时，可以在技能目录下再分子目录。常见的组织方式：

• scripts/：放可执行脚本，供技能在步骤中调用；
• references/：放参考文档、规范、示例说明，供模型阅读；
• templates/：放输出模板，例如固定格式的报告、提交信息模板。

组织资源时的几条建议：

• 在 SKILL.md 里用相对路径引用这些资源，保持目录自包含、可整体拷贝；
• 每个脚本都要能被人快速读懂它做了什么，避免黑盒；
• 参考文档尽量精简，只放与该技能直接相关的内容，过长的资料会稀释重点。

结构清晰的好处是：技能可以整目录分享、复用和版本管理，别人拿到后也能一眼看懂它依赖了哪些资源。

技能不触发、读取失败或结果不稳定怎么排查

遇到技能相关问题，可以按下面的顺序排查，避免在同一处反复试错：

• 技能完全不被识别：先确认目录结构和文件名是否符合当前版本要求，SKILL.md 是否在正确的技能子目录内；再确认你用的是不是支持 Skills 的 Codex 版本。
• 技能存在但不自动触发：多半是名称/描述太模糊。先用显式调用确认逻辑没问题，再回头把描述改得更贴近真实任务说法。
• 步骤执行了但结果不稳定：说明 SKILL.md 的步骤和输出约束不够具体，补充明确的格式要求、边界条件和反例。
• 引用的脚本或模板读取失败：检查相对路径是否正确、资源是否随技能目录一起拷贝、文件是否有权限问题。
• 多个技能互相抢占：把描述里重叠的措辞区分开，或在调试期只保留一个技能验证。

如果怀疑不是技能问题，而是 Codex 本体登录、网络或服务波动，可以对照官方状态页 https://status.openai.com/ 排查，并参考站内 OpenAI Codex是什么？Codex官网入口、CLI、App与使用教程（2026最新） 复核基础环境。

第三方 Skill 安装前的权限、脚本、网络与密钥安全检查

技能目录里可能包含会被真实执行的脚本，因此安装第三方技能前一定要审阅内容。建议逐项核对以下清单：

• 阅读全部脚本：确认 scripts/ 下每个脚本的实际行为，警惕删除、覆盖、批量修改等破坏性操作。
• 检查网络行为：留意脚本或步骤里是否有把本地文件、代码或环境变量外发到陌生地址的动作。
• 保护密钥：绝不因为技能“要求”就把 API Key、Token 粘进任何文件。示例里只应出现 <YOUR_API_KEY>、[REDACTED_API_KEY] 这类占位符，任何要你填入真实密钥并上传的技能都要高度警惕。
• 控制权限范围：优先在隔离目录或测试项目里试跑，别一上来就在核心仓库启用。
• 核对来源：优先使用官方仓库或可信作者的技能，避免来路不明的“合集”“增强版”。

常见避坑清单：

• 不要盲目信任“描述写得很正规”的技能，描述可信不代表脚本安全；
• 不要在生产分支直接测试未审阅的技能；
• 不要把敏感仓库的访问凭证交给不明技能；
• 不要忽略脚本里被拼接的命令，注意变量替换是否可能被注入。

关于官方来源，可核验的入口包括开发者文档 https://developers.openai.com/codex/skills/ 与官方仓库文档 https://github.com/openai/codex/blob/main/docs/skills.md，示例技能目录见 https://github.com/openai/codex/tree/main/.codex/skills。这些页面的具体内容会随版本更新，请以你打开时的实际文档为准。

适合中文用户的真实工作流示例

下面给一个贴近国内团队的落地思路，帮助你把 Skills 用在真实项目里：

1. 先在项目根目录建立 .agents/skills/，规划几个高频技能，例如 commit-message、code-review、changelog；需要个人跨项目复用时再放到 ~/.agents/skills/。
2. 每个技能先写最小 SKILL.md，用中文写清团队规范（提交格式、审查关注点、变更日志结构）。
3. 用最近一次真实改动逐个测试，先显式调用确认可用，再放开自动匹配。
4. 把团队里反复口头强调的规范沉淀进 references/，减少每次重复解释。
5. 通过 Git 管理整个 .codex/skills/ 目录，让新同事拉下来即用。

如果你还在权衡用 Codex、Cursor 还是 Claude Code 承载这类工作流，可以参考站内对比 Codex vs Cursor vs Claude Code 2026：AI编程工具怎么选？功能、场景与国内使用对比，以及国内使用注意事项 Codex国内怎么用？Codex国内版、中文使用、代码改造与安全指南（2026）。

常见问题

Codex Skills 和普通提示词有什么区别？ 普通提示词是一次性输入，用完即散；Skill 把一段可复用的说明、脚本和资源固化成一个技能目录（通常是 SKILL.md 加可选资源），可以在多个任务里被反复调用或自动匹配，减少每次重复粘贴长提示的成本。

SKILL.md 必须放在哪个目录？ 当前 OpenAI 源码支持多种作用域：用户级可放在 ~/.agents/skills/<skill-name>/SKILL.md，仓库级可放在项目内的 .agents/skills/<skill-name>/SKILL.md；项目配置目录下的 skills/ 也会被加载，官方 Codex 仓库自身就使用 .codex/skills/。旧的 $CODEX_HOME/skills 仍兼容但已标记为旧路径。具体优先级以当前官方文档和本机版本为准。

Codex Skills 和 MCP 是一回事吗？ 不是。MCP 负责让 Codex 连接外部工具和数据源（如数据库、内部 API、文件系统服务），Skill 主要封装可复用的说明、脚本和工作流。两者可以组合使用，但解决的是不同层面的问题，不能互相替代。

安装第三方 Skill 安全吗？ 取决于技能内容。Skill 里可能包含会被执行的脚本、会访问网络的命令，或诱导你交出密钥的说明。安装前应逐条阅读 SKILL.md 和 scripts 目录，确认没有可疑的外发网络、密钥读取或破坏性命令，最好先在隔离环境试跑。

为什么我的 Skill 没有被触发？ 常见原因是技能的名称和描述写得太模糊，导致语义匹配不到当前任务；或者目录结构、文件名不符合当前版本要求；也可能需要显式指名调用。可以先用明确指令点名这个技能，再回头优化描述文字。

Codex Skills 在国内能用吗？ Skill 本身是本地的目录和文件，能不能用取决于你本地的 Codex 是否已经正常登录和联网。网络访问、账号登录属于 Codex 使用层面的问题，与技能机制无关，可参考站内的 Codex官网入口与下载教程：安装、CLI、国内使用和中文指南。