ChatGPT 与 Codex Skills / Plugins 使用笔记

学习教程更新于 2026-08-17编辑本文

一句话理解

Skill：把可重复的做事方法写成指令，并附带参考资料、模板或脚本。
Plugin：可安装、可分发的能力包，可组合 Skill、Connector、MCP Server、Hook 和资源。
Connector：面向 GitHub、Drive、Slack 等服务的连接；底层由 MCP Server 提供工具。
MCP Server：负责实时数据、认证授权、受控操作和结构化工具调用。

选择原则：只需固定流程时用 Skill；需要安装分发、外部服务或多项能力时用 Plugin；需要实时数据或执行外部操作时再加 MCP Server。

能力与可用范围

能力	适用入口	关键限制
独立 Skill	ChatGPT 桌面端、Codex CLI、Codex IDE 扩展	Web / 移动端主要使用 Plugin 内置的 Skill
Plugin	ChatGPT Web、桌面端、移动端的 Chat / Work；桌面端 Codex；Codex CLI	Codex IDE 扩展不支持 Plugin
Record & Replay	macOS 的 ChatGPT 桌面端	需要启用 Computer Use

安装 Plugin 后应新建会话，内置 Skill、Connector 和 MCP 工具才会进入新会话。通过 API Key 登录 Codex 时，部分依赖 OAuth 的 Plugin 可能不可用。

日常使用

安装与调用 Plugin

打开 Plugins，搜索或浏览目录，进入详情后点 + 安装。
如需 Connector，按提示完成连接与授权；仔细检查权限范围。
新建 ChatGPT 或 Codex 会话，直接描述结果，让系统自动选工具；需要确定能力时显式指定。
ChatGPT 用 @ 选择 Plugin 或 Skill；Codex CLI / IDE 用 $skill-name，也可先执行 /skills 查看。

卸载 Plugin 只移除能力包，已连接的 Connector 不一定自动断开，需要在 ChatGPT 的连接管理中单独处理。

调用 Skill

显式调用：结果必须遵循某个流程时，直接使用 @skill 或 $skill。
隐式调用：只描述任务，由系统根据 Skill 的 name 和 description 匹配。
隐式触发不准时，先改 description；已正确触发但产出不稳时，再改正文步骤。

创建 Skill

最快方式：ChatGPT Work 使用 @skill-creator，Codex 使用 $skill-creator。已经有稳定操作流程且“演示比描述更容易”时，可在 macOS 用 Record & Replay 录制，再审查生成的 Skill。

最小结构：

my-skill/
├── SKILL.md              # 必需：元数据和流程
├── references/           # 可选：规范、示例、背景资料
├── assets/               # 可选：模板、图片、静态资源
├── scripts/              # 可选：确定性计算或文件处理
└── agents/openai.yaml    # 可选：界面、触发策略、工具依赖

最小 SKILL.md：

---
name: my-skill
description: 说明能完成什么，以及什么请求应触发它。
---

1. 明确输入。
2. 按顺序执行步骤。
3. 按约定格式输出。
4. 验证结果；失败时说明停止条件。

编写规则

一个 Skill 只解决一个可识别目标；不同触发条件、输入或成功标准应拆开。
name 与目录名一致，只用小写字母、数字和连字符，长度不超过 64。
description 不超过 1024 字符，同时写清“做什么”和“何时用”，把关键词和边界放在前面。
正文明确输入、步骤、输出、禁止推断项、提问或停止条件，以及何时读取辅助文件。
优先写指令；只有需要确定性行为或文件处理时才加脚本。
建议 SKILL.md 少于 500 行、正文少于约 5000 tokens；详细内容拆到一层引用文件。

系统会渐进加载：启动时只加载所有 Skill 的名称和描述，命中后读取完整 SKILL.md，需要时再读资源。Codex 的初始 Skill 列表最多占上下文窗口约 2%；Skill 太多时描述会缩短，甚至省略部分条目，因此触发关键词必须靠前。

Codex 本地位置

范围	位置	用途
当前目录或仓库	从 `$CWD/.agents/skills` 向上扫描至 `$REPO_ROOT/.agents/skills`	团队共享、目录或仓库专用
用户	`$HOME/.agents/skills`	跨仓库个人 Skill
管理员	`/etc/codex/skills`	机器或容器统一配置
系统	OpenAI 内置	通用 Skill

Codex 支持符号链接。可在 ~/.codex/config.toml 用 [[skills.config]] 的 path 与 enabled = false 禁用 Skill；配置变化未生效时重启 Codex。

测试 Skill

至少覆盖五类请求：

类型	验证点
直接请求	明确命中并完整执行
间接请求	同义表达也能命中
输入缺失	先询问，不擅自补全
负例	不应触发时保持不触发
边界情况	不编造、不越权，能停止或降级

创建与分发 Plugin

Plugin 根目录必须包含 .codex-plugin/plugin.json，其他组件放在根目录：

my-plugin/
├── .codex-plugin/plugin.json
├── skills/
├── .app.json       # 已注册 MCP Server 的映射
├── .mcp.json       # 随包分发的 MCP Server 配置
├── hooks/hooks.json
└── assets/

优先用 ChatGPT 的 @plugin-creator 或 Codex 的 $plugin-creator 生成清单与本地 Marketplace。手工最小清单：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "一句话说明用途",
  "skills": "./skills/"
}

路径必须以 ./ 开头、相对 Plugin 根目录解析并保持在根目录内。只有 plugin.json 放进 .codex-plugin/。

本地 Marketplace

仓库级：$REPO_ROOT/.agents/plugins/marketplace.json
个人级：~/.agents/plugins/marketplace.json
一个 Marketplace 可以列出多个 Plugin；source.path 从 Marketplace 根目录解析，必须以 ./ 开头。
修改本地 Plugin 后更新 Marketplace 指向的目录，重启 ChatGPT 桌面端，再从 Plugins 目录安装并在新会话测试。
CLI 可用 codex plugin marketplace add/list/upgrade/remove 管理来源；本地 Plugin 的安装与测试仍在桌面端完成。

何时增加 MCP Server

需要实时数据、登录鉴权、远程计算或可控写操作时才增加 MCP Server。开发顺序是“工具先可用，再考虑 UI”。

一个工具对应一个明确动作，使用清晰名称、输入/输出 Schema 和稳定 ID。
服务器必须逐请求做认证和授权，不能让模型代替权限判断。
只读工具正确设置 readOnlyHint；影响公开系统时设置 openWorldHint；不可逆操作设置 destructiveHint。
工具结果不要包含密钥、令牌、无关个人数据或调试载荷；_meta 对模型隐藏，但不是安全存储。
本地用 MCP Inspector 验证初始化、工具、Schema、错误、注解和授权；公开服务使用稳定 HTTPS Streamable HTTP 端点，通常为 /mcp。

发布检查

公开 Plugin 提交前确认：

发布组织具有 Plugin 提交写权限，并完成个人或企业身份验证。
MCP 使用公开、稳定的生产地址；域名验证、OAuth、CSP 和演示账号可供审查。
清单、Skill 文件树、工具 Schema、安全注解、隐私政策和实际行为一致。
准备真实 Starter Prompts、至少 5 个正向和 3 个负向测试用例。
提交后先进入 OpenAI 审核；批准后仍需由开发者执行发布，才会进入 ChatGPT 与 Codex 共用的公共目录。

快速决策

需求	方案
固化个人或团队步骤	仓库级 / 用户级 Skill
通过演示生成流程	Record & Replay，再审查生成的 Skill
跨团队安装和复用	Skills-only Plugin
读取外部实时数据	Plugin + Connector / MCP Server
执行受控写操作	MCP Server + 服务端授权 + 准确安全注解
需要表格、地图或编辑界面	工具稳定后再加 MCP UI
面向公众分发	完整 Plugin 清单、测试、合规材料与审核发布