外观
Codex Skills 怎么用?安装、启用、创建与 GitHub 导入教程(2026)
如果你条件有限,强烈推荐国内 API 站
这是站主自主搭建纯 GPT API 站,无需梯子,实时更新 GPT 最新模型(仅支持电脑端),价格是官方的 三分之一,操作简单,连接稳定,价格便宜,保证没有任何掺水、收集信息等低劣行为,保证爽用 GPT。
Codex Skills 可以把一套经常重复的工作流程,封装成可发现、可触发、可复用的技能。它不只是保存一段 Prompt:一个 Skill 还可以携带脚本、参考资料、模板和界面元数据,让 Codex 在处理特定任务时按固定流程工作。
本文重点解决六个问题:
- Codex Skills 与普通 Prompt、
AGENTS.md、Plugin 有什么区别; - 2026 年应该从哪里安装 Skill;
- 如何从 GitHub 导入第三方 Skill;
- 如何启用、禁用和显式调用 Skill;
- 如何从零创建一个合格的
SKILL.md; - Skill 不触发、导入后不显示或执行异常时如何排查。
一句话结论:什么任务适合做成 Skill
如果一项工作同时符合下面三点,就值得做成 Skill:
- 会重复出现:例如代码审查、发布前检查、生成周报、处理 PDF 或部署项目;
- 有稳定流程:每次都需要读取相似资料、执行相似命令、检查相似结果;
- 需要专业资源:要配合脚本、规范、模板、API 文档或品牌素材。
只做一次的小任务,用当前 Prompt 更轻;只对某个仓库长期有效的规则,写进 AGENTS.md 更合适;需要把多个 Skills、MCP、Hooks 和资源一起分发时,再做 Plugin。
Codex Skills、Prompt、AGENTS.md 和 Plugin 的区别
这四个概念最容易混淆。可以把它们理解成四个不同层级:
| 载体 | 主要用途 | 典型作用范围 | 适合放什么 |
|---|---|---|---|
| 当前 Prompt | 描述这一次任务 | 当前对话或当前任务 | 目标、范围、限制、验收条件 |
AGENTS.md | 保存仓库长期规则 | 当前仓库或对应子目录 | 安装命令、测试命令、目录边界、代码规范 |
| Skill | 封装可复用任务流程 | 个人、项目或插件 | 操作步骤、脚本、参考资料、模板、验证方法 |
| Plugin | 分发一组 Codex 能力 | 个人、团队或市场 | Skills、MCP、Hooks、Commands、Apps、Assets |
举个例子:
- “修复这次登录 Bug,只改认证模块”属于当前 Prompt;
- “本仓库统一运行
npm test,不要改dist/”属于AGENTS.md; - “每次审查仓库都按架构、测试、安全、发布风险四部分输出”适合做成 Skill;
- “把代码审查 Skill、GitHub MCP 和团队图标一起安装”适合做成 Plugin。
本站已有单独的 Codex Prompt 与 AGENTS.md 最佳实践,本文不会重复列出 20 个任务 Prompt,而是专注 Skills 的安装、结构和触发机制。
2026 年官方 Skills 分发方式有什么变化
这一点很重要:OpenAI 的旧 openai/skills 仓库已经在 README 中标记为 deprecated,并建议读者查看新的 OpenAI Plugins 仓库和 Build plugins 文档。
这不等于“Skill 被取消”。变化的是公开分发方式:
- Skill 仍然以
SKILL.md为核心; - 本地个人 Skill 和项目 Skill 仍可被 Codex 发现;
- 面向团队或公开分发的新项目,官方更倾向使用“仅包含 Skills 的 Plugin”或更完整的 Plugin;
- 旧仓库里的系统、精选或实验 Skill 可能仍被部分版本和内置安装器引用,但不应再把旧目录当成长期发布的默认入口。
因此,本文把安装方式分成三条路线:
- 个人或项目自用:放进本地 Skills 目录;
- 导入已有 GitHub Skill:使用内置安装 Skill,或审查后手动复制;
- 团队或公开分发:封装为带
.codex-plugin/plugin.json的 Skill-only Plugin。
Codex 从哪些目录发现 Skills
当前 Codex 源码支持多个技能作用域。为了减少版本差异,新建 Skill 时优先使用下面三个位置。
1. 个人 Skills
适合你在多个项目中重复使用的流程:
text
~/.agents/skills/<skill-name>/SKILL.mdWindows 通常对应:
text
C:\Users\<你的用户名>\.agents\skills\<skill-name>\SKILL.md2. 项目 Skills
适合只在某个仓库中共享的技能:
text
<项目根目录>/.agents/skills/<skill-name>/SKILL.md项目 Skill 可以和仓库一起进行版本管理,团队成员拉取仓库后即可获得同一套工作流。不要在 Skill 中保存真实密钥、Cookie、生产地址或个人隐私数据。
3. Plugin 内的 Skills
适合团队安装或公开分发:
text
my-plugin/
├── .codex-plugin/
│ └── plugin.json
└── skills/
└── <skill-name>/
└── SKILL.md旧的 $CODEX_HOME/skills 还能用吗
当前源码仍为下面的位置保留了向后兼容:
text
$CODEX_HOME/skills/<skill-name>/SKILL.md未设置 CODEX_HOME 时,常见旧路径是 ~/.codex/skills/。部分内置安装器也可能继续写入这里。已经正常工作的旧 Skill 不必为了“追新”立即搬家;新建个人 Skill 时可以优先采用 ~/.agents/skills/,并以你当前 Codex 客户端显示的技能列表为最终判断。
如何安装 Codex Skills
方法一:使用 Codex 内置的 Skill Installer
在提供 $skill-installer 的 Codex 版本中,可以直接在对话里提出安装要求。它不是终端命令,而是对 Codex 的任务指令。
查看可安装内容:
text
$skill-installer 列出当前可以安装的 Skills安装指定 GitHub 目录:
text
$skill-installer install https://github.com/owner/repo/tree/main/path/to/skill也可以用自然语言说明:
text
使用 $skill-installer,从这个 GitHub 目录安装 Skill:
https://github.com/owner/repo/tree/main/path/to/skill内置安装器通常会把目录复制到个人 Skills 路径,并检查目标目录里是否存在 SKILL.md。不同 Codex 版本的默认目录、可用目录和刷新机制可能不同,以安装结果和当前客户端的 Skills 列表为准。
不要把任意 GitHub 仓库直接当成可信 Skill
Skill 会向 Codex提供操作说明,还可能携带可执行脚本。安装前至少检查 SKILL.md、scripts/、外部网络请求、依赖安装命令和文件写入范围。陌生 Skill 应先在测试仓库中运行。
方法二:手动复制到个人目录
如果 Skill 目录结构很简单,可以手动下载并复制:
text
~/.agents/skills/
└── repo-audit/
└── SKILL.md注意,必须复制整个 Skill 文件夹,不能只把多份 SKILL.md 平铺到 skills/ 根目录,否则脚本、参考资料和资源路径会失效。
复制后,在 Skills 列表中搜索 repo-audit。如果没有立即出现,可以:
- 新开一轮任务或新建对话;
- 使用客户端的刷新或重新加载 Skills 功能;
- 关闭并重新打开 Codex;
- 检查文件名是否严格为大写的
SKILL.md; - 检查 YAML frontmatter 是否完整。
方法三:放进项目 .agents/skills
如果 Skill 只服务当前仓库,推荐放到项目中:
text
your-project/
├── .agents/
│ └── skills/
│ └── release-check/
│ ├── SKILL.md
│ └── references/
│ └── release-policy.md
├── AGENTS.md
└── src/这里的分工是:
AGENTS.md说明这个仓库怎样安装、测试和交付;release-check/SKILL.md说明“如何执行一次发布检查”;references/release-policy.md保存更长的发布标准。
如何启用、禁用和调用 Skill
在界面中启用或禁用
支持 Skills 管理菜单的 Codex 客户端会提供类似 Enable/Disable Skills 的入口。关闭后,Skill 仍保留在磁盘上,但不会出现在当前可调用技能集合中。
这适合处理以下情况:
- 两个 Skill 的触发描述过于相似;
- 第三方 Skill 暂时不再使用;
- 某个 Skill 依赖当前没有配置的 MCP 或命令;
- 你想对比启用 Skill 前后的执行差异。
通过配置禁用
当前 Codex 配置结构也支持按名称或 SKILL.md 路径设置状态。例如:
toml
[[skills.config]]
name = "repo-audit"
enabled = false按路径设置时,填写该 Skill 的 SKILL.md 绝对路径:
toml
[[skills.config]]
path = "C:\\Users\\you\\.agents\\skills\\repo-audit\\SKILL.md"
enabled = false配置字段可能随版本演进。如果客户端已经提供可视化开关,普通用户优先使用界面管理,避免手写路径错误。
显式调用:最容易验证
安装后第一次测试,建议明确点名 Skill:
text
使用 $repo-audit 对当前仓库做只读审查,不要修改文件。传统 CLI 和部分客户端使用 $skill-name。采用新版提及选择器的客户端可能显示 @ 或技能卡片,直接从界面列表选中即可。不要死记符号,以输入框弹出的技能列表为准。
隐式触发:由 description 决定
Skill 也可以根据任务语义自动匹配。例如 description 写明“用户要求审查仓库且不修改文件时使用”,那么下面的请求就可能触发它:
text
检查这个项目有没有发布风险,只输出报告,不要改代码。隐式触发的关键不在正文第一段,而在 SKILL.md 顶部的 description。Codex 先看到名称和描述,选中 Skill 后才加载完整正文。
如何从零创建一个 Codex Skill
下面创建一个 repo-audit Skill,用于对代码仓库做只读审查。
第一步:确定名称和触发边界
官方创建规范建议:
- 名称使用小写字母、数字和连字符;
- 不要使用空格、下划线或连续连字符;
- 名称不超过 64 个字符;
- 文件夹名称与 Skill 名称保持一致;
description同时写清“做什么”和“什么时候使用”。
合适的名称:
text
repo-audit
release-check
gh-address-comments
pdf-form-filler不推荐:
text
My Skill
repo_audit
万能技能
do-everything-for-any-project第二步:创建最小目录
text
repo-audit/
└── SKILL.md一个 Skill 最少只需要这一份文件。先跑通最小版本,再决定是否增加脚本和参考资料。
第三步:填写 SKILL.md
可直接使用下面这个安全的最小示例:
md
---
name: repo-audit
description: Perform a read-only audit of an existing code repository and report actionable architecture, testing, security, and release risks. Use when the user asks to audit, review, or assess a repository without modifying files.
---
# Repository Audit
## Workflow
1. Read the applicable AGENTS.md files.
2. Inspect the repository structure and dependency manifests.
3. Review relevant source code, tests, configuration, and CI files.
4. Do not modify files, install packages, commit, push, or deploy.
5. Verify every finding against a concrete file or execution path.
## Output
- List findings first, ordered by severity.
- Include the affected file and a concise explanation.
- Separate confirmed defects from unverified risks.
- State which checks were not run and why.
- If there are no actionable findings, say so directly.这个例子有几个值得保留的特点:
description明确了“只读仓库审查”的触发场景;- 正文用操作流程,而不是长篇解释概念;
- 明确禁止修改、安装、推送和部署;
- 输出要求可验证,不强迫 Codex 凑出问题。
第四步:用 $skill-creator 辅助创建
如果当前 Codex 提供系统内置的 $skill-creator,可以让它生成目录、模板和界面元数据:
text
使用 $skill-creator 创建一个名为 repo-audit 的个人 Skill。
用途是对代码仓库进行只读审查,输出架构、测试、安全和发布风险;
不修改文件,不提交,不推送,不部署。$skill-creator 通常会协助完成:
- 规范化 Skill 名称;
- 创建
SKILL.md; - 按需创建
scripts/、references/和assets/; - 生成推荐的
agents/openai.yaml; - 运行基础验证器并修复结构问题。
如果你明确要求创建位置,它可以放进个人或项目 Skills 目录;未指定时,应先确认实际生成路径,避免把团队专用内容误放进个人全局目录。
一个完整 Skill 的推荐目录结构
复杂 Skill 可以按下面组织:
text
repo-audit/
├── SKILL.md # 必需:触发描述与核心流程
├── agents/
│ └── openai.yaml # 推荐:显示名称、简介、默认提示和策略
├── scripts/
│ └── collect_repo_info.py # 可选:可重复、确定性的辅助程序
├── references/
│ ├── security-checks.md # 可选:按需读取的详细知识
│ └── release-checks.md
└── assets/
└── report-template.md # 可选:复制或填充的输出模板四类文件的职责不要混在一起:
| 目录或文件 | 用途 | 是否自动全部加载 |
|---|---|---|
SKILL.md | 核心工作流和资源导航 | 触发后完整读取 |
scripts/ | 稳定、重复、需要确定性的操作 | 通常直接运行,必要时才阅读 |
references/ | 长文档、规范、API、业务知识 | 按任务需要读取 |
assets/ | 模板、图片、字体、样例工程 | 用于输出,不应当作说明书堆进上下文 |
不要为了显得“完整”创建空目录。没有脚本就不建 scripts/,没有模板就不建 assets/。
agents/openai.yaml 怎么写
agents/openai.yaml 是推荐但非最小必需的界面元数据。它可以提供用户可见名称、简短说明、图标、默认提示、工具依赖和调用策略。
示例:
yaml
interface:
display_name: "Repository Audit"
short_description: "Audit repository risks without changing files"
default_prompt: "Use $repo-audit to review this repository and list actionable risks."
policy:
allow_implicit_invocation: false这里把 allow_implicit_invocation 设为 false,代表它不应仅凭语义自动加入任务,但用户仍然可以通过 $repo-audit 显式调用。对于会修改生产系统、发送外部消息、操作付款或执行批量删除的高风险 Skill,关闭隐式调用更稳妥。
如果保留默认值或设为 true,Codex 可以根据 description 自动选择它。无论哪种方式,Skill 都不会因为写了说明就自动绕过审批、沙箱或用户权限。
可选的 MCP 依赖
需要 MCP 时,可以在同一文件声明工具依赖:
yaml
dependencies:
tools:
- type: "mcp"
value: "github"
description: "GitHub MCP server"
transport: "streamable_http"
url: "https://example.com/mcp"scripts、references 和 assets 应该怎么拆
适合放进 scripts 的内容
- 每次都会重写的相同代码;
- 对结果一致性要求高的转换操作;
- 文件扫描、格式校验、生成清单等机械流程;
- 已经有测试、参数和错误处理的辅助工具。
脚本必须实际运行测试。不要把未经审查的一行远程安装命令包装进 Skill,也不要默认读取用户主目录、浏览器数据或密钥文件。
适合放进 references 的内容
- API 参考和错误码;
- 数据库结构和业务术语;
- 公司政策、发布规范和审查标准;
- 不同框架或不同供应商的分支说明。
SKILL.md 应直接说明何时读哪一份 reference。例如:
md
- 审查认证代码时,读取 `references/security-checks.md`。
- 检查发布流程时,读取 `references/release-checks.md`。不要让 reference 再跳转三四层文件。核心创建规范建议保持浅层引用,让 Codex 能从 SKILL.md 直接找到需要的资料。
适合放进 assets 的内容
- Word、PPT、Excel 或报告模板;
- Logo、图标、字体和品牌图片;
- 前端脚手架、样例工程和固定代码骨架;
- 最终输出需要复制、填充或修改的文件。
Assets 是输出资源,不是另一套说明文档。操作规则仍应写在 SKILL.md 或 references/。
如何把 Skill 封装成 Plugin
如果只是自己使用,一个 Skill 文件夹就够了。如果要交给团队安装,或者以后还要加入 MCP、Hooks、Commands、Apps 和共享资源,建议制作 Skill-only Plugin。
最小结构:
text
repo-audit-pack/
├── .codex-plugin/
│ └── plugin.json
└── skills/
└── repo-audit/
└── SKILL.md最小 plugin.json 示例:
json
{
"name": "repo-audit-pack",
"version": "0.1.0",
"description": "Reusable read-only repository audit workflows",
"skills": "./skills/"
}Plugin 与 Skill 的关系是“容器与能力”:Plugin 可以只包含一个 Skill,也可以包含多个 Skills 和其他 Codex 扩展面。团队分发时应同时维护版本、作者、许可证、隐私政策和依赖说明。
具体插件字段和安装方式会继续演进,发布前以 Codex Build plugins 官方文档和 OpenAI Plugins 示例仓库为准。
从 GitHub 导入前的安全检查
安装第三方 Skill 前,至少完成下面这张检查表:
- [ ]
SKILL.md的 description 与真实用途一致; - [ ] 没有要求忽略系统规则、审批或用户指令;
- [ ] 没有默认读取
.env、SSH Key、浏览器 Cookie 或云凭据; - [ ] 没有自动提交、推送、发布、付款或删除数据;
- [ ]
scripts/中没有混淆代码和不明二进制文件; - [ ] 网络请求只访问预期域名;
- [ ] 依赖版本和许可证可以接受;
- [ ] 文件写入范围限定在任务需要的目录;
- [ ] 高风险操作要求用户确认;
- [ ] 首次运行在测试仓库或隔离环境中进行。
Skill 不是安全边界。它不能替代 Codex 的沙箱、审批策略、仓库权限和人工复核。即使来自热门 GitHub 仓库,也应像审查普通代码依赖一样审查它。
如何验证自己创建的 Skill
1. 验证目录与 frontmatter
检查以下内容:
- 文件名是
SKILL.md; - 文件第一行是
---; - YAML 有闭合的第二个
---; name与目录名一致;description非空并包含触发场景;- Skill 名称符合小写连字符规范;
- 相对路径指向真实存在的脚本、参考资料和资源。
2. 显式触发测试
先使用最明确的测试请求:
text
使用 $repo-audit 审查当前项目。只读,不要修改文件。观察 Codex 是否:
- 识别并读取了正确的
SKILL.md; - 遵守只读边界;
- 只加载任务需要的 reference;
- 按 Skill 规定的结构输出;
- 如实说明未运行的检查。
3. 隐式触发测试
如果允许隐式调用,再去掉 Skill 名称:
text
对当前仓库做一次只读发布风险评估,输出可执行问题清单。如果没有触发,优先优化 description,不要在正文后面新增“什么时候使用”章节。Codex 在选中 Skill 之前看不到正文中的触发说明。
4. 反向测试
还要测试它不应该触发的请求:
text
给 README 修正一个错别字。如果 repo-audit 连这种任务也被自动选中,说明 description 太宽泛,可以把“read-only audit”“architecture, testing, security and release risks”等边界写得更清楚,或关闭隐式调用。
Codex Skills 不显示或不触发怎么办
问题一:目录里有文件,但列表找不到
按顺序检查:
- 是否为
<skills-root>/<skill-name>/SKILL.md; - 文件名大小写是否正确;
- YAML frontmatter 能否解析;
description是否为空;- 当前工作目录是否处于项目 Skill 的作用范围内;
- Skill 是否被界面或配置禁用;
- 重开任务或重启客户端后是否出现。
问题二:显式点名仍没有加载
可能原因包括:
- 名称拼写与 frontmatter 不一致;
- 同名 Skills 来自不同路径,纯名称可能产生歧义;
- 使用了当前客户端不支持的提及符号;
- Skill 已被禁用;
SKILL.md无法读取或超过当前环境权限范围。
可以从 Skills 列表直接选中目标,避免手打同名 Skill。
问题三:导入后脚本找不到
常见原因是只复制了 SKILL.md,没有复制完整目录;或者 Skill 使用了错误的绝对路径。
Skill 内引用应该以 Skill 文件夹为基准:
text
scripts/check.py
references/policy.md
assets/template.docx不要把作者电脑上的路径写死为:
text
C:\Users\author\Desktop\skill\scripts\check.py问题四:Skill 总是误触发
处理顺序:
- 缩窄 description 的任务类型;
- 增加明确的触发对象和排除边界;
- 拆分过于宽泛的“大而全 Skill”;
- 在
agents/openai.yaml中关闭隐式调用; - 暂时从 Skills 管理界面禁用。
问题五:Skill 触发了,但结果仍不稳定
Skill 不是把每一步都写得越死越好。先判断任务需要哪种自由度:
- 多种方案都合理:用原则和决策条件;
- 有固定模式但允许变化:用伪代码或参数化脚本;
- 操作脆弱且必须一致:提供已测试脚本和严格验证顺序。
同时删除 Skill 中无用的背景知识。过长的 SKILL.md 会占用上下文,详细材料应拆到 references/ 按需读取。
常见错误写法
把所有知识都塞进 SKILL.md
Skill 的正文应该是核心流程和资源导航,而不是复制整套 API 文档。官方创建指南建议控制正文长度,并通过渐进式加载减少无关上下文。
只写“你是一个专家”
下面这种 description 几乎无法准确触发:
yaml
description: You are a world-class software expert.更好的写法要说明任务和触发场景:
yaml
description: Review a TypeScript web application for concrete accessibility defects. Use when the user asks for an accessibility audit of UI code, components, or pages.在 Skill 中重复整个 AGENTS.md
仓库命令和目录规则应由 AGENTS.md 维护,Skill 只需要求“先读取适用的 AGENTS.md”。两份规则长期复制,会出现版本不一致和冲突。
默认授权高风险操作
不要在通用 Skill 中写“自动提交、自动推送、自动部署、发现无用目录就删除”。真正需要发布或生产变更的 Skill,应把权限、审批、验证和回滚条件写清楚。
安装后从不复测
模型、客户端、工具接口和项目结构都会变化。应定期用真实任务测试 Skill,并更新过期的命令、路径、依赖和参考资料。
常见问题 FAQ
Codex Skills 是插件吗
不是同一个概念。Skill 是一套可复用任务说明和资源;Plugin 是安装与分发容器,可以包含一个或多个 Skills,也可以带 MCP、Hooks、Commands、Apps 和 Assets。
只有 Codex CLI 能用 Skills 吗
Skills 是 Codex 的扩展能力,不同客户端的列表入口、提及符号、安装与刷新方式可能不同。以当前客户端显示的 Skills 列表和官方文档为准。
创建 Skill 必须会 Python 吗
不需要。最小 Skill 只有一份 Markdown 格式的 SKILL.md。只有在流程需要稳定自动化时,才增加 Python、PowerShell、Bash 或其他脚本。
name 可以写中文吗
官方创建工具建议使用小写英文字母、数字和连字符,并限制在 64 个字符内。面向用户的中文名称可以放到 agents/openai.yaml 的 interface.display_name。
Skill 能自动获得全部文件和网络权限吗
不能。Skill 提供工作流程,不会绕过 Codex 的沙箱、审批、文件权限、网络限制、账号权限和组织策略。
从 GitHub 安装后需要重启吗
不同版本行为不同。有些版本会在下一轮任务或 Skills 刷新后出现,有些旧版本需要重启。安装完成后先查看技能列表;未出现时再重开任务或客户端。
为什么明确写了 description 还是不会自动触发
先确认 Skill 已启用,再检查 description 是否同时包含“做什么”和“何时使用”。如果 allow_implicit_invocation 被设为 false,它只能通过技能列表或显式提及调用。
能把公司内部文档放进 references 吗
可以,但要遵守公司数据政策和仓库访问控制。不要放真实密钥、个人信息和超出使用范围的客户数据;安装到个人全局目录前也要确认这些资料是否允许跨项目使用。
推荐学习顺序
如果你刚开始使用 Codex,可以按下面顺序学习:
- Codex 下载、安装、配置保姆级教程
- Codex 写代码项目实战
- Codex Prompt 与 AGENTS.md 最佳实践
- 本文:把重复工作封装成 Skills
- 需要团队分发时,再学习 Plugin、MCP 和 Hooks
国内账号、API 与第三方产品的边界,可查看 Codex 国内怎么用。
官方资料与核验来源
- Using skills in Codex
- Create custom skills in Codex
- Build plugins for Codex
- OpenAI Codex 官方 GitHub
- OpenAI Plugins 示例仓库
- 旧 OpenAI Skills 仓库(仓库当前已标记弃用,用于核对迁移说明)
总结
Codex Skills 最有价值的地方,不是把一段 Prompt 换个文件保存,而是把触发条件、工作流程、专业资料、确定性脚本和验证标准组合成可复用能力。
个人自用可以放在 ~/.agents/skills/,项目专用可以放进 .agents/skills/,从 GitHub 导入前必须审查脚本和权限;需要交给团队或公开分发时,则应顺着当前官方方向封装为 Skill-only Plugin。
第一次创建时,从一个边界清晰、只读、容易验收的小 Skill 开始。显式触发跑通后,再测试隐式匹配、增加 references 或 scripts,比一开始制作“大而全”的万能 Skill 更可靠。