agent-skills 接入 Codex 实战：插件安装、@ 调用与清单文件工作机制

2026-09-05 23:43:03作者：晏闻田Solitary

本篇指南聚焦 docs/codex-setup.md 讲解的主题：如何把 agent-skills 仓库作为原生 Codex 插件安装到你的 Codex CLI，并理解安装背后的清单文件结构与调用机制。读完后，你可以独立完成远程/本地克隆两种安装方式，掌握 @ 前缀调用任意 skill 的方法，并看懂 .codex-plugin/plugin.json、.agents/plugins/marketplace.json 两份关键清单是如何让 Codex 与 Claude Code 共享同一份 skills/ 目录的。

一、核心前提：一份 skills 目录，两个平台消费

agent-skills 仓库本身就是一个 Codex 插件。它的核心设计是：Claude Code 使用的根级 skills/ 目录会被 Codex 直接消费，安装过程中不会复制、不会生成任何副本文件。这意味着两个平台读的是同一批 skills/<name>/SKILL.md，维护一份即可同时服务两端。

仓库内 skills/ 目录下共有 25 个 skill，覆盖从需求规格到上线发布的完整研发流程，例如：

spec-driven-development：编码前先写规格说明（spec）；
code-review-and-quality：合并前的多维度代码审查；
test-driven-development：红-绿-重构循环；
performance-optimization、security-and-hardening、shipping-and-launch 等。

README.md 的 Codex 小节同样强调：Codex 通过 .codex-plugin/plugin.json 直接读取根目录的 skills/ 目录。

二、安装插件（远程仓库方式）

要求 Codex CLI v0.122 或更高版本。两条命令依次执行：

codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills

两条命令的分工是明确的：

第一条把这个仓库注册为一个名为 agent-skills 的 marketplace（插件市场）；
第二条从该 marketplace 中安装并启用 agent-skills 插件。

安装完成后，必须启动一个新的 Codex 会话，skill 才会被发现（discovered）并可用。

版本注意：在 v0.122 之前的旧版本 Codex CLI 中，命令是 codex marketplace add（没有 plugin 子命令）。如果执行报错，先检查 CLI 版本是否过旧。

三、本地克隆安装

如果你在开发、调试这份仓库，或者网络环境不便直连远程仓库，可以直接用本地克隆：

codex plugin marketplace add /path/to/your/clone
codex plugin add agent-skills@agent-skills

注意第二条命令与远程方式完全相同：marketplace 注册的是本地路径，但插件标识符仍然是 agent-skills@agent-skills。之所以能这样工作，与仓库内 marketplace 清单的声明方式有关——见下文第四节。

四、工作原理：三个关键文件

原文档用三个文件解释整个集成机制，下面逐一展开，并给出仓库中的真实文件内容。

4.1 .codex-plugin/plugin.json —— Codex 插件清单

.codex-plugin/plugin.json 是 Codex 识别本仓库为插件的入口文件。它把 skills 字段指向 ./skills/，并提供 Codex 所需的完整元数据。真实内容如下：

{
  "name": "agent-skills",
  "version": "0.6.8",
  "description": "Production-grade engineering skills for AI coding agents covering the full software development lifecycle from spec to ship.",
  "author": { "name": "Addy Osmani", "url": "https://github.com/addyosmani" },
  "homepage": "https://github.com/addyosmani/agent-skills",
  "repository": "https://github.com/addyosmani/agent-skills",
  "license": "MIT",
  "skills": "./skills/",
  "interface": {
    "displayName": "Agent Skills",
    "shortDescription": "Senior-engineer workflows for AI coding agents: spec, plan, build, test, review, ship.",
    "longDescription": "Agent Skills bundles 24 production engineering workflows from Addy Osmani, covering requirements, planning, implementation, testing, review, and shipping.",
    "developerName": "Addy Osmani",
    "category": "Productivity",
    "capabilities": ["Interactive", "Read", "Write"],
    "defaultPrompt": [
      "Help me choose the right engineering workflow for this task",
      "Plan and implement this change using the relevant Agent Skills"
    ]
  }
}

逐字段说明：

字段	作用
`name` / `version`	插件标识。安装命令 `codex plugin add agent-skills@agent-skills` 中的名称即来自这里；当前版本为 `0.6.8`
`skills: "./skills/"`	核心字段。告诉 Codex 去仓库根目录的 `skills/` 目录发现全部 skill，这是"两个平台共享同一目录"的直接依据
`author` / `homepage` / `repository` / `license`	元数据，供插件市场展示
`interface.capabilities`	声明插件需要的交互能力：`Interactive`、`Read`、`Write`
`interface.defaultPrompt`	安装后在 Codex 中提供的默认提示语模板

对比来看，仓库根目录另有一份 plugin.json（仅含 name、version、description 三个字段），它是 Claude Code 侧的插件清单；.claude-plugin/ 目录下的 plugin.json、marketplace.json 则服务于 Claude Code 的 /plugin 市场机制。两套清单各自独立，互不影响。

4.2 .agents/plugins/marketplace.json —— marketplace 条目

.agents/plugins/marketplace.json 是声明"本仓库可作为 marketplace 源"的条目。真实内容：

{
  "name": "agent-skills",
  "interface": { "displayName": "Agent Skills" },
  "plugins": [
    {
      "name": "agent-skills",
      "version": "0.6.8",
      "description": "Production-grade engineering skills covering every phase of software development: spec, plan, build, verify, review, and ship.",
      "source": {
        "source": "local",
        "path": "./"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

要点解析：

source.path: "./" 声明仓库根目录就是插件源。因此无论是 codex plugin marketplace add addyosmani/agent-skills（远程克隆后根目录即 ./）还是 codex plugin marketplace add /path/to/your/clone（本地克隆），Codex 都能用同一份 marketplace.json 找到插件，且插件标识符保持一致。
policy.installation: "AVAILABLE" 表示该插件可直接安装；policy.authentication: "ON_INSTALL" 表示认证发生在安装时。

4.3 skills//SKILL.md —— 两端共享的 skill 格式

skill 文件本身没有任何平台专属改动。以 skills/spec-driven-development/SKILL.md 为例，其 YAML frontmatter 形如：

---
name: spec-driven-development
description: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. ...
---

Codex 与 Claude Code 采用相同的 name + description frontmatter 约定，因此同一个 SKILL.md 文件同时服务两个平台：name 决定调用标识，description 决定 agent 在自然语言场景下如何判断该 skill 是否适用（何时使用、何时不使用都写在描述和正文里）。这也是整个仓库"多平台一份内容"设计的根基。

五、日常使用：@ 调用与自然语言触发

安装并重启会话后，有两种方式使用 skill：

显式调用：在 Codex 聊天中用 @ 前缀指定 skill，例如 @spec-driven-development。全部 25 个 skill 均可用，命名与 skills/ 下的目录名一一对应；
隐式触发：直接用自然语言描述任务（比如"帮我评审一下这个 diff"），由 Codex 根据各 skill 的 description 自行挑选合适的 skill。

六、能力边界：哪些是 Claude Code 专属的

这一点是原文档特意强调的，也是 Codex 用户最容易踩坑的地方。以下三类内容仍然是 Claude Code 专属，不会随插件带入 Codex：

内容	所在位置	在 Codex 中的替代方式
斜杠命令	.claude/commands/ 下的 `spec.md`、`plan.md`、`test.md`、`review.md`、`ship.md`、`webperf.md` 等	直接调用底层 skill：用 `@spec-driven-development` 替代 `/spec`，用 `@test-driven-development` 替代 `/test`
角色人格（personas）	agents/ 目录下的 `code-reviewer.md`、`security-auditor.md` 等	无直接等价物，按 skill 调用
生命周期钩子	hooks/ 目录（如 hooks/hooks.json 声明的 `SessionStart` 钩子）	不适用

也就是说：Codex 侧拿到的是"纯 skill 能力"，而 Claude Code 侧额外拥有命令包装层、人格与钩子。如果你在 Codex 中找不到 /spec 这类斜杠命令，这不是安装失败，而是按设计如此。

七、验证安装是否成功

完成安装后的验证步骤：

启动一个新的 Codex 会话（旧会话不会发现新装的 skill）；
输入 @，确认补全列表中出现 spec-driven-development、code-review-and-quality 等 25 个 skill 名称；
输入一句自然语言任务，观察 Codex 是否自动选中了对应 skill；
若命令执行即报错，先确认 Codex CLI 版本 ≥ v0.122，旧版本需改用 codex marketplace add 的旧命令形式，或升级 CLI 后按本文第二节的命令重新安装。

小结

agent-skills 的 Codex 接入遵循一条清晰的主线：

.agents/plugins/marketplace.json 让仓库根目录成为合法的插件源，支撑远程与本地克隆两种安装路径；
.codex-plugin/plugin.json 中的 skills: "./skills/" 让 Codex 直接消费根级 skills/ 目录，零复制、零漂移；
统一的 name + description frontmatter 让每个 SKILL.md 同时被 Codex 和 Claude Code 理解；
斜杠命令、personas 与生命周期钩子保留在 Claude Code 侧，Codex 用户以 @skill-name 直接调用 skill 作为等价替代。