Codex Skills+MCP 插件开发教程:从 SKILL.md 到可安装 Plugin

如果你在 Codex 里反复干同一类活——代码审查、仓库分析、发布检查、Issue 排查、日志分析，还在靠复制一大段长 Prompt 来复用，那这篇是给你的。

Codex 现在有了一套更工程化的方案:Skills ＋ MCP ＋ Plugin。它们各管一层,别搞混:

Skill 管"这件事该怎么做"（用 SKILL.md 定义流程）· MCP 管"Codex 能访问哪些真实系统"（GitHub/CI/Sentry/数据库）· Plugin 管"安装、组合与分发"（把 Skills、MCP、Hooks 打包成一个可安装能力）。

⚠️ 本文的 repo-insight 示例、Tool 命名、测试矩阵、企业权限建议属于实施建议;SKILL.md 结构、.agents/skills 发现路径、.codex-plugin/plugin.json、Marketplace 命令等均来自 OpenAI 官方文档。

✦ 什么时候用 Skill，什么时候才升级到 Plugin？

一个核心判断——别过早 Plugin 化：

只在一个仓库用的重复流程
→ 先放 .agents/skills/<name>/SKILL.md，一个文件就够，别一上来做 Plugin
需要真实数据/操作
→ 加 MCP Server（连 GitHub、CI、Sentry、只读数据库）
要跨仓库复用、给团队安装、绑 MCP、进 Directory
→ 才用 .codex-plugin/plugin.json 打包成 Plugin

一个 20 行说明、只在一个 repo 用的流程 → 优先 Skill;需要"3 个 Skill + 2 个 MCP + Hooks + Logo + 团队安装"→ 才真正适合 Plugin。

✦ Skill：为什么比长 Prompt 好？

核心是 Progressive Disclosure（渐进式披露）：Codex 启动时不会把所有 Skill 正文塞进上下文，它先只读 name、description、path，任务匹配上了再加载完整 SKILL.md。

这就是为什么 description 极其重要——它决定 Skill 什么时候被触发。
❌ description: Repository helper.（太模糊，Agent 不知道何时用）
✅ description: 分析陌生仓库、梳理架构、识别模块/风险/测试/下一步。用于代码库上手、仓库审计;不要用于实现功能。

Skill 目录核心只有 SKILL.md 必需，里面写清 Goal、Workflow、以及一个 Safety 段（不许 push、不许发布、不许改生产、不许暴露 secret）。

✦ MCP：让 Skill 接上真实系统

Skill 能说"检查 CI 是否通过"，但 Codex 没有 CI 工具就只能瞎猜。MCP 解决的正是"模型拿不到真实系统状态"。

设计 Tool 时有个安全铁律——工具越具体越安全：

❌ run_any_command(command)（等于开了后门）
✅ get_ci_status(repository, branch)（参数明确、可审计）

插件内置 MCP 和普通 MCP 要分清：普通 MCP 用户自己在 config.toml 配；插件捆绑的 MCP 由 .mcp.json + Manifest 的 "mcpServers" 声明。但关键是——装了插件 ≠ 给所有工具永久授权，用户仍能对每个工具单独设审批模式和启用范围。

✦ 完整开发流程：先分开验证，再打包

这篇最实用的一条方法论——别把 Skill Bug、MCP Bug、打包 Bug 一起调：

① 建目录 → ② 写 Skill（先只做只读流程）→ ③ 先把 Skill 单独放 .agents/skills/ 验证触发和输出 → ④ 开发 MCP Server（Tool 从只读开始）→ ⑤ 单独测 MCP（启动、Tool List、超时、OAuth、429 重试）→ ⑥ 写 .mcp.json → ⑦ 写 plugin.json（第一版别塞满可选字段）→ ⑧ 建本地 Marketplace → ⑨ 跑完整测试 → ⑩ 测权限。

第 ⑩ 步特别关键:故意给一个高风险 Prompt（"部署到生产并删掉旧版本"），理想结果不是"立即执行",而是识别高风险 → 请求确认/拒绝无权限工具 → 不越权。这是检验安全设计是否到位的试金石。

✦ 每层放对东西：一张表理清

层级	职责	示例
`AGENTS.md`	项目长期规则	Build/Test、安全边界
Skill	重复工作流	Repo 分析、发布检查
MCP	真实数据与动作	GitHub、CI、Sentry
Plugin Manifest	能力组合与分发	Skills、MCP、Hooks
Marketplace	本地/团队发现	Repo、Personal
Codex Config	Tool 权限与审批	enabled_tools、approval
后端系统	最终权限边界	OAuth、RBAC、Audit

一句话记住:Skill 说"怎么做"、MCP 说"能调什么"、Plugin 说"这些属于同一个安装包"、权限系统决定"最终允许做什么"。

✦ 安全：三条最容易被忽略的红线

① Skill 文本不是权限边界。 Skill 里写"Never delete production data"只是模型指令——真正的安全层在 MCP 授权、Tool 白名单、Codex 审批策略、Sandbox、后端 RBAC、人工审批。

② 装插件不会自动信任它的 Hook。 OpenAI 官方明确:插件捆绑的 Hook 属于 non-managed hooks,不会因为装了插件就被信任,Codex 会跳过直到用户审查。因为 Hook 能执行 Shell/脚本——绝不能设计成"装插件→自动跑未知脚本"。

③ Secret 永不写进插件。 真实 Token 交给环境变量/OAuth/Secret Manager,别写进 plugin.json、.mcp.json 或 Git 仓库。

高风险动作（部署、数据库写、删除、账单、发布、密钥轮换）一律加人工 Gate;读取 Issue/README/网页/CI Log 时,把外部内容当不可信输入,防 Prompt Injection 扩大工具权限。

📖 完整教程在这里

四层扩展体系、SKILL.md 结构与 description 写法、Skill 发现路径、MCP 配置（STDIO/HTTP/OAuth）、插件内置 MCP vs 普通 MCP、完整 Plugin 目录结构、plugin.json（最小版+完整版）、.mcp.json/.app.json 区别、$plugin-creator 快速创建、本地 Marketplace、十步实战、权限测试、8 节企业安全治理、发布前测试矩阵、10 条 FAQ、OpenAI 官方来源——全在这篇文章里👇

👉 《Codex Skills＋MCP 插件开发教程》
（点「阅读原文」直达 AI Stack Nav 看全文）

📚 配套阅读：站内有「Agent Plugins 1.0：Skills+MCP 跨 Codex/Copilot/VS Code 打包」「Claude Code/Codex/Copilot + MCP 完整配置」「Claude Code+Codex 跨平台任务接力」可一并查看。

🎁 卡在环境配置和部署？

MCP Server 开发、Node 环境、依赖、Docker 这些环节，我们整理成了现成资料包：

环境配置资料包
：Windows / Mac / Linux 环境配置、依赖安装、报错排查清单
Docker 工作流包
：Docker 部署模板、compose 示例、常用服务编排流程

📍 在 AI Stack Nav（aistacknav.com） 站内即可下载。会员开通、微信支付、资料下载有问题，直接找在线客服。

关注 AI Stack Nav，持续更新 Codex、MCP、AI Agent 插件开发的实战教程。