Codex Skill 和插件到底有什么区别？程序员如何在项目中落地使用

前言

使用 Codex 写代码时，我们通常会遇到几个容易混淆的概念：

AGENTS.md
Skill
Plugin
App
MCP Server
Hook
Command

很多人会把 Skill 和插件理解成同一种东西，或者把 Skill 当成普通提示词，把插件当成类似 IDEA、VS Code 的扩展。

这种理解并不准确。

按照 Codex 当前的官方定义：

Skill 是可复用工作流的编写格式，Plugin 是安装和分发这些能力的包装单位。

简单理解：

Skill 负责告诉 Codex“这件事情应该怎么做”
Plugin 负责把 Skill、外部系统连接、MCP 工具、Hook 等能力打包起来，让其他人安装使用

官方文档明确说明，Skill 是工作流的 authoring format，也就是“编写格式”；Plugin 是 installable distribution unit，也就是“可安装、可分发的单位”。

一、先用一个实际例子理解 Skill 和插件

假设你是一名 Java 后端开发，需要让 Codex按照团队规范完成代码评审。

团队规范包括：

检查空指针风险。
检查事务是否可能失效。
检查循环查询数据库的问题。
检查接口幂等性。
检查日志中是否打印敏感信息。
检查 SQL 是否可能出现多行子查询异常。
生成固定格式的代码评审报告。

你可以把这些规则写成一个：

java-code-review Skill

这个 Skill 的作用是告诉 Codex：

当用户要求进行 Java 代码评审时，按照指定顺序检查代码，
最后按照团队规定的模板输出结果。

但是，如果代码评审还需要：

从 GitHub 读取 Pull Request；
获取 Jira 需求；
将评审结果发送到 Slack；
调用 SonarQube；
执行自定义扫描脚本；
在任务结束时自动运行测试；

那么只写一个 Skill 通常不够。

你可以进一步创建一个：

java-review-plugin

插件中包含：

java-review-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   └── java-code-review/
│       └── SKILL.md
├── scripts/
├── hooks/
├── .mcp.json
└── assets/

这个插件负责把：

Java 代码评审 Skill；
GitHub、Jira、Slack 等外部连接；
MCP Server；
自动化脚本；
生命周期 Hook；
报告模板；

打包成一个可以安装、共享和复用的完整工作流。

二、什么是 Codex Skill

2.1 Skill 的定义

Skill 是一个包含操作说明、脚本、参考资料和资源文件的目录。

最简单的 Skill 只需要一个文件：

SKILL.md

一个完整 Skill 可以包含：

my-skill/
├── SKILL.md
├── scripts/
├── references/
├── assets/
└── agents/
    └── openai.yaml

各目录的作用如下。

`SKILL.md`

Skill 的核心文件，包含：

Skill 名称；
Skill 描述；
触发条件；
执行步骤；
输出格式；
边界条件；
禁止执行的操作。

`scripts/`

存放可执行脚本，例如：

Shell 脚本；
Python 脚本；
Node.js 脚本；
SQL 校验脚本；
代码扫描脚本；
测试脚本。

`references/`

存放 Codex 执行任务时可以参考的资料，例如：

公司开发规范；
数据库设计规范；
API 规范；
架构文档；
错误码文档；
示例代码。

`assets/`

存放模板或静态资源，例如：

Markdown 报告模板；
配置文件模板；
YAML 模板；
SQL 模板；
项目初始化模板。

Codex 首先只读取 Skill 的 name、description 和文件位置。只有任务与 Skill 匹配时，Codex 才会进一步读取完整的 SKILL.md，并在需要时读取参考资料或执行脚本。这种机制叫作 progressive disclosure，即渐进式加载，可以减少无关内容占用上下文。

2.2 Skill 有什么作用

Skill 的核心作用是：

把一次性的提示词，变成稳定、可维护、可复用的工程化工作流。

普通提示词可能是：

帮我检查一下这段 Java 代码。

不同时间执行，Codex 的检查重点和输出格式可能不同。

使用 Skill 后，可以把过程固定下来：

1. 先分析调用链。
2. 再检查参数校验。
3. 检查事务边界。
4. 检查数据库访问。
5. 检查并发和幂等性。
6. 检查日志和异常处理。
7. 运行测试。
8. 输出固定格式报告。

因此，Skill 能够实现以下目的：

统一团队规范

把团队经验写进 Skill，避免每个开发人员使用不同的提示词。

固化复杂流程

把一个复杂任务拆解成确定步骤，减少 Codex 遗漏步骤。

提高输出稳定性

规定输入、执行流程和输出格式，使多次执行结果更一致。

沉淀领域知识

把支付、清结算、风控、开票、对账等业务知识交给 Codex。

减少重复提示

不需要每次重新粘贴几十行要求。

与脚本结合

Skill 不只是文字说明，也可以让 Codex执行测试、校验、格式化和代码生成脚本。

2.3 Skill 和普通 Prompt 的区别

普通 Prompt 是一次性的：

检查当前代码有没有事务失效问题。

Skill 是长期复用的工作流：

java-transaction-review/
└── SKILL.md

Skill 可以明确规定：

什么时候触发；
哪些文件需要检查；
按什么顺序分析；
使用什么命令；
参考什么规范；
最后输出什么内容；
哪些操作禁止执行。

因此可以简单理解为：

普通 Prompt = 临时口头要求
Skill = 标准作业指导书

三、什么是 Codex 插件

3.1 插件的定义

Codex Plugin 是一个可安装的能力包。

一个插件可以包含：

一个或多个 Skills；
App；
MCP Server；
Browser Extension；
Hooks；
Scheduled Task Templates；
Commands；
Agents；
Assets。

官方文档把插件定义为“将多种能力打包为可复用工作流的安装单元”。插件既可以只包含 Skill，也可以同时包含 Skill 和外部工具连接。

典型目录如下：

my-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── review-code/
│   │   └── SKILL.md
│   └── fix-code/
│       └── SKILL.md
├── agents/
├── commands/
├── hooks/
│   └── hooks.json
├── assets/
├── .app.json
└── .mcp.json

其中最关键的是：

.codex-plugin/plugin.json

这是插件清单文件，相当于插件的身份证。

3.2 插件有什么作用

插件主要解决以下问题。

统一安装

一个插件可能包含多个 Skill 和相关配置，用户只需要安装一次。

团队分发

可以将插件放到团队 Marketplace 中，让所有成员使用统一版本。

连接外部系统

例如连接：

GitHub；
GitLab；
Gmail；
Slack；
Google Drive；
Notion；
Jira；
Figma；
内部研发平台。

提供真实操作能力

Skill 主要规定“怎么完成任务”，插件中的 App 或 MCP Server 可以提供真正的工具调用能力，例如：

查询 Pull Request；
创建 Issue；
读取 Slack 消息；
修改文档；
获取监控数据；
调用内部 API。

增加生命周期自动化

通过 Hook 可以在特定阶段自动执行命令，例如：

修改代码后自动格式化；
任务结束前自动运行测试；
提交前执行静态扫描；
完成后生成报告。

管理权限和认证

涉及 GitHub、Slack、Gmail 等外部服务时，插件可以要求登录或授权，并由对应服务控制访问权限。官方提醒，插件中的连接器、MCP Server 和 Hook 都可能访问数据或执行操作，安装前应检查其权限和来源。

四、Skill 和插件的核心区别

对比维度	Skill	Plugin
核心定位	工作流编写格式	安装和分发单位
主要作用	告诉 Codex 怎么做	打包 Codex 完成任务所需的能力
最小组成	一个 `SKILL.md`	一个 `.codex-plugin/plugin.json`
是否可以包含多个工作流	通常描述一个具体工作流	可以包含多个 Skill
是否适合项目内使用	非常适合	适合复杂项目或团队共享
是否能连接外部系统	通常需要配合 MCP	可以直接打包 App 或 MCP 配置
是否方便团队安装	可以通过 Git 管理	更适合 Marketplace 分发
是否适合快速试验	非常适合	相对较重
是否可以包含 Hook	通常不作为主要载体	可以
是否可以包含命令	主要通过工作流描述	可以打包 Commands
类比	标准操作手册	软件安装包
关注重点	任务过程	能力组合与分发

一句话总结：

Skill 决定 Codex 如何工作。
Plugin 决定 Codex 能安装和使用哪些完整能力。

再换一个程序员更容易理解的类比：

Skill 类似 Java 中的业务实现类。
Plugin 类似一个包含多个模块、依赖和配置的 Starter。

或者：

Skill ≈ 方法或服务
Plugin ≈ Maven 依赖包或 Spring Boot Starter

这种类比并不完全等价，但便于理解两者的层级关系。

五、Skill、插件、AGENTS.md 和 MCP 的区别

5.1 AGENTS.md

AGENTS.md 主要描述当前开发者或当前代码仓库的长期规则。

例如：

- 项目使用 JDK 17。
- 禁止引入 Lombok。
- 所有金额字段使用 BigDecimal。
- Controller 不允许直接调用 Mapper。
- 所有数据库更新必须包含 delete_flag 条件。
- 提交代码前运行 mvn test。

Codex 支持全局和仓库级规则：

~/.codex/AGENTS.md

用于个人全局习惯。

project-root/AGENTS.md

用于项目规范。

官方建议：全局文件用于个人沟通偏好和默认行为，仓库文件用于代码库和团队规则；距离当前工作目录更近的说明具有更高优先级。

AGENTS.md 适合写什么

项目技术栈；
目录结构；
编码规范；
测试命令；
构建命令；
禁止修改的目录；
安全限制；
团队长期约定。

Skill 适合写什么

发布流程；
代码评审流程；
SQL 检查流程；
故障排查流程；
接口生成流程；
数据库变更流程。

区别是：

AGENTS.md = 这个项目长期必须遵守什么
Skill = 某类任务具体应该怎么执行

5.2 MCP Server

MCP Server 负责向 Codex 提供工具和外部数据。

例如：

Skill：
告诉 Codex 先查询 Jira，再分析代码，最后更新任务状态。

MCP Server：
真正提供 jira_search、jira_read、jira_update 等工具。

所以：

Skill = 流程和决策
MCP = 工具和数据
Plugin = 将 Skill 与 MCP 打包起来

5.3 App

App 负责连接外部服务，例如 GitHub、Slack 或 Google Drive。App 背后通常由 MCP Server 提供工具，还可能包含自定义界面。

插件可以依赖或打包 App 配置。

5.4 Hook

Hook 是在 Codex 生命周期的指定时间自动执行的命令。

例如：

代码修改完成
    ↓
自动执行 spotless:apply
    ↓
自动执行 mvn test
    ↓
测试失败则阻止任务结束

Hook 更像自动触发器，而 Skill 更像工作说明书。

六、怎么试用一个 Skill

6.1 方法一：使用内置 Skill 创建器

在 Codex 中输入：

$skill-creator

然后描述需求，例如：

创建一个 Java Spring Boot 代码评审 Skill。

触发条件：
当用户要求评审 Java、Spring Boot、MyBatis 或 Dubbo 代码时使用。

检查内容：
1. 空指针风险；
2. 事务失效；
3. 循环查询；
4. 幂等性；
5. 并发安全；
6. 日志敏感信息；
7. 异常吞掉；
8. SQL 多行子查询；
9. BigDecimal 使用错误；
10. 接口兼容性。

输出格式：
按照严重、较高、一般、建议四个等级输出。

官方 Skill 创建器会询问：

Skill 做什么；
什么时候触发；
是否只使用说明；
是否需要脚本。

官方推荐优先创建 instruction-only Skill，即先只写说明，确实需要稳定执行工具时再增加脚本。

6.2 方法二：手动创建项目级 Skill

在项目根目录创建：

mkdir -p .agents/skills/java-code-review

创建文件：

.agents/skills/java-code-review/SKILL.md

写入：

---
name: java-code-review
description: Review Java, Spring Boot, MyBatis and Dubbo code for correctness, transactions, database access, concurrency, idempotency and maintainability. Use when the user asks to review Java backend code or a code change.
---

# Java backend code review

## Goal

Review the selected Java backend changes and identify concrete defects,
production risks, missing tests and maintainability problems.

## Review order

1. Understand the business purpose and call chain.
2. Inspect parameter validation and null handling.
3. Inspect transaction boundaries and self-invocation.
4. Inspect database queries and update conditions.
5. Inspect concurrency, locking and idempotency.
6. Inspect exception handling and logging.
7. Inspect backward compatibility.
8. Inspect test coverage.
9. Run relevant tests when permitted.

## Important checks

- Do not treat style preferences as defects.
- Every finding must reference a concrete file and line.
- Explain the runtime consequence of each finding.
- Do not modify code unless the user requests a fix.
- Never run production deployment commands.

## Output

### Critical
List defects that may cause data corruption, security issues or outages.

### High
List defects that may produce incorrect business results.

### Medium
List maintainability and edge-case problems.

### Tests
List missing or recommended tests.

### Conclusion
Provide an overall assessment and recommended next action.

Codex 会扫描项目中的：

.agents/skills/

官方说明，项目级 Skill 可以提交到代码仓库，让整个团队共享；个人跨项目 Skill 则可以放到：

$HOME/.agents/skills

Codex 通常能自动检测 Skill 变更；如果没有出现，可以重启 Codex。

6.3 如何调用 Skill

显式调用

在 Codex CLI 或 IDE 中，可以输入：

/skills

查看 Skill。

也可以在提示词中通过 $ 选择 Skill：

使用 $java-code-review 评审当前分支相对于 main 的代码变更。

或者：

使用 $java-code-review 检查
src/main/java/com/example/payment/PaymentService.java。

隐式调用

直接输入：

帮我评审当前 Java 后端改动，重点检查事务和数据库一致性。

只要 Skill 的 description 与任务匹配，Codex 就可能自动选择这个 Skill。

Codex 官方支持显式调用和隐式调用两种方式；隐式匹配主要依赖 description，所以描述必须简洁、明确，并在开头放入关键触发词。

6.4 安装官方或精选 Skill

可以使用：

$skill-installer

例如官方文档给出的安装形式：

$skill-installer linear

也可以让安装器从其他代码仓库安装 Skill。

这种方式适合：

本地试验；
个人使用；
验证工作流；
学习 Skill 结构。

如果要将自己的 Skill 分发给团队，官方更推荐封装为插件。

七、怎么试用插件

7.1 Codex 桌面端安装插件

在 Codex 或 ChatGPT 桌面端中：

打开 Plugins。
搜索需要的插件。
打开插件详情。
点击加号安装。
如果需要连接外部系统，完成登录授权。
安装完成后新建一个任务。
在新任务中使用插件。

插件是在任务启动时加载的，因此安装插件以后，应当新建聊天或新建 Codex 任务，而不是继续使用安装前已经打开的旧任务。

7.2 Codex CLI 安装插件

先进入项目：

cd your-project
codex

然后在 Codex 中输入：

/plugins

打开插件浏览器。

执行过程通常是：

/plugins
    ↓
搜索插件
    ↓
Install plugin
    ↓
新建 Codex Session
    ↓
调用插件

例如试用 Codex Security：

/plugins

搜索：

Codex Security

安装完成后开启新任务，然后输入：

Run a Codex Security scan on this repository.

Codex Security 官方插件可以扫描经过授权的代码仓库、验证可能的漏洞，并生成证据和修复建议。标准扫描会产生 report.md，以及 scan-manifest.json、findings.json 和 coverage.json 等结构化结果文件。

7.3 IDE 扩展安装插件

在 Codex IDE 扩展中：

Settings
    ↓
Plugins
    ↓
搜索插件
    ↓
安装
    ↓
新建聊天

安装后同样需要新建聊天，使插件中的 Skill 和工具被加载。

八、如何自己创建一个 Skill

下面以“Oracle UPDATE SQL 安全检查”为例。

8.1 项目目录

your-project/
├── AGENTS.md
├── .agents/
│   └── skills/
│       └── oracle-update-review/
│           ├── SKILL.md
│           ├── references/
│           │   └── oracle-update-rules.md
│           └── scripts/
│               └── check_sql.py
└── src/

8.2 SKILL.md 示例

---
name: oracle-update-review
description: Review Oracle UPDATE statements for multi-row scalar subqueries, accidental full-table updates, duplicate source rows, null overwrites and missing rollback verification. Use when reviewing or generating Oracle UPDATE SQL.
---

# Oracle UPDATE review workflow

## Inputs

- Target table
- Source table
- Join condition
- Target assignment
- Business filters
- Duplicate-data strategy

## Procedure

1. Identify the target table and target columns.
2. Check whether the WHERE clause restricts the target rows.
3. Check whether the scalar subquery can return multiple rows.
4. Query source-key duplication before generating UPDATE SQL.
5. Do not use DISTINCT to hide conflicting source values.
6. Define an explicit duplicate-resolution rule:
   - latest record;
   - maximum value;
   - minimum value;
   - aggregation;
   - reject duplicate data.
7. Check whether NULL source values may overwrite valid target values.
8. Generate a preview SELECT before generating UPDATE.
9. Generate the UPDATE statement.
10. Generate post-update verification SQL.
11. Recommend transaction and rollback steps.

## Oracle-specific checks

- ORA-01427: scalar subquery returns multiple rows.
- ORA-01779: cannot modify a column mapped to a non-key-preserved table.
- Empty string is treated as NULL.
- Verify indexes on join columns.
- Avoid functions on indexed join columns where possible.

## Output format

1. Risk analysis
2. Duplicate inspection SQL
3. Preview SELECT
4. UPDATE SQL
5. Verification SQL
6. Rollback recommendation

## Safety

Do not execute UPDATE, DELETE, TRUNCATE, DROP or MERGE automatically.
Only generate SQL unless the user explicitly authorizes execution in a non-production environment.

8.3 使用方式

输入：

使用 $oracle-update-review，把
T_E951_OTHER_PUB_MASTER_BILL.REC_BANK_NO
更新到
T_TRUCK_BUSINESS_BILL.REC_BANK_ACCOUNT。

关联条件：
T_TRUCK_BUSINESS_BILL.BILL_NO =
T_E951_OTHER_PUB_MASTER_BILL.BILL_NO。

只允许使用 UPDATE，不使用 MERGE。

Codex 就会按照 Skill 中规定的流程：

检查源表重复数据；
生成预览 SELECT；
分析 ORA-01427 风险；
生成 UPDATE；
生成校验 SQL；
给出事务和回滚建议。

九、如何自己创建一个插件

9.1 最小插件结构

java-backend-plugin/
├── .codex-plugin/
│   └── plugin.json
└── skills/
    └── java-code-review/
        └── SKILL.md

创建目录：

mkdir -p java-backend-plugin/.codex-plugin
mkdir -p java-backend-plugin/skills/java-code-review

9.2 编写 plugin.json

文件位置：

java-backend-plugin/.codex-plugin/plugin.json

内容：

{
  "name": "java-backend-plugin",
  "version": "1.0.0",
  "description": "Reusable Java backend development workflows",
  "skills": "./skills/"
}

插件名建议使用稳定的 kebab-case 格式，例如：

java-backend-plugin
database-review-plugin
release-management-plugin

Codex 会把插件名用作插件标识符和组件命名空间。

9.3 添加 Skill

文件位置：

java-backend-plugin/skills/java-code-review/SKILL.md

内容：

---
name: java-code-review
description: Review Java backend code for correctness, transactions, database access, concurrency, idempotency and test coverage.
---

Review the Java backend changes in this order:

1. Business correctness
2. Null handling
3. Transaction boundaries
4. SQL and database access
5. Concurrency and idempotency
6. Exception handling
7. Logging
8. Compatibility
9. Tests

Reference concrete files and lines for every finding.
Do not modify code unless explicitly requested.

这就是一个最小可用插件。官方的插件创建文档也建议先从“一个插件包含一个 Skill”的最小结构开始，再逐步增加 MCP、连接器和 Marketplace 信息。

十、项目中怎么安装本地插件

10.1 项目级 Marketplace

适合：

只在一个代码仓库使用；
插件跟随项目版本管理；
团队成员克隆项目后统一安装；
不希望影响其他项目。

项目结构：

project-root/
├── .agents/
│   └── plugins/
│       └── marketplace.json
├── plugins/
│   └── java-backend-plugin/
│       ├── .codex-plugin/
│       │   └── plugin.json
│       └── skills/
└── src/

复制插件：

mkdir -p ./plugins
cp -R /absolute/path/java-backend-plugin \
  ./plugins/java-backend-plugin

创建：

.agents/plugins/marketplace.json

内容：

{
  "name": "company-java-marketplace",
  "plugins": [
    {
      "name": "java-backend-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/java-backend-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Developer Tools"
    }
  ]
}

然后：

重启 Codex 或 ChatGPT 桌面端；
打开 Plugins；
找到项目 Marketplace；
安装插件；
新建任务；
调用其中的 Skill。

这是官方文档给出的 Repo Marketplace 模式。source.path 相对于 Marketplace 根目录解析，而不是相对于 .agents/plugins 目录解析。

10.2 个人 Marketplace

适合：

个人跨项目使用；
自己维护多个插件；
不提交到业务项目；
先本地验证。

插件目录：

~/.codex/plugins/

Marketplace 文件：

~/.agents/plugins/marketplace.json

复制插件：

mkdir -p ~/.codex/plugins

cp -R /absolute/path/java-backend-plugin \
  ~/.codex/plugins/java-backend-plugin

然后在个人 Marketplace 中配置插件路径，重启桌面端后安装。官方说明，这些目录是推荐示例，不是绝对固定目录；真正决定插件位置的是 Marketplace 中的 source.path。

十一、Java 项目中推荐的落地结构

对于一个中大型 Java 项目，可以采用以下结构：

payment-service/
├── AGENTS.md
├── .agents/
│   ├── skills/
│   │   ├── java-code-review/
│   │   │   └── SKILL.md
│   │   ├── oracle-update-review/
│   │   │   └── SKILL.md
│   │   ├── api-design/
│   │   │   └── SKILL.md
│   │   ├── incident-analysis/
│   │   │   └── SKILL.md
│   │   └── release-check/
│   │       └── SKILL.md
│   └── plugins/
│       └── marketplace.json
├── plugins/
│   └── payment-engineering/
│       ├── .codex-plugin/
│       │   └── plugin.json
│       ├── skills/
│       ├── references/
│       ├── scripts/
│       └── hooks/
├── docs/
│   ├── architecture/
│   ├── database/
│   └── api/
├── src/
└── pom.xml

职责划分如下：

AGENTS.md
    项目长期规则

.agents/skills
    项目内具体工作流

plugins
    可以安装和分发的完整能力包

docs
    项目文档和 Skill 参考资料

scripts
    可重复执行的校验和自动化脚本

十二、程序员常用的 Skill

12.1 代码评审 Skill

用途：

检查业务逻辑；
检查异常处理；
检查事务；
检查并发；
检查幂等；
检查测试覆盖。

推荐名称：

java-code-review
spring-code-review
pr-review
architecture-review

12.2 Git 提交 Skill

用途：

分析改动；
按业务目的拆分提交；
避免 git add .；
生成 Conventional Commit；
检查不应提交的文件。

官方文档提供了类似的 commit Skill 示例，强调按语义分组暂存和提交，而不是一次性提交全部文件。

推荐名称：

semantic-commit
prepare-commit
branch-cleanup

12.3 单元测试生成 Skill

用途：

分析分支条件；
生成正常场景；
生成边界场景；
生成异常场景；
生成 Mockito 测试；
执行测试并修复。

推荐名称：

java-unit-test
test-gap-analysis
integration-test

12.4 SQL 审核 Skill

用途：

检查全表扫描；
检查多行子查询；
检查重复数据；
检查索引；
检查更新范围；
生成回滚 SQL；
生成验证 SQL。

推荐名称：

oracle-sql-review
mysql-sql-review
database-change-review

12.5 API 设计 Skill

用途：

设计请求响应 DTO；
设计错误码；
设计幂等键；
检查兼容性；
生成 OpenAPI 文档；
生成接口测试。

推荐名称：

rest-api-design
openapi-generator
api-compatibility-review

12.6 Bug 修复 Skill

用途：

重现问题；
定位根因；
编写失败测试；
最小化修复；
运行回归测试；
输出根因说明。

推荐名称：

bug-investigation
root-cause-analysis
fix-and-verify

12.7 发布检查 Skill

用途：

检查未提交代码；
检查测试；
检查数据库脚本；
检查配置；
检查依赖；
生成发布说明。

推荐名称：

release-check
deployment-readiness
generate-release-notes

12.8 文档生成 Skill

用途：

生成 README；
生成详细设计；
生成数据库设计；
生成时序说明；
生成接口文档；
更新变更记录。

推荐名称：

technical-design
architecture-doc
readme-maintainer
changelog-generator

12.9 故障排查 Skill

用途：

收集日志；
梳理时间线；
分析调用链；
分析线程、数据库、缓存和消息队列；
输出根因和修复方案。

推荐名称：

production-incident-analysis
java-log-analysis
performance-troubleshooting

十三、程序员常用的插件

Codex 官方插件仓库中的示例覆盖了 Figma、Notion、Web、iOS、macOS、Expo、Netlify、Remotion、Google Slides 等工作流。插件目录的具体内容会持续变化，应以当前客户端中的 Plugins 页面为准。

13.1 Codex Security

用途：

代码安全扫描；
漏洞验证；
威胁模型分析；
PR 安全评审；
修复建议；
生成安全报告。

适合：

Java Web 项目；
支付系统；
管理后台；
对外 API；
身份认证系统。

注意：只应扫描自己拥有或明确获授权评估的代码。

13.2 GitHub 插件

用途：

读取 Issue；
读取 Pull Request；
总结代码变更；
分析 Review 评论；
创建 Issue；
辅助 PR 工作流。

适合：

PR 评审；
Bug 修复；
CI 问题排查；
需求追踪。

13.3 Slack 插件

用途：

总结频道消息；
提取行动项；
起草回复；
生成日报；
获取项目上下文。

13.4 Google Drive 插件

用途：

查找设计文档；
读取 Docs；
分析 Sheets；
生成 Slides；
汇总团队资料。

官方插件文档将 Google Drive 描述为能够跨 Drive、Docs、Sheets 和 Slides 工作的插件。

13.5 Gmail 插件

用途：

搜索邮件；
总结邮件线程；
提取待办；
起草回复；
管理邮件。

13.6 Figma 插件

用途：

读取设计信息；
根据设计生成前端代码；
检查设计系统规则；
将代码与设计稿关联。

OpenAI 官方插件仓库将 Figma 列为较完整的插件示例之一，包括设计系统规则和 Code Connect 等工作流。

13.7 Build Web Apps 插件

用途：

Web 页面开发；
UI 开发；
数据库工作流；
支付接入；
部署；
调试。

13.8 Notion 插件

用途：

项目规划；
知识库查询；
会议记录；
调研整理；
文档沉淀。

13.9 OpenAI Developers 插件

用途：

开发 OpenAI API 应用；
创建 Agent；
查询 OpenAI 官方开发文档；
配置 API；
设计工具调用。

十四、推荐的选择原则

只需要固定执行方法：使用 Skill

例如：

代码评审
SQL 检查
单元测试生成
接口设计
发布检查

这类任务不依赖外部系统，优先创建 Skill。

需要连接外部系统：使用 Plugin

例如：

读取 GitHub PR
查询 Jira
总结 Slack
读取 Google Drive
调用内部平台

这类任务需要 App 或 MCP Server，适合使用插件。

只对当前项目有效：使用项目级 Skill

project/.agents/skills/

希望多个项目都能使用：使用个人 Skill

$HOME/.agents/skills/

希望整个团队安装：打包为 Plugin

通过：

.agents/plugins/marketplace.json

创建项目或团队 Marketplace。

只是长期项目规则：写入 AGENTS.md

例如：

JDK 版本
构建命令
目录约束
代码风格
禁止修改范围
测试要求

十五、Skill 编写最佳实践

15.1 一个 Skill 只解决一类问题

不推荐：

all-java-development

里面同时包含：

写代码；
查 Bug；
发版本；
写 SQL；
生成文档；
部署生产。

推荐拆分成：

java-code-review
java-unit-test
oracle-update-review
release-check
incident-analysis

15.2 description 必须写清触发条件

不推荐：

description: Java helper.

15.3 明确不应该做什么

例如：

- 不自动执行生产 SQL。
- 不自动推送 Git 分支。
- 不自动合并 Pull Request。
- 不删除用户文件。
- 不修改数据库迁移历史。
- 不把密钥写入代码。

15.4 要求引用具体证据

代码评审 Skill 应规定：

每个问题必须包含：

- 文件路径；
- 行号；
- 问题说明；
- 触发条件；
- 运行时影响；
- 修复建议。

这样可以减少空泛的建议。

15.5 先写说明，再增加脚本

最开始只创建：

SKILL.md

当发现某一步必须稳定执行时，再增加：

scripts/check.sh
scripts/validate.py

不要一开始就把 Skill 做得过于复杂。

15.6 不要安装过多无关 Skill

Codex 会把可用 Skill 的元数据放入初始上下文。官方当前会限制这部分内容占用的上下文比例；Skill 太多时，描述可能被缩短，甚至部分 Skill 不进入初始列表。

因此建议：

按项目启用 Skill；
删除重复 Skill；
停用不常用插件；
保持 description 简洁；
避免多个 Skill 的触发范围完全重叠。

十六、插件使用的安全注意事项

16.1 检查插件来源

优先选择：

OpenAI 官方插件；
公司内部插件；
已审查的开源插件；
自己编写的插件。

16.2 检查 MCP 权限

确认 MCP 能够：

读取哪些数据；
修改哪些数据；
调用哪些 API；
是否能执行写操作；
是否能访问公司内部信息。

16.3 检查 Hook

插件 Hook 可能自动执行本地命令。

安装前需要检查：

hooks/
hooks.json

避免存在：

删除文件；
上传代码；
修改 Git 配置；
执行未知二进制文件；
自动推送代码；
访问敏感目录。

官方文档也明确要求在启用插件 Hook 前检查并信任相关命令。

16.4 不要把密钥写入 Skill

不要在以下文件中保存真实密钥：

SKILL.md
AGENTS.md
plugin.json
.mcp.json
scripts/

敏感信息应通过：

环境变量；
系统钥匙串；
企业密钥管理平台；
OAuth；
MCP Server 的安全认证机制；

进行管理。

16.5 公司项目应优先使用项目级配置

公司代码建议采用：

项目级 AGENTS.md
项目级 Skill
企业内部 Plugin Marketplace
经过审批的 MCP Server

不要随意安装来源不明的第三方插件。

十七、推荐的实际落地路线

对于刚开始使用 Codex Skill 和插件的程序员，可以分四个阶段实施。

第一阶段：先写 AGENTS.md

把项目基本规则整理出来：

技术栈
模块结构
构建命令
测试命令
编码规范
安全限制
禁止修改范围

第二阶段：创建三个核心 Skill

建议先创建：

java-code-review
java-unit-test
database-change-review

这三个 Skill 覆盖日常开发中最常见的场景。

第三阶段：添加脚本和参考资料

例如：

scripts/run-unit-tests.sh
scripts/check-sql.py
references/java-guidelines.md
references/database-rules.md
assets/review-report-template.md

第四阶段：封装成团队插件

当多个项目都需要时，创建：

company-java-engineering-plugin

插件可以包含：

代码评审 Skill
SQL 审核 Skill
发布检查 Skill
GitHub MCP
Jira MCP
Slack App
测试 Hook
报告模板

然后通过内部 Marketplace 分发。

十八、最终总结

Codex Skill 和插件不是互相替代的关系，而是上下层关系。

Skill
负责描述一个任务应该如何完成。

Plugin
负责把多个 Skill、外部工具、连接器、MCP 和 Hook
组合成一个可以安装和共享的完整能力包。

程序员可以按照下面的原则选择：

项目长期规则
    → AGENTS.md

重复执行的开发流程
    → Skill

访问外部系统和数据
    → MCP 或 App

将多个能力打包、安装和共享
    → Plugin

在特定阶段自动执行命令
    → Hook

最推荐的项目实践是：

AGENTS.md
    定义项目长期规则

.agents/skills/
    定义项目开发工作流

plugins/
    打包团队级完整能力

MCP Server
    连接 GitHub、Jira、Slack 和内部系统

Marketplace
    统一安装、升级和分发插件

当这些能力组合起来以后，Codex 就不再只是一个“根据提示词写代码的 AI”，而是逐渐成为一个理解团队规范、执行固定流程、连接研发系统并能够完成端到端任务的工程代理。

posted @ 2026-07-12 09:34 郭慕荣阅读(51) 评论(0) 收藏举报

刷新页面返回顶部

郭慕荣博客园

Codex Skill 和插件到底有什么区别？程序员如何在项目中落地使用

Codex Skill 和插件到底有什么区别？程序员如何在项目中落地使用

前言

一、先用一个实际例子理解 Skill 和插件

二、什么是 Codex Skill

2.1 Skill 的定义

SKILL.md

scripts/

references/

assets/

2.2 Skill 有什么作用

统一团队规范

固化复杂流程

提高输出稳定性

沉淀领域知识

减少重复提示

与脚本结合

2.3 Skill 和普通 Prompt 的区别

三、什么是 Codex 插件

3.1 插件的定义

3.2 插件有什么作用

统一安装

团队分发

连接外部系统

提供真实操作能力

增加生命周期自动化

管理权限和认证

四、Skill 和插件的核心区别

五、Skill、插件、AGENTS.md 和 MCP 的区别

5.1 AGENTS.md

AGENTS.md 适合写什么

Skill 适合写什么

5.2 MCP Server

5.3 App

5.4 Hook

六、怎么试用一个 Skill

6.1 方法一：使用内置 Skill 创建器

6.2 方法二：手动创建项目级 Skill

6.3 如何调用 Skill

显式调用

隐式调用

6.4 安装官方或精选 Skill

七、怎么试用插件

7.1 Codex 桌面端安装插件

7.2 Codex CLI 安装插件

7.3 IDE 扩展安装插件

八、如何自己创建一个 Skill

8.1 项目目录

8.2 SKILL.md 示例

8.3 使用方式

九、如何自己创建一个插件

9.1 最小插件结构

9.2 编写 plugin.json

9.3 添加 Skill

十、项目中怎么安装本地插件

10.1 项目级 Marketplace

10.2 个人 Marketplace

十一、Java 项目中推荐的落地结构

十二、程序员常用的 Skill

12.1 代码评审 Skill

12.2 Git 提交 Skill

12.3 单元测试生成 Skill

12.4 SQL 审核 Skill

12.5 API 设计 Skill

12.6 Bug 修复 Skill

12.7 发布检查 Skill

12.8 文档生成 Skill

12.9 故障排查 Skill

十三、程序员常用的插件

13.1 Codex Security

13.2 GitHub 插件

13.3 Slack 插件

13.4 Google Drive 插件

13.5 Gmail 插件

13.6 Figma 插件

13.7 Build Web Apps 插件

13.8 Notion 插件

13.9 OpenAI Developers 插件

十四、推荐的选择原则

`SKILL.md`

`scripts/`

`references/`

`assets/`