源项目 1： OpenAI Codex Agent Skills

相关工具： $skill-creator

官方用例： Save workflows as skills

官方最佳实践： Codex Best Practices

源项目 2： mattpocock/skills

被对照 Skill： writing-great-skills / SKILL.md

Codex Skill Creator 负责创建，writing-great-skills 负责评审，真正缺的是 Eval、Security 和分发治理。

Codex 负责把 Skill 做出来，Matt 的方法论负责判断 Skill 做得好不好。

一句话结论

Codex 的 $skill-creator 和 Matt Pocock 的 writing-great-skills 不是竞争关系，而是上下游关系。

Codex $skill-creator 解决的是：如何把一个重复工作流快速做成 Skill。

writing-great-skills 解决的是：如何判断一个 Skill 写得好不好。

前者偏工程生成，后者偏设计评审。

真正有价值的整合方向，是把两者变成一套完整的 Skill 工程流程：

Create → Review → Rewrite → Eval → Package

也就是说，Agent Skill 的下一阶段，不是写更多 Skill，而是把 Skill 从「Prompt 文件」升级成「可创建、可评审、可验证、可分发的工程资产」。

一、为什么要写这篇姊妹篇？

上一篇我们评测了 Matt Pocock 的 writing-great-skills。

它最重要的判断是：

Skill 的本质不是提示词，而是可预测流程。

它强调 predictability、invocation、context load、completion criterion、progressive disclosure、leading word、failure modes 等概念。这些概念很适合作为 Skill 设计原则。

但它也有一个明显短板：

它更像 Skill 方法论，不像一个完整的 Skill 创建器。

而 Codex 的 $skill-creator 刚好补上了另一半。

OpenAI 官方文档把 Codex Skills 定义成一种可复用工作流的 authoring format。一个 Skill 是一个目录，包含必需的 SKILL.md，也可以包含 scripts/、references/、assets/ 和 agents/openai.yaml 等支持文件；Codex 可以通过显式 $skill 调用，也可以根据 description 进行隐式调用。

这说明 Codex 已经把 Skill 当成一种工程包，而不是一段 prompt。

所以问题就变成了：

Codex 能帮我们把 Skill 做出来，但它是否足够帮助我们把 Skill 做好？

我的判断是：还不够。

这正是 writing-great-skills 可以补上的地方。

二、Codex $skill-creator 是什么？

Codex 官方文档中提到，如果你已经知道工作流，并且更容易通过示范表达，可以使用 Record & Replay；如果你想直接描述一个 Skill，则可以使用内置的 $skill-creator。

这个 creator 会询问 Skill 做什么、什么时候触发，以及是 instruction-only，还是需要包含 scripts；默认是 instruction-only。

官方 use case 还给了一个非常清楚的使用方式：

你可以把一个有效的 Codex thread、团队 runbook、PR review 规则、测试命令、发布 checklist、设计规范、写作样例，沉淀成未来线程可复用的 Skill。

官方建议从一个 working example 开始，再让 $skill-creator 帮你 scaffold Skill，并验证结果。

所以 Codex $skill-creator 的本质是：

把一次有效经验，沉淀成一个可复用 Skill。

它很像一个 Skill 脚手架工具。

输入是：

  • 一个重复出现的任务
  • 一个已经跑通过的工作流
  • 一份 runbook
  • 一套团队规范
  • 一个好结果样例
  • 一组命令或脚本

输出是：

  • SKILL.md
  • references/
  • scripts/
  • assets/
  • 必要的元信息

这非常工程化。

三、Codex 的强项：把 Skill 当成工程包

Codex Skills 最值得学习的地方，是它没有把 Skill 降级成「长提示词」。

官方文档里，一个 Skill 的目录结构大致是：

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

其中 SKILL.md 是必需的，scripts/ 用来放可执行代码，references/ 用来放文档，assets/ 用来放模板和资源，agents/openai.yaml 可以配置 UI 元数据、调用策略和工具依赖。

这背后有一个重要变化：

Skill 不再只是 instruction，而是 instruction + resource + script + metadata。

这比单纯写 Markdown 更接近生产环境。

因为在真实任务中，很多事情不应该靠模型自由发挥。

场景更适合放在哪里
可变的操作步骤SKILL.md
长规范、API 文档、schemareferences/
确定性转换、校验、批处理scripts/
模板、样例、素材assets/
UI 展示、依赖、调用策略agents/openai.yaml

这套结构说明 Codex 已经把 Skill 看成一种轻量软件包。

这是它比很多社区 Skill 更成熟的地方。

四、Codex 的第二个强项：从真实任务出发

Codex 官方用例里反复强调：创建 Skill 要从一个 working example 开始。

这个 example 可以是一段 Codex thread、一个 Slack 讨论、一个 PR review、一个 release checklist、一份 runbook、一个已经被接受的最终输出。

官方还建议给 $skill-creator 提供工作示例、来源材料、repo 路径、可复用命令和好结果样例。

这个原则非常重要。

很多 Skill 失败，不是因为写得不够长，而是因为没有真实任务样本。

没有真实样本，就无法判断：

  • 用户会怎么触发？
  • Agent 应该先做什么？
  • 哪些步骤必须固定？
  • 哪些资料应该外置？
  • 哪些部分应该脚本化？
  • 什么才叫做完成？
  • 什么输出才算好？

所以 Codex 的创建方法有一个很强的产品感：

不要从抽象能力开始。
要从重复出现的真实任务开始。

这点应该成为所有 Skill 工程的第一原则。

五、Codex 的短板：它偏“创建”，不偏“评审”

Codex $skill-creator 的问题也很明显。

它可以帮你把 Skill 做出来，但它不够系统地回答：

这个 Skill 写得好不好？

比如，一个 Skill 生成以后，还需要继续判断：

  • description 是否过宽？
  • 是否容易误触发？
  • 是否存在多个 trigger branch 混在一起？
  • SKILL.md 是否太长？
  • 是否把 reference 写成了 step？
  • 是否每一步都有 completion criterion？
  • 是否存在 no-op 指令？
  • 是否会导致 premature completion？
  • 是否需要拆成多个 Skill？
  • 是否真的比无 Skill baseline 更好？

Codex 官方最佳实践确实提到：一个好的 Skill 应该聚焦一个 job，从 2 到 3 个具体 use cases 开始，定义清楚 inputs 和 outputs，description 要说明什么时候使用，并且只在能提升可靠性时加入 scripts 或 assets。

但这些更像通用建议，不是完整评审体系。

所以 Codex 的 $skill-creator 适合解决：

从 0 到 1 创建 Skill。

但还不足以解决：

从能用到好用。
从好用到可验证。
从可验证到可分发。

六、Matt 的强项：提供 Skill 质量评审语言

Matt Pocock 的 writing-great-skills 刚好补上了这一层。

它最强的地方不是创建目录结构，而是建立了一套 Skill 质量语言。

它强调：

  • Skill 的根本价值是 predictability
  • description 要 front-load leading word
  • 每个 trigger branch 不要用重复同义词堆叠
  • 每个 step 都要有 completion criterion
  • SKILL.md 要区分 step、reference 和 external reference
  • Skill 要防止 duplication、sediment、sprawl、no-op
  • 当 user-invoked Skill 太多时，需要 router skill
  • 要通过 pruning 控制上下文负担

这些概念非常适合做 Skill Review。

它回答的不是「Skill 怎么生成」，而是「Skill 怎么变得更稳定」。

这是 Codex 目前相对欠缺的部分。

七、两者真正的区别

可以用一张表看清楚：

维度Codex $skill-creatorMatt writing-great-skills
核心定位Skill 创建器Skill 设计方法论
解决问题怎么把工作流做成 Skill怎么判断 Skill 是否写得好
主要输入真实工作流、runbook、thread、命令、好结果已有 Skill、设计意图、触发场景
主要输出Skill 目录、SKILL.md、references、scripts、assets评审原则、改写标准、失败模式
强项工程落地、目录结构、资源组织可预测性、调用设计、信息分层、完成标准
短板质量评审不够系统创建和打包能力不强
更像什么脚手架评审尺
适合阶段CreateReview / Rewrite

一句话总结：

Codex 负责把 Skill 做出来；
Matt 负责判断 Skill 做得好不好。

八、最好的整合：不要二选一，要做 Skill 工程闭环

真正值得做的，不是选择 Codex 还是 Matt，而是把它们整合成一条完整链路。

我建议的 Skill 工程闭环是：

Capture → Create → Review → Rewrite → Validate → Eval → Package

1. Capture：捕捉真实任务

先不要写 Skill。

先收集真实任务样本。

包括：

  • 用户真实怎么提问
  • Agent 第一次怎么做
  • 哪些地方反复需要纠正
  • 哪些输出被接受
  • 哪些步骤每次都重复
  • 哪些命令或脚本经常被使用

没有真实任务，不要急着做 Skill。

2. Create：用 Codex 思路生成 Skill

这一层吸收 Codex $skill-creator 的优点。

把真实工作流沉淀为：

SKILL.md
references/
scripts/
assets/
metadata

这里的关键不是追求完美，而是先把一个代表性任务跑通。

3. Review：用 Matt 标准评审 Skill

这一层吸收 writing-great-skills 的方法论。

重点检查：

  • 是否服务于 predictability？
  • description 是否精准？
  • 是否存在误触发？
  • step 是否有 completion criterion？
  • reference 是否应该外置？
  • 是否存在 no-op、sprawl、duplication？
  • 是否应该拆成多个 Skill？

4. Rewrite：重写成更稳定的 Skill

评审不是目的，改写才是目的。

重写时重点做四件事：

压缩 description
拆分信息层级
补全完成标准
外置低频参考资料

5. Validate：做格式和结构校验

这一层解决「Skill 格式是否正确」。

检查：

  • frontmatter 是否完整
  • name / description 是否符合规范
  • 路径是否正确
  • scripts 是否可执行
  • references 是否可访问
  • metadata 是否合法

6. Eval：验证 Skill 是否真的有效

这是最关键但最容易缺失的一步。

至少做两类测试：

Eval 类型测什么
Invocation Eval该触发时是否触发，不该触发时是否误触发
Execution Eval触发后是否按预期流程完成，是否比无 Skill 更好

这一步决定 Skill 是主观好，还是客观有效。

7. Package：进入分发与生态

当 Skill 通过验证后，再考虑打包、共享、进入团队仓库或插件体系。

Codex 官方也区分了本地 Skill authoring 和面向更广泛分发的 plugin packaging：直接 Skill 文件夹适合本地和 repo-scoped 工作流，想要可复用分发时，可以将 Skill 打包为 plugin。

九、可以沉淀成一个新 Skill：skill-engineer

如果要把这套整合真正产品化，我建议不要叫 skill-creator，而叫：

skill-engineer

因为它不只是创建，而是覆盖完整工程生命周期。

它的职责是：

Create → Review → Rewrite → Eval → Package

一个合理的目录结构可以是：

skill-engineer/
├── SKILL.md
├── references/
│   ├── skill-design-principles.md
│   ├── skill-review-rubric.md
│   ├── skill-eval-patterns.md
│   └── skill-packaging-guide.md
├── scripts/
│   ├── validate_skill.py
│   └── run_skill_eval.py
└── assets/
    └── skill-template/

这个 Skill 应该有五个工作模式：

模式作用
Create Mode从真实任务创建 Skill
Review Mode评审已有 Skill
Rewrite Mode重构 SKILL.md
Eval Mode生成并运行测试用例
Package Mode准备发布和分发

这样它就不是普通 creator，而是 Skill 工程师。

十、安全维度也必须加入

随着 Skill 变成可安装、可分发的工程资产，安全问题会变得更重要。

近期研究已经开始关注 Agent Skill 的安全风险。

有研究指出，SKILL.md 不是被动文档，而是会影响 skill discovery、selection 和 governance 的操作性文本；攻击者可能通过自然语言触发词操控 skill 可见性、选择倾向和治理判断。

还有研究提出，Agent Skill 的风险不仅来自自然语言，也来自 SKILL.md 与脚本代码之间的跨模态攻击面：表面上看似良性的 Skill 描述，可能配合脚本或资源诱导 Agent 做危险操作。

这意味着未来的 Skill 工程不能只做功能评审，还要做安全评审。

至少要检查：

  • description 是否刻意扩大触发范围
  • 是否诱导 Agent 读取敏感文件
  • scripts 是否执行危险命令
  • references 是否含有注入指令
  • assets 是否包含隐藏 payload
  • Skill 是否请求不必要工具或外部系统访问
  • SKILL.md 描述与实际脚本行为是否一致

所以 skill-engineer 不应该只包含 Creator 和 Reviewer，还应该包含 Security Review。

十一、最终判断：Skill 工程会成为 Agent 产品的基础设施

Codex $skill-creator 代表的是一个方向：

把重复工作流变成可复用 Skill。

Matt 的 writing-great-skills 代表的是另一个方向：

把 Skill 写成可预测、可维护、可评审的流程。

二者结合起来，才真正接近 Agent Skill 工程。

未来成熟的 Agent 产品，不会只拼模型能力，也不会只拼工具数量，而会拼这四层能力：

1. Skill Authoring：如何创建 Skill
2. Skill Review：如何评审 Skill
3. Skill Eval：如何验证 Skill
4. Skill Registry：如何管理和分发 Skill

如果没有这四层，Skill 很容易退化成 Prompt 文件夹：

看起来很多，实际不可控。

看起来可复用，实际每次都要人工兜底。

看起来智能，实际没有稳定流程。

而真正的 Skill 工程，是把人的经验、团队的规范、反复出现的工作流，沉淀为 Agent 可以稳定调用的行为资产。

十二、结论

这篇姊妹篇的核心判断是：

Codex $skill-creator 是 Skill 的生产工具；Matt writing-great-skills 是 Skill 的质量标准；真正缺失的是 Skill Eval 和 Skill Security。

所以，最佳整合不是做一个更长的 SKILL.md，而是做一个完整的 Skill 工程闭环：

真实任务
  ↓
Codex-style Skill Creator
  ↓
Skill 工程包
  ↓
Matt-style Skill Reviewer
  ↓
Skill Rewrite
  ↓
Invocation Eval + Execution Eval
  ↓
Security Review
  ↓
Plugin / Registry / Team Distribution

这也是 Agent Skill 接下来最重要的产品机会：

不是帮用户写更多提示词，而是帮用户把高频工作流变成可验证、可复用、可分发的 Agent 能力模块。

换句话说，Prompt 时代的核心资产是「好指令」。

Agent 时代的核心资产会变成「好 Skill」。

而好 Skill 的标准，不是写得长，而是可预测、可验证、可维护、可安全分发。

参考来源