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

agent-skills 接入 Codex 实战插件安装、 调用与清单文件工作机制【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills本篇指南聚焦 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编码前先写规格说明speccode-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-skillsagent-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-skillsagent-skills注意第二条命令与远程方式完全相同marketplace 注册的是本地路径但插件标识符仍然是agent-skillsagent-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-skillsagent-skills中的名称即来自这里当前版本为0.6.8skills: ./skills/核心字段。告诉 Codex 去仓库根目录的skills/目录发现全部 skill这是两个平台共享同一目录的直接依据author/homepage/repository/license元数据供插件市场展示interface.capabilities声明插件需要的交互能力Interactive、Read、Writeinterface.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 采用相同的namedescriptionfrontmatter 约定因此同一个 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角色人格personasagents/ 目录下的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/目录零复制、零漂移统一的namedescriptionfrontmatter 让每个SKILL.md同时被 Codex 和 Claude Code 理解斜杠命令、personas 与生命周期钩子保留在 Claude Code 侧Codex 用户以skill-name直接调用 skill 作为等价替代。【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考