Codex Skills 与 Plugin 实战：把团队流程固化成可复用能力

同一套代码审查清单在 5 个仓库里复制粘贴，每次 PR 还要手动提醒”先跑失败测试”、“检查权限边界”、“别漏 changelog”。问题不在提示词不够长，而是这些流程没有被产品化。

Codex 的 Skills 和 Plugins 就是为了解决这个问题：把团队的重复流程从提示词和 AGENTS.md 中抽出来，沉淀成可复用能力。Skill 是可复用工作流的作者格式，Plugin 是可安装的分发单元。两者和项目规则分工不同：常驻规则留 AGENTS.md，多步骤流程、示例、脚本和长参考进 Skill，团队分发再打包成 Plugin。

一张决策表能帮你快速判断该用 Skill、Plugin、MCP、AGENTS.md 还是 Subagent；然后从一个最小 Skill 文件树开始，写到 role-specific plugin 的拆法、团队分发路径和权限边界检查清单。

一、复制粘贴的团队流程：问题不在提示词

代码审查、发布前检查、测试流程、文档更新，这些清单在团队里往往有固定格式。你可能会在每个 PR 评审时手动复制一段提示词给 Codex：“检查是否漏了 changelog、测试覆盖率有没有下降、API 文档要不要同步更新”。问题很快就暴露出来：

• 维护散落在多个地方：清单更新时，要同步修改 5 个项目的 .github/PULL_REQUEST_TEMPLATE.md 或各自独立的提示词文件
• 执行质量不稳定：Codex 每次都从零开始理解流程，容易漏掉”先跑失败测试”这类重要步骤
• 角色职责混乱：前端、测试、安全、文档四个角色的检查项堆在一个提示词里，Codex 难以判断该用哪个标准

有些团队选择把这些规则写进 AGENTS.md，但这又带来新问题：项目规则文件越写越长，常驻的构建命令、目录约定和临时的流程指导混在一起，超出它原本”持久项目约束”的设计范围。

Codex 提供了更清晰的分层：用 AGENTS.md 管持久规则，用 Skills 管可复用流程，用 Plugins 打包分发。知道每一层适合什么内容才能避免堆砌。

二、一张决策表说清 Skill、Plugin、MCP、AGENTS.md

Skill 是可复用工作流的作者格式，通常是一个 SKILL.md 文件加上可选的脚本、参考文档和资产。Plugin 是 Codex 中可安装的分发单元，可以打包 Skills、应用集成、MCP 服务器和资产。MCP 是外部工具和上下文连接协议，给 Codex 访问第三方文档、浏览器、Figma 等能力。AGENTS.md 是持久项目约束，适合存放构建命令、目录约定、审查期望等常驻规则。Subagent 是委派角色，用于处理嘈杂或专用任务。

何时选择哪种方式

内容类型	适用方式	典型场景	不要用在
构建命令、测试脚本路径、目录约定	AGENTS.md	”所有新组件放在 src/components/”、“测试用 npm run test:unit”	多步骤流程、示例、外部工具调用
多步骤流程、需要示例/脚本/参考文档	Skill	代码审查 10 步检查、发布前 7 项清单、API 文档生成流程	仅一条命令或一句话规则
团队分发、打包应用集成/MCP 配置	Plugin	前端角色插件，包含 4 个审查 Skills + Figma 连接器	仅在单个仓库迭代、不需要共享
外部工具调用、第三方文档访问	MCP	连接 Figma 获取设计规范、访问 GitHub API 拉取 issue 列表	纯工作流定义、不需要外部数据
嘈杂/专用任务委派	Subagent	让专用 agent 处理测试诊断、日志分析	简单流程、可以直接在主对话完成

何时从 AGENTS.md 抽成 Skill

以下情况说明流程已经超出项目规则文件的设计范围，应该写成 Skill：

• 同一套检查清单在多个 PR 反复出现，且每次都要手动复制粘贴
• 流程包含多个步骤，且需要示例、脚本或外部参考文档支撑
• 流程有明确触发条件，如”在发布前执行”、“在合并请求时运行”，而不是常驻约束
• 不同角色有不同的执行标准，不适合全部塞进一个文件
• 需要版本管理和变更记录，而不是每次改动都要修改项目规则

何时从 Skill 升级到 Plugin

Skill 在单个仓库或个人工作流内迭代时足够用，但当出现以下需求时，应该打包成 Plugin：

• 需要跨团队共享，而不是只在个人目录或单一仓库内使用
• 需要打包应用集成，如 Figma、GitHub、CI/CD 工具，或 MCP 服务器配置
• 需要版本管理、变更记录和升级机制，而不是每次都重新复制 Skill 文件
• 需要通过 Codex App 的 Plugin Directory 分发给 workspace 成员
• 准备发布稳定包，而不是频繁修改实验性流程

推荐顺序：先用 AGENTS.md 固化仓库约定；已有现成 Plugin 就安装；否则创建 Skill；团队分发时再打包成 Plugin；需要外部系统时再接 MCP；准备委派嘈杂或专用任务时再用 Subagent。

三、最小可用 Skill 实战：从代码审查开始

最小 Skill 文件树

一个 Skill 至少需要：

.agents/skills/code-review/
├── SKILL.md
├── references/
│   └── security-checklist.md
└── scripts/
    └── run-failed-tests.sh

目录名和 SKILL.md frontmatter 中的 name 必须匹配，lowercase alphanumeric + hyphen。

SKILL.md 示例：代码审查 Skill

---
name: code-review
description: Use for pull request reviews in frontend projects. Checks changelog, test coverage, security boundary, and API docs. Do not use for backend-only changes or infrastructure PRs.
---

# Code Review Checklist

## Before Starting
1. Run failed tests first: `npm run test:failed`
2. Check if PR has clear description and scope

## Review Steps
1. Changelog: Does `CHANGELOG.md` need update?
2. Test Coverage: Did coverage decrease? Check report in `coverage/`
3. Security: Review changes in `src/auth/`, `src/api/`, and `src/middleware/`
4. API Docs: If API changed, update `docs/api.md`

## Security Boundary Checks
See `references/security-checklist.md` for detailed items.

## Failed Test Runner
Use `scripts/run-failed-tests.sh` to rerun previously failed tests.

description 触发设计：before/after 对比

Codex 会根据 description 判断何时隐式调用 Skill。写得太模糊容易误触发或不触发：

Before（容易误触发）	After（触发更可靠）
“Code review skill for frontend projects"	"Use for pull request reviews in frontend projects. Checks changelog, test coverage, security boundary, and API docs."
"Help review code"	"Use when reviewing PRs with frontend changes. Do not use for backend-only changes or infrastructure PRs."
"Review checklist"	"Trigger on: PR reviews, code audit requests. Exclude: backend changes, config-only updates.”

写法要点：明确 “Use when…” 和 “Do not use when…”，触发关键词前置，例如 pull request、review、frontend。大 Skill 集描述可能被截短，核心判断要放在前半部分。如果只想显式调用，设置 allow_implicit_invocation: false。

Skill 保存位置与作用域

位置	作用域	适用场景	注意事项
.agents/skills/（仓库根目录）	当前仓库	团队项目的审查、测试、发布流程	签入 Git，团队共享
$HOME/.agents/skills/（用户目录）	个人跨项目	个人习惯的代码风格、常用命令提示	不会自动同步到仓库
/etc/codex/skills/（admin 目录）	组织级别	组织统一的安全审查、合规检查	需要 admin 权限
System bundled	系统内置	Codex 默认提供的 $skill-creator、$skill-installer	不可修改

同名 Skill 不会合并；优先级通常为 repo > user > admin > system，具体行为可能随 Codex 版本变化，以官方文档为准。

Progressive disclosure 设计原则

不要把所有内容塞进主 SKILL.md。Codex 的渐进式披露分三层：

1. Metadata：Codex 初始只看 name、description、file path
2. Instructions：选中后才读完整 SKILL.md
3. Resources：用到时才读 references/、scripts/、assets/

设计原则：主 SKILL.md 控制在 500 行内，长参考拆到单独文件；scripts/ 只放确定性检查脚本，如测试运行器、覆盖率检查；references/ 放详细清单、背景文档、历史案例；assets/ 放示例截图、模板文件。

显式/隐式调用方式

显式调用用 $code-review 或 /skills 后选择 Skill。隐式调用让 Codex 根据 description 判断是否适用当前任务。禁用隐式调用则在 agents/openai.yaml 中设置 allow_implicit_invocation: false。

隐式调用适合高频、边界明确的流程，如每次 PR 都要审查；显式调用适合低频、需要人工判断的场景，如季度安全审计。如果 Skill 包含外部脚本或敏感操作，优先显式调用。

四、Plugin 打包与团队分发：从本地 Skill 到团队套件

Plugin 最小结构

Plugin 不是只把 Skill 目录改个后缀，而是一个可安装包，至少包含 .codex-plugin/plugin.json manifest：

.agents/plugins/frontend-review/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   ├── accessibility-check/
│   │   └── SKILL.md
│   └── performance-lint/
│       └── SKILL.md
├── assets/
│   └── templates/
└── README.md

plugin.json 必需字段

{
  "name": "frontend-review",
  "version": "1.0.0",
  "description": "Frontend team code review and accessibility check skills",
  "skills": "./skills/",
  "assets": "./assets/",
  "author": "frontend-team",
  "repository": "https://github.com/org/frontend-review-plugin"
}

可选字段包括 apps（打包应用集成，如 .app.json for Figma）、mcpServers（打包 MCP 服务器配置，如 .mcp.json）、policy（权限和数据共享策略，受 workspace admin policy 约束）。

marketplace 结构：团队插件目录

Plugin marketplace 是一个 JSON 清单，指向插件路径：

.agents/plugins/marketplace.json

{
  "plugins": [
    {
      "source": "local",
      "path": "./frontend-review"
    },
    {
      "source": "github",
      "owner": "openai",
      "repo": "role-specific-plugins",
      "ref": "main",
      "path": "plugins/data-analytics"
    }
  ]
}

local 适合团队内部未发布插件；github 指向 GitHub 仓库，适合公共插件或跨团队共享。

Plugin 分发命令清单

CLI 基本命令以官方文档为准，容易变化：

# Scaffold 新插件
codex plugin create frontend-review

# 添加插件到 marketplace
codex plugin marketplace add owner/repo --ref main --sparse

# 列出已安装插件
codex plugin marketplace list

# 升级插件
codex plugin marketplace upgrade frontend-review

# 移除插件
codex plugin marketplace remove frontend-review

Codex App 内：Plugin Directory 可浏览 Curated by OpenAI、Shared with you、Created by you；Local plugin 可分享给 workspace members 或 groups；Workspace admins 可禁用 plugin sharing 或设置 managed requirements。

分享到 workspace 不等于公开发布。外部 app 连接和 MCP server 仍需授权，approval settings 仍适用。

团队 marketplace 组织建议

仓库级 marketplace 放 $REPO_ROOT/.agents/plugins/marketplace.json，存放项目专用插件。组织级 marketplace 放 $HOME/.agents/plugins/marketplace.json 或 GitHub organization repo，存放团队通用插件。版本管理在插件 manifest 中明确 version，README 维护 changelog，升级前在测试环境验证。权限隔离把敏感插件，如安全审查、合规检查，放在组织级 marketplace，避免随意安装。

建议先用 local skill 迭代，稳定后再打包成 plugin 分发，而不是一开始就建 plugin。

五、Role-specific Plugin 拆法：把前端、测试、文档角色固化

OpenAI 在 role-specific-plugins 仓库提供了 Sales、Data Analytics、Product Design、Financial Markets 四个模板。开发团队不需要照搬金融或销售流程，但可以借鉴拆法：从一个角色出发，拆出 3-5 个小 Skill，再打包成 Plugin。

拆解框架：角色 → 重复产物 → 数据/工具来源 → 小 Skill 列表 → 共享方式

角色	重复产物	数据/工具来源	应拆出的 Skills	可能需要的 apps/MCP	验收标准
前端工程师	组件审查、性能检查、无障碍验证	Figma 设计规范、Storybook 现有组件库	component-audit、accessibility-check、performance-lint、design-system-sync	Figma connector、Storybook MCP	每个新组件都跑完 4 个检查
QA 工程师	测试覆盖率报告、E2E 套件诊断、回归清单	CI/CD 测试结果、历史失败记录	test-coverage-check、e2e-suite-runner、flaky-test-diagnosis、regression-suite-builder	CI/CD 工具连接，如 GitHub Actions/Jenkins	失败测试优先运行、覆盖率不下降
技术文档工程师	API 文档更新、Changelog 构建、迁移指南	API schema、Git commit history	api-doc-generator、changelog-builder、readme-audit、migration-guide-writer	GitHub API、Schema 工具	API 变化时文档同步更新
安全工程师	权限边界审查、密钥检查、依赖安全扫描	依赖清单、密钥存储配置	auth-boundary-check、secrets-scan、dependency-security	Snyk、Dependabot MCP	每次发布前跑完安全清单

前端角色插件拆解示例

frontend-engineer-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── component-audit/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── component-template.md
│   ├── accessibility-check/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── axe-audit.sh
│   ├── performance-lint/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── lighthouse-check.sh
│   └── design-system-sync/
│       ├── SKILL.md
│       └── references/
│           └── design-tokens.md
├── assets/
│   └── templates/
│       └── component-template.tsx
└── README.md

component-audit Skill 检查新组件是否符合团队规范，如命名、目录、props 类型；accessibility-check 用 axe-core 脚本跑无障碍检查；performance-lint 用 Lighthouse 检查核心指标；design-system-sync 对照 Figma 设计规范验证实现。

测试角色插件拆解示例

qa-engineer-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── test-coverage-check/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── coverage-threshold-check.sh
│   ├── e2e-suite-runner/
│   │   └── SKILL.md
│   ├── flaky-test-diagnosis/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── flaky-test-log-analysis.md
│   └── regression-suite-builder/
│       └── SKILL.md
├── .mcp.json
└── README.md

test-coverage-check 检查覆盖率是否下降并标记未覆盖的文件；e2e-suite-runner 按优先级运行 E2E 测试；flaky-test-diagnosis 分析历史失败日志找出不稳定测试；regression-suite-builder 根据变更范围构建回归测试清单。

connector placeholder 替换清单

官方模板中的 .app.json 可能包含 placeholder connector id，安装前需要替换：

{
  "app_id": "figma-placeholder"
}

检查项：.app.json 中的所有 placeholder id 要替换为目标 workspace 可用的真实 id；不要直接复制别的 workspace 的 connector id，它们在不同环境可能无效或有权限问题；MCP server 配置中的 OAuth/Bearer token 要按你的环境配置，不是模板中的示例值；替换后先在测试环境验证连接器是否可用。

官方 role-specific-plugins README 说明，这些插件模板需要先按团队环境定制；带 connector 的插件可能包含要替换的 app 或 connector id。

六、安全与维护：Plugin 不是权限通行证

Connector / MCP 权限边界

安装 Plugin 不绕过 Codex 的 approval settings。外部 app 和 MCP server 仍需授权，数据共享仍受各自政策约束：.app.json 中的 placeholder id 要替换，但不能直接复制别的 workspace 的 connector id，它们可能因权限或环境差异而无效；外部 app 如 Figma、GitHub 需要你单独授权，Plugin 只是打包配置，不是授权本身；MCP server 在 config.toml 中仍可控制 enabled 和 tool policy；Approval mode 仍适用，如果设置为 “suggest-only”，Plugin 中的脚本不会自动执行。

不要把 Plugin 当成权限通行证。它只是把工作流、配置和资产打包，权限边界仍然存在。

脚本来源审查

Skill/Plugin 中的 scripts/ 目录可能包含可执行文件。第三方 Plugin 或社区 marketplace 的脚本需要审查：检查 scripts 目录中的所有可执行文件，确认来源可信；避免直接运行来自未验证仓库的脚本；测试环境先行，不在生产环境直接安装未知 Plugin；版本锁定，不要每次都从 main 分支拉最新版本，使用明确的 tag 或 commit hash。

站内之前分析过 OpenClaw Skills 的恶意插件风险，同样的原则适用于任何可执行脚本和第三方 Plugin：来源审查、权限最小化、测试环境验证。

版本与变更记录

团队协作需要版本管理：plugin.json 中明确 version 字段，每次更新递增版本号；README 中维护 changelog，说明哪些 Skill 新增、哪些修改、哪些废弃；升级前在测试环境验证，运行所有 Skills，检查脚本是否正常，确认连接器仍可用；marketplace 中使用 ref 锁定版本，而不是每次都拉 main 分支最新代码。

Skill/Plugin 数量影响

Codex 初始 Skill 列表有上下文预算约束。官方文档说明：初始 skills 列表预算约占上下文 2% 或 unknown context 时 8,000 characters。

实际影响：Skill description 写得太长可能被截短，核心触发词要前置；同时加载过多 Skills 可能影响 Codex 判断哪个 Skill 适用当前任务；高频使用、边界明确的 Skill 适合放在 repo 或 user 目录，低频、不常用的 Skill 放在 plugin 中按需安装，而不是全部常驻。

如果发现 Codex 经常误触发或不触发某个 Skill，先检查 description 是否清晰、是否被截短，而不是继续增加 Skill 数量。

七、与相关技术的对比

与 Claude Code Skills 的类比

站内之前写过 Claude Code Skill 机制，两者心智相近但产品不同：都围绕 Agent Skills 开放标准和 SKILL.md 文件；都用 name、description、可选的 scripts/、references/、assets/；都支持渐进式披露：metadata → instructions → resources。

差异在于：路径上 Codex 用 .agents/skills/，Claude Code 用 .claude/skills/；调用上 Codex 用 $skill-name 或 /skills，Claude Code 用 /skill 命令；插件分发上 Codex Plugin 有 marketplace、CLI 命令和 workspace sharing，Claude Code 目前没有官方 Plugin marketplace；内置工具上 Codex 有 $skill-creator、$skill-installer、@plugin-creator，Claude Code 有不同的内置命令。

如果之前写过 Claude Code Skills，心智可以直接迁移，但路径和调用方式要以各自官方文档为准，不要把 .claude/skills 当成 Codex 路径。

与 MCP 的分工

MCP（Model Context Protocol）用于外部工具和上下文连接，不是 Skill/Plugin 的替代：Skill 定义工作流和流程；MCP 连接外部工具，如 Figma、GitHub、CI/CD 系统；Plugin 可以打包 MCP server 配置，但 MCP server 本身仍然在 config.toml 中受控。

分工示例：前端审查 Skill 定义”检查组件是否符合设计规范”的流程；Figma MCP server 提供访问设计规范文件的能力；前端 Plugin 打包审查 Skill + Figma MCP 配置，但 Figma OAuth 仍需单独授权。

这里先澄清分工，Codex MCP tools 实战会单独展开。

结论

Codex Skills 和 Plugins 的核心价值是把团队的重复流程从复制粘贴和 AGENTS.md 中抽出来，沉淀成可复用能力。要点：用 AGENTS.md 管持久规则，用 Skill 管多步骤流程，用 Plugin 打包分发，用 MCP 接外部工具；description 写清触发条件，避免误触发或不触发；先用 local skill 迭代，稳定后再打包成 plugin；第三方 Plugin 的脚本、connector id 和 MCP 配置要审查和替换。

从一个最小 Skill 开始：先把团队的代码审查或测试流程写成 SKILL.md，跑几次验证触发是否可靠，再考虑是否需要打包成 Plugin 分发。如果团队有前端、测试、安全、文档等角色，可以参考 OpenAI role-specific-plugins 的拆法，按角色拆成 3-5 个小 Skill，再打包成角色 Plugin。

站内延伸阅读：

• Codex 入门完全指南
• AGENTS.md 项目规则
• Codex 安全边界与权限管理
• Codex MCP tools 实战
• Claude Code Skill 类比
• MCP 协议基础