Codex 插件实战：把 Skill 变成可安装、可分发的 Plugin

本文以我现有的 super-frontend-design Skill 为例，完整演示如何把一个已经能工作的 Skill 封装成 Codex Plugin，再通过 Marketplace 安装和分发。重点不是讲概念，而是给出一条可以照着复现的路径。

一、为什么要把 Skill 做成 Plugin？

我之前做过一个 super-frontend-design Skill。

它解决的问题很直接：

AI 能生成前端代码，但“能跑”不等于“像专业产品”。

所以我给它加入了一套比较硬的设计约束，例如：

• 不使用 Emoji 充当 UI 图标
• 优先使用 Lucide / Tabler SVG 图标
• 需要真实图片时使用真实摄影素材
• 强调响应式、可访问性和完整视觉层级
• 输出尽可能接近生产级页面，而不是 Demo

原来的使用方式大概是：

下载 Skill
↓
复制到指定目录
↓
让 Claude Code / Codex 读取
↓
开始执行

能用，但当 Skill 越来越多以后，会出现几个问题：

• 不同电脑需要重新复制
• 团队成员要自己配置
• Skill、脚本、资源文件不好统一管理
• Skill + MCP 等能力不好一起分发
• 更新版本没有统一入口

这就是 Plugin 开始有价值的地方。

可以先用一句话理解：

Skill = 告诉 Agent 怎么做
MCP = 给 Agent 什么工具
Plugin = 把这些能力打包、安装和分发

二、当前 Codex Plugin 的基本结构

以 Codex 官方仓库当前提供的 $plugin-creator 为准，一个 Plugin 的核心 Manifest 位于：

.codex-plugin/plugin.json

官方的 Plugin Creator 还支持创建：

skills/
hooks/
scripts/
assets/
.mcp.json
.app.json

也就是说，一个 Plugin 不只是一个 Prompt 文件，它可以把 Agent 工作所需的多类资源放在同一个安装单元里。

这次我们的目标不是重写 super-frontend-design，而是：

保留已有 Skill，只增加 Plugin 封装层。

最终目录可以整理成：

super-frontend-design/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   └── super-frontend-design/
│       ├── SKILL.md
│       ├── templates/
│       ├── examples/
│       └── .env.example
├── assets/
└── README.md

这里职责非常清楚：

Plugin
负责安装、管理和分发

Skill
负责真正的工作流和规则

三、最快的方法：直接用 $plugin-creator

如果你当前 Codex 环境里已经有官方 Plugin Creator，可以直接调用：

$plugin-creator

然后给它一个明确任务，例如：

Create a plugin named super-frontend-design.

Package my existing super-frontend-design skill.

Requirements:

- Keep the existing SKILL.md
- Keep templates and examples
- Never use emoji as UI icons
- Prefer Lucide or Tabler SVG icons
- Generate responsive production-ready frontend code
- Add the plugin to a personal marketplace

官方 Plugin Creator 当前会创建一个基础 Plugin 骨架，并要求核心 Manifest 保持在：

<plugin-path>/.codex-plugin/plugin.json

如果要同时创建 Skill 目录，可以使用官方脚本的：

python3 scripts/create_basic_plugin.py super-frontend-design \
  --with-skills \
  --with-assets \
  --with-marketplace

实际路径要根据你的 Plugin Creator 所在位置调整。

创建完以后，建议先检查目录，再运行官方校验脚本：

python3 scripts/validate_plugin.py <plugin-path>

不要跳过校验。

因为 Manifest 字段错误、残留 TODO、版本号不合法等问题，都会导致后续安装体验很差。

四、plugin.json 要放什么？

一个最小可用思路是：

{
"name": "super-frontend-design",
"version": "0.1.0",
"description": "Create production-grade frontend interfaces.",
"author": {
"name": "adu666"
  },
"skills": "./skills/",
"interface": {
"displayName": "Super Frontend Design",
"shortDescription": "Create professional frontend interfaces.",
"longDescription": "Generate distinctive, responsive and production-grade frontend interfaces.",
"developerName": "adu666",
"category": "Productivity",
"capabilities": [],
"defaultPrompt": "Create a professional production-grade frontend interface."
  }
}

实际字段请以你当前安装的 Plugin Creator 校验规则为准。

最关键的是这一类关系：

"skills": "./skills/"

它把 Plugin 和内部 Skills 关联起来。

也就是说，我们不需要把原来的 Skill 全部改写。

五、把原来的 Skill 迁进来

我原来的 super-frontend-design 仓库已经有：

SKILL.md
templates/
examples/
.env.example

因此迁移其实很简单：

skills/
└── super-frontend-design/
    ├── SKILL.md
    ├── templates/
    ├── examples/
    └── .env.example

Plugin 负责“装进去”。

Skill 继续负责：

• 页面设计规则
• UI 约束
• 图片规范
• 图标规范
• 前端实现要求
• 输出步骤

这也是我认为 Plugin 很适合已有 Skill 作者的原因：

以前的工作没有白做。

六、接下来做 Marketplace

单独有 Plugin 还不够。

真正改变分发体验的是 Marketplace。

Codex 当前 Plugin Creator 的 Marketplace 结构使用：

.agents/plugins/marketplace.json

一个简单的 Marketplace 可以是：

{
"name": "personal",
"interface": {
"displayName": "Personal"
  },
"plugins": [
    {
"name": "super-frontend-design",
"source": {
"source": "local",
"path": "./plugins/super-frontend-design"
      },
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
      },
"category": "Productivity"
    }
  ]
}

官方当前对 policy.installation 支持的值包括：

NOT_AVAILABLE
AVAILABLE
INSTALLED_BY_DEFAULT

对 policy.authentication 支持：

ON_INSTALL
ON_USE

对于普通个人 Plugin，先用：

{
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
}

已经够了。

七、个人 Marketplace 和团队 Marketplace 不一样

这里非常容易写错。

个人 Marketplace

官方 Plugin Creator 当前默认的个人 Marketplace 路径是：

~/.agents/plugins/marketplace.json

这个默认个人 Marketplace 会被 Codex 自动发现。

因此：

默认个人 Marketplace 不需要额外执行 codex plugin marketplace add。

安装 Plugin 时使用：

codex plugin add super-frontend-design@<marketplace-name>

如果顶层 Marketplace 名称就是：

"name": "personal"

那么就是：

codex plugin add super-frontend-design@personal

非默认 / 团队 Marketplace

如果你做的是一个仓库级 Marketplace，例如：

codex-plugins/
├── .agents/
│   └── plugins/
│       └── marketplace.json
└── plugins/
    └── super-frontend-design/

这种非默认 Marketplace 才需要先把 Marketplace 加入 Codex：

codex plugin marketplace add <path-to-marketplace-root>

这一点建议严格以你本机 codex plugin --help 输出和当前版本官方仓库为准。

八、安装完成后，一定要新开 Session

Plugin 安装成功以后，不建议直接在旧 Session 里测试。

官方当前的安装更新说明建议：

重新安装或更新以后，新开一个 Thread / Session。

因为新的 Skills、MCP Tools 等能力需要在新的上下文边界重新加载。

所以正确流程是：

安装 Plugin
↓
关闭当前 Session
↓
新建 Session
↓
再测试 Plugin

很多“Plugin 装了但是没效果”的问题，其实不是 Skill 写坏了，而是仍然在用旧 Session。

九、真实测试：别用 Hello World

这篇文章如果只测试：

hello world

价值很低。

我的测试方式会直接让 Codex 做一个真实页面。

例如：

Use super-frontend-design.

Create a landing page for an AI coding product.

Tech stack:
- Next.js
- Tailwind CSS

Requirements:
- Dark technical visual style
- Hero section
- Product features
- Workflow
- Pricing
- FAQ
- CTA
- Fully responsive
- Production-ready code

Do not use emoji as icons.
Use professional SVG icons.
Use real visual assets where appropriate.

然后完整观察：

理解需求
↓
读取 Skill
↓
确定视觉方案
↓
创建项目
↓
生成页面
↓
运行项目
↓
检查问题
↓
继续修改
↓
最终页面

文章里建议至少保留三类真实截图：

1. Codex 识别 Plugin / Skill
2. Codex 实际执行过程
3. 浏览器中的最终页面

这样才能真正证明：

Plugin 不只是“安装成功”，而是真的改变了 Codex 的工作方式。

十、Skill、MCP、Plugin 到底怎么选？

Skill

适合：

开发规范
执行流程
代码审查规则
设计方法
项目约束
提示策略

解决的是：

Agent 应该怎么做？

MCP

适合：

数据库
GitHub
企业系统
内部 API
第三方服务
工具调用

解决的是：

Agent 可以使用什么外部能力？

Plugin

适合把：

Skill
MCP
脚本
资源
配置

组合到一起，并提供统一的：

安装
更新
管理
分发

一句话：

Skill = 说明书
MCP = 工具箱
Plugin = 安装包

十一、Plugin 真正改变的是什么？

如果只理解成：

Plugin 就是给 Skill 加一个壳。

其实低估它了。

我认为 Plugin 真正重要的变化是：

Agent 能力开始“软件化”。

以前给 AI 增加能力：

复制 Prompt
↓
复制 Markdown
↓
复制 Skill
↓
手动修改配置

现在开始变成：

找到 Plugin
↓
安装
↓
授权
↓
新开 Session
↓
直接使用

进一步，一个团队完全可以维护自己的 Agent 能力仓库：

company-agent-plugins/
├── frontend-design
├── code-review
├── database-design
├── testing
├── deploy
└── documentation

新人加入以后，不一定要先知道：

团队的 30 个 Prompt 到底放在哪？

而可能只需要：

安装团队 Plugin。

从这个角度看，Plugin 已经很接近：

Agent 时代的能力包管理机制。

十二、下一步我准备怎么做

这次只是把：

super-frontend-design Skill

升级为：

Codex Plugin

下一步我准备继续做两个方向。

1. 把常用 Skill 全部 Plugin 化

例如：

前端设计
代码 Review
文档生成
项目初始化
UI 检查
发布流程

2. 做自己的 Codex Plugin Marketplace

以后分享的可能不只是：

一段 Prompt

而是：

一个可以直接安装到 Codex 里的能力

这件事，我觉得比“再写 100 条 Prompt”更值得开发者关注。

最后

如果你已经有：

CLAUDE.md
AGENTS.md
SKILL.md
MCP Server
Agent 工作流

现在可以开始想一个问题：

这些能力，能不能进一步变成 Plugin？

Prompt 解决的是：

这一次怎么让 AI 做好。

Skill 解决的是：

怎么让 AI 重复做好。

Plugin 开始解决的是：

怎么把这套能力真正交付给别人。

这三个阶段，已经完全不一样了。

参考资料

• super-frontend-design
  https://github.com/adu666/super-frontend-design

注：Codex Plugin 仍处于快速迭代阶段。命令、Manifest 字段和 Marketplace 行为可能随版本变化。实际操作前建议执行 codex plugin --help，并以当前版本官方仓库与文档为准。