写一次 Skill，能否同时给 Codex、Cursor、Copilot 使用？Agent Plugins 1.0 来了

写一次 Skill，能否同时给 Codex、Cursor、Copilot 使用？Agent Plugins 1.0 来了

摘要

过去，为 Codex、Cursor、GitHub Copilot 编写同一种能力，经常要复制 Skill、重写 MCP 配置，再维护三套插件清单。2026 年 8 月发布的 Agent Plugins 1.0，第一次把可复用部分收敛为一个厂商中立的目录格式：根目录使用 plugin.json，工作流放进 skills/，MCP Server 放进 mcp.json。兼容客户端可以从同一份插件中发现并加载它们。

但“写一次，到处运行”并不等于所有配置都完全通用。Agent Plugins 1.0 目前只标准化了 Agent Skills 和 MCP Servers；Hooks、Rules、Commands、Custom Agents、安装入口、权限和认证仍由各客户端决定。

本文不只介绍概念，而是从零实现一个可以运行的 portable-sql-review 插件：同一份 SQL Review Skill 配合同一个本地 MCP Server，在 Codex、Cursor 和 GitHub Copilot 中复用，并给出安装、协议测试、功能验收和常见错误排查方法。

60 秒先看结论

答案是：可以，但要准确理解“写一次”的范围。

官方兼容列表目前同时列出了 Cursor、GitHub Copilot、ChatGPT & Codex；三者都支持 Agent Skills、stdio MCP 和 Streamable HTTP MCP。Agent Plugins：Compatible Clients

因此，正确的工程方式不是复制三套 Skill，而是分成两层：

可移植核心
├── plugin.json
├── skills/
└── mcp.json

客户端适配层
├── 安装与 Marketplace 配置
├── Hooks / Rules / Commands
├── 权限与认证
└── UI 与企业治理

一句话概括：

工作流和工具尽量只写一次；客户端特有能力放进独立适配层，不要污染可移植核心。

一、Agent Plugins 1.0 到底解决了什么

1. 以前真正重复的不是业务能力，而是外包装

假设团队做了一个“数据库变更审查”能力：

• Skill 规定审查步骤、风险等级和输出格式；
• MCP Server 对 SQL 做确定性扫描；
• Agent 负责理解上下文、判断业务语义并生成验证 SQL。

这些核心能力在 Codex、Cursor、Copilot 中没有本质区别。真正造成重复维护的通常是：

• 每个客户端的插件清单位置不同；
• Skill 目录约定不同；
• MCP 配置字段和传输方式不同；
• Hooks、Rules、Commands 混在插件主清单里；
• 一个版本修复后，另外两份副本忘记同步。

Agent Plugins 1.0 的价值，就是给共同部分定义一个最小交集。官方将它定义为一种厂商中立的可移植包格式，首个版本只标准化两个组件：Agent Skills 和 MCP Servers。Agent Plugins 1.0 规范

2026 年 8 月 6 日发布该标准时，初始维护成员来自 Amazon、Cursor、Microsoft、OpenAI 和 Vercel，Google 随后加入。GitHub Copilot 已在 VS Code、Copilot CLI、Copilot SDK 和 Copilot App 中提供支持。GitHub 发布说明

2. 它不是新的 Agent 框架

Agent Plugins 1.0 不负责：

• 调度 Agent；
• 选择模型；
• 保存聊天记忆；
• 定义完整权限模型；
• 统一所有厂商的 Hooks；
• 规定插件商店必须如何实现。

它解决的是更基础的问题：如何把已经存在的 Skill 和 MCP Server 放进一个结构稳定、可被多个客户端识别的目录中。

可以把几层标准理解为：

3. 为什么标准故意做得很小

如果第一版试图同时统一所有厂商的 Agent、Hook、Rule、Command 和权限机制，规范很可能还没发布就已经失效。

所以 Agent Plugins 1.0 只保留真正成熟的公共部分：

这种设计的重点不是“什么都能统一”，而是“统一的部分以后不需要再复制”。

二、一个标准 Agent Plugin 长什么样

最小插件只需要：

hello-plugin/
├── plugin.json
└── skills/
└── greet/
└── SKILL.md

一个同时包含 Skill 和 MCP Server 的实用插件通常是：

portable-sql-review/
├── plugin.json
├── skills/
│ └── sql-change-review/
│ ├── SKILL.md
│ └── references/
│ └── review-rules.md
├── mcp.json
├── server/
│ └── server.mjs
├── tests/
│ └── test-server.mjs
├── samples/
│ └── risky.sql
└── package.json

这里有三个不能混淆的文件：

1. plugin.json 不是随便写的 JSON

{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "portable-sql-review",
"version": "1.0.0",
"description": "Review SQL changes with a portable workflow and a deterministic local MCP checker.",
"author": {
"name": "Example Author"
},
"license": "MIT",
"keywords": ["sql", "database", "review", "migration", "safety"]
}

Agent Plugins 1.0 的根清单是闭合 Schema，只允许这些顶层字段：

$schema, name, version, description, author,
homepage, repository, license, keywords, extensions

因此下面这种看起来合理的写法，反而不是合规的 1.0 清单：

{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "wrong-example",
"skills": "./skills/",
"mcpServers": "./mcp.json",
"hooks": "./hooks.json"
}

问题在于：

• skills 不需要声明，客户端固定扫描 skills/；
• MCP 必须放在根目录 mcp.json，不能内联；
• Hooks 不是 Agent Plugins 1.0 的可移植组件；
• 未定义的顶层字段会被报告并忽略，不能依赖它们产生行为。

2. Skill 必须是 skills/ 的直接子目录

正确：

skills/sql-change-review/SKILL.md

错误：

skills/database/review/sql-change-review/SKILL.md

规范只发现 skills/ 下的直接子目录，不会递归搜索更深层级。每个 Skill 内仍然可以使用标准的 scripts/、references/ 和 assets/。

3. mcp.json 也有自己的 Schema

{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"portable-sql-review": {
"type": "stdio",
"command": "node",
"args": ["${PLUGIN_ROOT}/server/server.mjs"],
"cwd": "${PLUGIN_ROOT}"
}
}
}

这里有几个容易忽略的细节：

• command 必须是一个可执行文件名，不能写成整段 Shell 命令；
• 参数必须拆到 args 数组；
• ${PLUGIN_ROOT} 指向插件安装目录；
• ${PLUGIN_DATA} 指向客户端为插件分配的持久化可写目录；
• 两个 Schema 版本必须一致；
• 不要把 API Key 写进 env 或 HTTP headers。

Agent Plugins 1.0 没有统一 OAuth 和凭据保存协议，认证仍由客户端管理。插件清单中的 env、headers 都属于可见配置，不是安全的密钥存储。Agent Plugins 1.0 规范

三、实战：实现一个真正能用的 SQL Review Skill

这个示例不是“你好世界”，而是一个有明确工程价值的插件：

• Agent Skill 负责完整审查流程；
• MCP Tool 负责确定性的危险 SQL 扫描；
• Agent 再结合数据库类型、事务、锁和业务语义给出结论；
• 同一套核心文件交给 Codex、Cursor、Copilot 使用。

第一步：编写 Skill

创建 skills/sql-change-review/SKILL.md：

—
name: sql-change-review
description: Review SQL files, database migrations, DML, DDL, and stored-procedure changes for destructive operations, semantic drift, transaction risks, locking risks, and missing verification steps. Use when the user asks to review, migrate, execute, or troubleshoot SQL changes.
—

# SQL Change Review

Review the change as an engineering change, not as isolated SQL syntax.

## Workflow

1. Identify the target database, affected objects, execution environment, and intended business result.
2. Read the complete SQL change or diff. Do not infer omitted statements.
3. Call the `review_sql` tool from the `portable-sql-review` MCP server for every changed SQL script.
4. Treat tool findings as a deterministic first pass, not as proof that the SQL is safe.
5. Manually review:
– row-selection semantics and NULL behavior;
– transaction and exception boundaries;
– lock duration, index support, and expected row count;
– repeated execution and idempotency;
– source-to-target data meaning during database migrations;
– rollback, preimage capture, and post-execution verification.
6. Never execute destructive SQL merely because the static checker returned no finding.

## Required output

Return the review in this order:

1. 60-second conclusion: safe, needs confirmation, or blocked.
2. Risk table: severity, location, evidence, impact, and fix.
3. Required changes: only changes necessary before execution.
4. Verification SQL: pre-check, execution guard, and post-check.
5. Remaining uncertainty: facts that must be confirmed by a human or database owner.

这份 Skill 有四个关键点：

第二步：把领域规则放进 references

创建 skills/sql-change-review/references/review-rules.md：

# SQL review rules

## Block by default

– DELETE 或 UPDATE 缺少有效 WHERE 条件。
– TRUNCATE、DROP TABLE 或破坏性结构变更没有恢复方案。
– 执行环境不明确时操作生产数据库。
– 使用不可信输入拼接动态 SQL。
– 数据库迁移把“逐行成功/失败”改成“整批失败”却没有经过确认。

## Require evidence

– 预计和实际影响行数。
– 大批量 DML 的索引支持。
– 长时间操作的锁等待检查。
– 不可逆修改的执行前快照。
– 使用业务主键和金额核对，而不只是比较总行数。

## Oracle to PostgreSQL checks

– 空字符串与 NULL。
– NVL、DECODE、异常处理、自治事务、序列、日期计算和隐式转换。
– 过程返回协议与事务归属。
– 游标和批处理的逐行处理语义。
– 按业务含义核对字段映射，而不是只看字段名。

这样做比把所有内容塞进 SKILL.md 更合理：Skill 主文件保持短小，只有遇到数据库审查任务时，Agent 才按需读取详细规则。

第三步：实现确定性 MCP 检查器

下面的 Server 不依赖第三方 npm 包，只需要 Node.js。它实现了 MCP 初始化、工具发现和 review_sql 调用，并检查：

• 无有效 WHERE 的 DELETE；
• 无有效 WHERE 的 UPDATE；
• WHERE 1=1；
• TRUNCATE；
• DROP TABLE / DROP COLUMN；
• 动态 SQL；
• 写操作缺少验证和回滚证据。

核心扫描逻辑如下：

function reviewSql(sql, dialect = "generic") {
const normalized = String(sql ?? "")
.replace(/–.*$/gm, " ")
.replace(/\\/\\*[\\s\\S]*?\\*\\//g, " ");

const findings = [];

for (const match of normalized.matchAll(
/\\bDELETE\\s+FROM\\s+[\\w."`]+[\\s\\S]*?(?=;|$)/gi
)) {
const statement = match[0];
if (!/\\bWHERE\\b/i.test(statement) ||
/\\bWHERE\\s+1\\s*=\\s*1\\b/i.test(statement)) {
findings.push({
severity: "critical",
code: "DELETE_WITHOUT_FILTER",
message: "DELETE 缺少有效 WHERE 条件，可能删除整表数据。",
evidence: statement.trim()
});
}
}

for (const match of normalized.matchAll(
/\\bUPDATE\\s+[\\w."`]+[\\s\\S]*?(?=;|$)/gi
)) {
const statement = match[0];
if (!/\\bWHERE\\b/i.test(statement) ||
/\\bWHERE\\s+1\\s*=\\s*1\\b/i.test(statement)) {
findings.push({
severity: "critical",
code: "UPDATE_WITHOUT_FILTER",
message: "UPDATE 缺少有效 WHERE 条件，可能更新整表数据。",
evidence: statement.trim()
});
}
}

if (/\\bTRUNCATE\\b/i.test(normalized)) {
findings.push({
severity: "critical",
code: "TRUNCATE",
message: "检测到 TRUNCATE，必须确认环境和恢复方案。"
});
}

if (/\\bDROP\\s+TABLE\\b/i.test(normalized)) {
findings.push({
severity: "critical",
code: "DROP_TABLE",
message: "检测到 DROP TABLE，默认阻断。"
});
}

const blocked = findings.some(item => item.severity === "critical");

return {
dialect,
decision: blocked
? "blocked"
: findings.length
? "review_required"
: "no_static_finding",
findings,
disclaimer: "静态检查不替代执行计划、锁分析和业务语义核对。"
};
}

完整 MCP Server、测试脚本和示例 SQL 已放在本文配套包中。之所以不直接让 Skill 用自然语言判断全部风险，是因为：

• 正则扫描是确定性的；
• 同样的 SQL 每次得到相同结果；
• MCP Tool 可以独立测试；
• Agent 把精力用于事务、锁、字段映射和业务语义；
• 后续可以把简单规则替换为真正的 SQL Parser，而不改 Skill 的工作流。

这就是 Skill 与 MCP 正确的分工：

四、先测试插件，不要直接丢给 Agent

1. 测试 MCP 协议

配套包中的测试会完成四项检查：

运行：

cd portable-sql-review
node tests/test-server.mjs

预期输出：

PASS: initialize, tools/list, risky SQL, scoped SQL

如果这一步失败，不要先怀疑 Agent。问题仍然处在插件、Node.js 或 MCP 协议层。

2. 验证 JSON

python -m json.tool plugin.json > /dev/null
python -m json.tool mcp.json > /dev/null

这只能检查 JSON 语法。真正发布前还要按照 Agent Plugins Schema 验证字段、路径和类型。

3. 准备功能测试 SQL

samples/risky.sql：

— 预期：blocked
DELETE FROM demo_orders;

— 预期：blocked
UPDATE demo_order_items
SET quantity = 0
WHERE 1 = 1;

安装插件后，对三种客户端使用同一条验收指令：

请使用 sql-change-review 检查 samples/risky.sql，
给出 60 秒结论、风险表、修改建议和验证 SQL。

不要只检查 Agent 有没有“说危险”，还要检查：

• 是否确实调用了 MCP Tool；
• 是否识别两个危险语句；
• 是否给出 blocked；
• 是否没有擅自执行 SQL；
• 是否输出执行前和执行后验证方案；
• 是否说明静态扫描的能力边界。

五、同一份插件如何安装到 Cursor

Cursor 官方文档明确说明：符合 Agent Plugins 规范的插件可以不修改直接加载。开发阶段可以把插件放进本地插件目录。Cursor Plugins 文档

Windows

将插件复制到：

%USERPROFILE%\\.cursor\\plugins\\local\\portable-sql-review

macOS / Linux

mkdir -p ~/.cursor/plugins/local
cp -R ./portable-sql-review ~/.cursor/plugins/local/

然后：

如果 Skill 出现但 MCP 没出现，优先检查：

• Node.js 是否在 Cursor 进程可见的 PATH 中；
• mcp.json 是否在插件根目录；
• 文件名是否误写成 .mcp.json；
• command 是否写成了一整段 Shell 命令；
• 企业管理员是否关闭了本地插件导入。

六、同一份插件如何安装到 GitHub Copilot

Copilot CLI 支持直接从本地目录安装：

copilot plugin install ./portable-sql-review

查看是否安装成功：

copilot plugin list

进入交互会话后检查 Skill：

/skills list

然后使用统一验收指令检查 samples/risky.sql。

开发阶段修改了插件后，需要重新安装或开始新会话，让缓存中的组件刷新：

copilot plugin install ./portable-sql-review

GitHub 官方文档还支持从 Marketplace、GitHub 仓库、Git URL、子目录和本地绝对路径安装。GitHub Copilot CLI 插件文档

如果要加入 Copilot 特有的 Agent、Hook、Command 或 Rule，不要塞进 Agent Plugins 1.0 根清单。GitHub 的推荐做法是把 Copilot 特有文件放到它识别的客户端命名空间或兼容目录中，其他客户端忽略这些内容。

七、同一份插件如何安装到 Codex

Codex 支持通过 Marketplace 安装插件。本地开发时，可以建立一个最小 Marketplace：

portable-demo-marketplace/
├── .agents/
│ └── plugins/
│ └── marketplace.json
└── plugins/
└── portable-sql-review/
├── plugin.json
├── skills/
└── mcp.json

.agents/plugins/marketplace.json：

{
"name": "portable-demo",
"interface": {
"displayName": "Portable Demo"
},
"plugins": [
{
"name": "portable-sql-review",
"source": {
"source": "local",
"path": "./plugins/portable-sql-review"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
]
}

添加 Marketplace：

codex plugin marketplace add /absolute/path/to/portable-demo-marketplace

安装插件：

codex plugin add portable-sql-review@portable-demo

查看状态：

codex plugin list –json

也可以进入 Codex CLI 后执行：

/plugins

选择对应 Marketplace，检查并启用插件。完成安装后开启一个新会话，再执行统一验收指令。

Codex 的 Marketplace 可以引用原生 .codex-plugin/plugin.json、Claude 兼容插件、Agent Plugins 1.0 包或独立 Skill 包。OpenAI Codex 插件管理文档

需要注意：OpenAI 自己的公共插件目录还存在 .codex-plugin/plugin.json 原生打包格式。它与 Agent Plugins 1.0 根目录 plugin.json 不是同一个文件。团队内部跨客户端复用时，可以以 Agent Plugins 1.0 为核心；需要投递特定厂商的公共目录时，再增加该平台要求的发布元数据和适配文件。

八、“一次编写”真正应该怎样组织仓库

推荐使用单一仓库、一个可移植核心、多个薄适配层：

agent-plugin-repo/
├── plugins/
│ └── portable-sql-review/
│ ├── plugin.json
│ ├── skills/
│ ├── mcp.json
│ ├── server/
│ └── tests/
├── .agents/plugins/marketplace.json
├── .github/plugin/marketplace.json
└── adapters/
├── codex/
├── cursor/
└── copilot/

其中：

• plugins/portable-sql-review/ 是唯一业务能力来源；
• 两份 Marketplace 文件只是不同客户端的分发入口；
• adapters/ 只放无法标准化的 Hooks、Rules、Commands 或发布元数据；
• 不允许在适配层复制 SKILL.md；
• CI 必须验证所有适配层仍然指向同一个核心版本。

一个重要原则：不要为了“统一”而制造最低质量的 Skill

跨客户端通用的 Skill 应该避免依赖：

• 某个客户端独有的工具名称；
• 某种专属 Slash Command；
• 某个厂商的隐藏目录；
• 未标准化的 Hook 返回格式；
• 某个模型特有的提示词技巧。

但这不代表 Skill 只能写成空泛流程。正确做法是：

• 在 Skill 中引用逻辑工具名和目标能力；
• 在 MCP 中提供确定性工具；
• 把厂商特有增强放入适配层；
• 使用相同验收用例验证不同客户端的行为。

九、Hooks 为什么不能一起带走

这是 Agent Plugins 1.0 最容易被误解的地方。

当前 1.0 规范只定义：

Hooks、Custom Agents、Commands、Rules、LSP、UI 都不是可移植核心。原因是各客户端的：

• 生命周期事件不同；
• 输入和输出 JSON 不同；
• 阻断语义不同；
• 权限模型不同；
• 可执行脚本环境不同。

如果 SQL 审查插件还想在命令执行前强制拦截危险 SQL，应当：

公共 Skill：说明何时审查、怎么审查、输出什么
公共 MCP：执行确定性 SQL 风险扫描
Codex Hook：按 Codex 协议阻断危险命令
Cursor Hook：按 Cursor 协议阻断危险命令
Copilot Hook：按 Copilot 协议阻断危险命令
CI：作为最终、与客户端无关的合并门禁

这仍然比维护三份完整插件好，因为最复杂的工作流、规则和扫描器只有一份，客户端层只保留薄薄的事件适配。

Skill 负责指导，MCP 负责能力，Hook 负责节点控制，CI 负责最终强制。

十、最常见的 10 个失败原因

1. 把厂商原生清单当成 Agent Plugins 1.0

.codex-plugin/plugin.json、.cursor-plugin/plugin.json 与根目录 plugin.json 不是同一个格式。想要可移植，必须提供带 1.0 Schema 的根清单。

2. 在根清单中配置组件路径

1.0 使用固定发现位置。不要添加：

{
"skills": "./skills/",
"mcpServers": "./mcp.json"
}

3. 把 mcp.json 写成 .mcp.json

厂商旧格式可能使用 .mcp.json，但 Agent Plugins 1.0 的可移植核心固定使用根目录 mcp.json。

4. Skill 藏得太深

只扫描：

skills/<skill-name>/SKILL.md

不会继续递归寻找更深层 Skill。

5. command 写成 Shell 命令

错误：

{
"command": "node ./server/server.mjs –mode check"
}

正确：

{
"command": "node",
"args": ["${PLUGIN_ROOT}/server/server.mjs", "–mode", "check"]
}

6. 插件依赖当前工作目录

安装后路径会变化。访问插件内文件使用 ${PLUGIN_ROOT}，写缓存和安装依赖使用 ${PLUGIN_DATA}。

7. 把密钥提交进 env 或 headers

这些都是插件包的可见数据。认证必须交给客户端或外部安全凭据机制。

8. 认为 MCP 启动成功就代表 Skill 有效

至少分别验证：

• 插件清单；
• Skill 发现与触发；
• MCP 握手；
• 工具发现；
• 工具调用；
• Agent 是否遵循输出要求。

9. 认为一个客户端通过就代表三个都通过

标准允许客户端逐步实现组件。每个目标客户端都要运行相同验收用例，并记录版本。

10. 用 Skill 代替安全门禁

Skill 是提供给模型的工作流，不是不可绕过的权限系统。删除数据、发布生产、发送消息等高风险动作，仍然需要 Hook、审批、沙箱或 CI。

十一、发布前检查清单

插件结构

• 根目录存在 plugin.json。
• $schema 精确指向 1.0.0/plugin.schema.json。
• 插件名只使用允许的小写字母、数字、连字符或点号。
• 根清单没有 skills、mcpServers、hooks 等非法顶层字段。
• 每个 Skill 都位于 skills/<name>/SKILL.md。
• MCP 配置位于根目录 mcp.json。
• plugin.json 与 mcp.json 的 Schema 版本一致。

MCP

• command 是单个可执行文件名。
• 参数全部放在 args。
• 插件文件路径使用 ${PLUGIN_ROOT}。
• 持久化数据使用 ${PLUGIN_DATA}。
• 没有把密钥写进 env 或 headers。
• stdio Server 能完成 initialize、tools/list 和 tools/call。
• Server 错误不会导致整个插件其他 Skill 无法加载。

Skill

• name 与目录名称清晰且稳定。
• description 同时说明“做什么”和“什么时候触发”。
• 明确工具调用顺序。
• 明确缺少信息时如何处理。
• 明确危险动作的人工确认条件。
• 明确最终输出格式。
• 没有写死某一客户端独有命令。

跨客户端验收

• Cursor 能发现 Skill 和 MCP Tool。
• Copilot 能发现 Skill 和 MCP Tool。
• Codex 能发现 Skill 和 MCP Tool。
• 三端使用同一测试输入。
• 三端都识别高风险 SQL。
• 三端都没有擅自执行危险操作。
• 差异只存在于安装、权限或客户端适配层。

十二、最终结论

Agent Plugins 1.0 让“一份 Skill 同时给 Codex、Cursor、Copilot 使用”从手工复制变成了正式的标准能力，但它不是魔法。

真正可以一次编写的是：

• Skill 工作流；
• Skill 引用的脚本、规则和资源；
• MCP Server；
• MCP 的标准启动与连接配置。

仍然需要分别处理的是：

• Marketplace 和安装入口；
• Hooks、Rules、Commands、Custom Agents；
• 权限、认证和密钥；
• UI、企业策略和发布审核。

所以，最稳妥的落地方式不是追求“三端零差异”，而是：

用 Agent Plugins 1.0 保存唯一的可移植核心，用很薄的客户端适配层处理剩余差异，再用一套相同的验收用例防止行为漂移。

对于团队来说，它真正减少的不是一个 SKILL.md 的复制动作，而是长期维护中最麻烦的版本分叉、规则漂移和工具配置重复。