关键词：Codex Skills / Agent Skills / Plugin / MCP / Workflow / AI Coding
适合读者：AI Coding 用户、工程团队、产品经理、Agent 产品构建者、正在沉淀团队工作流的人

一、核心判断

Codex Skills 不是一个普通插件功能。

它真正重要的地方在于：它把“提示词”推进到了“可复用工作流”的阶段。

过去我们使用 AI Coding 工具，很多时候依赖临时 Prompt：

  • 这次让它按某个格式 Review PR；
  • 下次让它按某个流程写 Release Note；
  • 再下次让它根据团队规范做迁移检查；
  • 每次都要重新解释背景、规则、格式、边界和验收标准。

这会带来三个问题：

第一，效率低。同样的工作，每次都要重复说明。

第二，质量不稳定。不同人写 Prompt，结果就不一样；同一个人不同时间写 Prompt，结果也可能不一样。

第三，团队经验无法沉淀。一次成功的 AI 协作，如果没有结构化保存，很快就消失在对话历史里。

Codex Skills 解决的正是这个问题：

把一次有效的人机协作，沉淀成一个 Codex 可以重复调用、持续改进、团队共享的工作单元。

所以，Codex Skills 的本质不是“提示词增强”，而是 Agent 工作方法的产品化封装。

从一次性 Prompt 到可复用 Skill 的转变
Skill 的价值不是把提示词写长，而是把一次有效协作沉淀成可复用工作单元。

二、什么是 Codex Skill？

一句话：

Codex Skill 是一套可以被 Codex 自动或手动调用的可复用工作流。

它通常包含：

  • 任务说明
  • 适用场景
  • 执行步骤
  • 输入输出格式
  • 判断标准
  • 示例
  • 可选脚本
  • 可选参考资料
  • 可选模板资源

最小形态是一个目录：

my-skill/
├── SKILL.md

更完整的形态可以是：

my-skill/
├── SKILL.md          # 必需：元数据 + 工作流说明
├── scripts/          # 可选：脚本、命令、自动化逻辑
├── references/       # 可选：规范、文档、API 说明、团队制度
├── assets/           # 可选：模板、图片、样例文件
└── agents/           # 可选：面向不同 Agent 的配置或展示信息

其中最重要的是 SKILL.md。

SKILL.md 至少包含两个字段：

---
name: code-review
description: Review pull requests for correctness, security, maintainability, test coverage, and release risk. Use when reviewing code changes, PRs, diffs, or proposed patches.
---

# Code Review Skill

## When to use

Use this skill when the user asks for code review, PR review, patch review, release risk analysis, or security-sensitive review.

## Process

1. Understand the intent of the change.
2. Inspect the changed files and related call sites.
3. Check correctness, edge cases, security, maintainability, and backward compatibility.
4. Verify whether tests exist or should be added.
5. Produce a review with required changes and suggested improvements.

## Output format

### Summary
### Blocking Issues
### Non-blocking Suggestions
### Test Recommendations
### Release Risk

这里最关键的不是 Markdown 格式，而是两个问题：

  1. 这个 Skill 什么时候应该被调用？
  2. 它被调用后，Codex 应该如何稳定完成任务？
Codex Skill 目录结构示意
一个 Skill 不是一段孤立提示词，而是说明书、参考资料、脚本和样例的能力包。

三、为什么不是继续写长 Prompt？

因为长 Prompt 适合一次性任务，Skill 适合重复性任务。

一个判断标准：

如果你发现自己反复复制同一段 Prompt，或者反复纠正 Codex 同一个工作流，那么它就应该被沉淀成 Skill。

例如：

  • 每周都要写项目周报；
  • 每次 PR Review 都有固定检查项；
  • 每次发版前都有固定验收流程；
  • 每次处理线上问题都要按固定 Runbook；
  • 每次写日报、研报、客户简报都有固定结构；
  • 每次做代码迁移都有团队约束和风险边界。

这些都不应该长期停留在 Prompt 层。

Prompt 是一次性的表达。
Skill 是可复用的能力。
Plugin 是可分发的产品。
MCP 是连接外部工具和上下文的协议。

这几个概念可以这样理解：

类型解决的问题典型场景
Prompt临时指令让 Codex 完成一次任务
Skill固定流程让 Codex 按团队方法重复完成一类任务
Plugin分发能力把多个 Skills、MCP、应用集成打包给团队
MCP连接外部系统让 Codex 访问 GitHub、Slack、Notion、数据库、内部系统等

最简单的判断是：

  • 要它按流程做事，用 Skill。
  • 要它连接外部工具，用 MCP。
  • 要把能力打包分发，用 Plugin。
  • 只是一次临时任务，用 Prompt。
Prompt、Skill、Plugin、MCP 的关系
Prompt 解决一次表达，Skill 解决重复流程，Plugin 解决分发，MCP 解决连接。

四、Codex Skill 的真正价值

1. 把个人经验变成团队资产

一个资深工程师知道怎么 Review PR。
一个产品负责人知道怎么写需求评审。
一个运维负责人知道怎么排查线上事故。
一个内容负责人知道怎么写日报、周报和研报。

过去这些经验通常存在于人的脑子里，或者散落在文档、Slack、PR 评论、Notion、邮件和历史对话中。

Skill 的价值是：把这些经验变成 Codex 可以执行的工作单元。

这意味着团队经验可以被：

  • 复用
  • 迭代
  • 共享
  • 版本化
  • 审查
  • 自动化

这比“写一个更好的 Prompt”重要得多。

2. 把 AI Coding 从聊天模式推向工作流模式

AI Coding 的早期范式是聊天：

我问一句，AI 答一句。
我让它改一段，它改一段。
它错了，我再纠正。

但真正的工程工作不是聊天。

工程工作是流程：

  • 理解上下文
  • 明确目标
  • 找到相关文件
  • 提出方案
  • 修改代码
  • 运行测试
  • 处理失败
  • 复盘风险
  • 输出结果

Skill 的作用，就是把这种流程显式化。

它让 Codex 不只是“回答问题”，而是按照一套稳定方法完成工作。

3. 让 Agent 具备“组织记忆”

一个团队真正需要的不是“每个人都会写 Prompt”，而是：

团队最好的工作方法，能不能被 Agent 记住、调用、执行和改进？

Codex Skills 正在把这个问题变得具体。

它不是一个知识库，也不是一个单纯文档库。

它更像是面向 Agent 的组织操作系统：

  • 这里是我们的代码 Review 标准；
  • 这里是我们的发版流程；
  • 这里是我们的事故复盘模板；
  • 这里是我们的内容生产格式；
  • 这里是我们的客户简报结构；
  • 这里是我们的测试命令和验证标准。

未来团队的差异，不只在于谁用的模型更强，也在于谁把自己的工作方法沉淀得更好。

五、什么工作适合做成 Skill？

不是所有任务都适合做成 Skill。

一个好的 Skill，通常满足四个条件：

1. 高频

这个任务会重复发生。

例如：

  • PR Review
  • Release Note
  • Bug Triage
  • 周报生成
  • 日报生成
  • 代码迁移检查
  • 线上事故复盘
  • 客户会议纪要整理

如果一年只做一次，没必要做 Skill。

2. 有稳定流程

任务不是完全开放式创作，而是有相对稳定的步骤、格式和判断标准。

例如：

  • 发版前必须跑哪些检查；
  • 代码 Review 必须看哪些风险；
  • 周报必须包含哪些模块；
  • 事故复盘必须回答哪些问题；
  • 数据分析必须输出哪些图表和结论。

3. 有团队偏好

同样的任务，不同团队做法不同。

例如，十个团队都写周报，但结构可能完全不一样。十个团队都 Review PR，但关注重点可能不同。十个团队都写 Release Note，但面向用户、面向内部、面向销售的写法不一样。

只要存在“我们团队就是这样做”的差异，就适合沉淀成 Skill。

4. 可验证

Skill 最好有明确的验收标准。

例如：

  • 测试是否通过；
  • 输出是否符合模板；
  • 是否覆盖风险项；
  • 是否检查 backward compatibility；
  • 是否列出 blocking issue；
  • 是否给出下一步行动；
  • 是否符合团队语气和发布标准。

没有验收标准的 Skill，容易退化成一段模糊 Prompt。

判断任务是否适合做成 Skill 的四个条件
高频、稳定流程、团队偏好、可验证，是一个任务值得 Skill 化的四个条件。

六、不适合做成 Skill 的场景

以下场景不适合一开始就做 Skill：

1. 还没有跑通的流程

如果你自己也不知道怎么做，不要急着写 Skill。先用 Codex 完成几次真实任务，找到稳定步骤，再沉淀。

2. 过于宽泛的任务

例如：

help-me-code

这个太宽了。

更好的方式是拆成：

pr-review
release-note
bug-triage
migration-plan
incident-summary

Skill 应该像函数一样，有清晰职责边界。

3. 只是知识，不是流程

如果只是放一堆资料，不叫好 Skill。

Skill 不是知识仓库，而是“如何使用知识完成任务”的工作流。

4. 变化太快的外部数据

如果任务依赖实时数据，例如最新客户状态、线上日志、数据库、Slack、GitHub Issue，最好结合 MCP 或 Plugin，而不是把数据硬塞进 Skill。

Skill 负责方法。
MCP 负责连接。
Plugin 负责分发。

七、如何设计一个高质量 Skill？

可以用一个简单框架：

触发词 → 输入 → 流程 → 工具 → 输出 → 验收 → 迭代

1. 写清楚触发场景

description 不是普通简介，而是触发器。

差的写法：

description: Helps with code review.

好的写法：

description: Review pull requests, diffs, and proposed code changes for correctness, security, maintainability, test coverage, backward compatibility, and release risk. Use when the user asks for PR review, code review, patch review, or risk analysis.

为什么？

因为 Codex 会根据 name 和 description 判断什么时候加载这个 Skill。description 写得越清楚，越容易被正确调用。

2. 明确输入

一个 Skill 应该告诉 Codex：开始前需要什么信息。

例如 PR Review Skill 需要：

  • PR 链接或 diff；
  • 相关文件路径；
  • 业务背景；
  • 关注重点；
  • 测试命令；
  • 兼容性要求；
  • 发布风险边界。

如果输入缺失，要么让 Codex 自行查找，要么让它提出最少必要问题。

3. 明确流程

不要只写原则，要写流程。

差的写法：

Review the PR carefully.

好的写法：

1. Identify the intent of the change.
2. Read changed files and nearby call sites.
3. Check correctness and edge cases.
4. Check security-sensitive paths.
5. Check tests and backward compatibility.
6. Run or recommend verification.
7. Output blocking issues before suggestions.

Agent 更适合执行具体流程，而不是理解抽象口号。

4. 明确输出格式

输出格式越稳定，Skill 越有价值。

例如：

## Summary

## Blocking Issues

## Non-blocking Suggestions

## Test Recommendations

## Release Risk

## Final Verdict

这会让结果更适合团队协作，而不是变成一段自由发挥的回答。

5. 明确验收标准

每个 Skill 都应该回答一个问题：

什么情况下，这次执行算完成？

例如：

  • PR Review：指出 blocking issue，给出是否可合并判断；
  • Release Note：按用户视角写清楚新增、修复、破坏性变更；
  • Incident Summary：说明影响范围、根因、处理过程、后续行动；
  • Weekly Report：输出本周变化、关键风险、下周重点；
  • Migration Plan：列出迁移步骤、风险、回滚方案和验证命令。

没有验收标准，就没有稳定质量。

八、一个通用 Skill 模板

可以从这个模板开始：

---
name: your-skill-name
description: Describe what this skill does and when to use it. Include realistic trigger phrases users may say.
---

# Your Skill Name

## Purpose

Explain the outcome this skill should produce.

## When to use

Use this skill when:
- ...
- ...
- ...

Do not use this skill when:
- ...
- ...
- ...

## Required inputs

Before starting, identify:
- Goal:
- Source material:
- Constraints:
- Output format:
- Verification method:

If required inputs are missing, proceed with reasonable assumptions when safe. Ask only for information that is necessary to avoid a wrong result.

## Workflow

1. Understand the user's goal.
2. Inspect the provided context or relevant files.
3. Apply the domain-specific process.
4. Use scripts or references only when needed.
5. Produce the final output in the required format.
6. Verify the result against the checklist.

## Output format

Use this format:

### Summary

### Findings

### Risks

### Recommended Actions

### Verification

## Quality bar

The result is acceptable only if:
- It addresses the stated goal.
- It follows the required output format.
- It distinguishes facts, assumptions, and recommendations.
- It identifies risks or missing information.
- It gives concrete next actions.

## Examples

### Example input

...

### Example output

...

九、一个工程团队最应该先做的 7 个 Skills

如果你是一个工程团队，不建议一开始做很多 Skill。

先做 7 个最有复用价值的：

1. PR Review Skill

目标：统一代码审查标准。适合：每个 PR 都按同一套标准检查正确性、安全、兼容性、测试和发布风险。

2. Bug Triage Skill

目标：把 Bug 从“现象”变成“可复现、可定位、可验证”的任务。适合：用户反馈、线上异常、测试失败、日志报错。

3. Release Note Skill

目标：把技术变更转成可发布说明。适合：周版本、月版本、用户更新、内部发布。

4. Migration Plan Skill

目标：降低重构和迁移风险。适合：数据库迁移、框架升级、API 改造、目录结构调整。

5. Incident Summary Skill

目标：统一事故复盘口径。适合：线上故障、性能问题、三方服务异常、发布回滚。

6. Test Plan Skill

目标：把需求、PR 或 Bug 转成测试计划。适合：新增功能、关键路径、回归测试、边界条件。

7. Weekly Engineering Report Skill

目标：把代码、PR、Issue、事故和计划转成管理层可读的周报。适合：团队周报、项目同步、研发管理。

这 7 个 Skill 覆盖了工程团队最常见的闭环：

需求 → 开发 → Review → 测试 → 发布 → 事故 → 复盘 → 周报

工程团队最值得先沉淀的 7 个 Skills
工程团队可以先从 Review、Triage、Release、Migration、Incident、Test、Report 这 7 类高频工作开始。

十、Codex Skills 的落地方法

不要从“写一个完美 Skill”开始。

正确路径是：

第一步：先跑通一次真实任务

选择一个高频任务，例如 PR Review。

不要马上写 Skill。先让 Codex 完成一次真实 Review。

记录：

  • 哪些输入有效；
  • 哪些步骤必要；
  • 哪些输出有价值；
  • 哪些地方需要反复纠正；
  • 哪些规则是团队特有的；
  • 哪些命令必须稳定执行。

第二步：把成功过程整理成 SKILL.md

把这次成功经验写进 Skill：

  • 任务目标；
  • 适用场景；
  • 输入要求；
  • 执行步骤；
  • 输出格式；
  • 质量标准；
  • 示例；
  • 常见错误。

第一版不用完美，能用就行。

第三步：在真实任务里反复调用

下一次遇到相同任务，直接调用：

$pr-review Review this PR for correctness, security, test coverage, and release risk.

观察 Codex 是否：

  • 触发正确；
  • 流程正确；
  • 输出稳定；
  • 漏掉关键步骤；
  • 执行了错误命令；
  • 需要补充团队规范。

第四步：把纠正写回 Skill

Skill 不应该一次写完。

它应该像代码一样持续迭代。

每次发现问题，就更新：

  • description；
  • workflow；
  • output format；
  • references；
  • scripts；
  • examples；
  • quality bar。

这就是 Agent 工作流的版本化。

第五步：从个人 Skill 变成团队 Skill

个人 Skill 成熟后，可以放到仓库里，成为团队共享能力。

团队 Skill 的价值不只是节省时间，而是统一标准。

一个新人加入团队，不需要先问十个人“我们 PR Review 怎么做”。他可以直接使用团队沉淀好的 Skill。

第六步：成熟后再考虑 Plugin

当一个 Skill 已经稳定，并且需要跨团队分发、和 MCP / App 集成、包含多个 Skills 或安装元数据时，再打包成 Plugin。

不要一开始就做 Plugin。

正确顺序是：

Prompt → Thread → Skill → Team Skill → Plugin → Automation

这是从临时协作到组织能力的演进路径。

从真实任务到团队 Skill 的落地路径
Skill 不是一次写完，而是在真实任务里跑、改、复用、再沉淀。

十一、写 Skill 的 10 条原则

1. 一个 Skill 只做一类工作

不要把 PR Review、Release Note、Bug Triage 混在一个 Skill 里。

2. description 要像触发器，不是广告语

它要告诉 Codex：什么时候该用，什么时候不该用。

3. 少写理念，多写流程

Agent 不缺泛泛原则，缺的是稳定操作路径。

4. 输出格式必须固定

没有固定输出，团队就无法复用。

5. 验收标准必须明确

没有 Done Definition，就没有质量闭环。

6. 复杂资料放到 references

SKILL.md 只放核心流程。详细文档、规范、API、模板放到 references/。

7. 脚本只在能提升可靠性时加入

不要为了显得高级而加脚本。只有当脚本能减少不确定性、提升验证能力时才加。

8. 先本地迭代，再团队共享

第一版先自己用。稳定后再提交到团队仓库。

9. 每次纠正都是一次 Skill 更新机会

不要只在对话里纠正 Codex。要把纠正沉淀回 Skill。

10. Skill 是工作方法，不是知识堆砌

写 Skill 的目标不是“告诉 Codex 更多信息”，而是“让 Codex 更稳定地完成一类任务”。

十二、一个最小可用 PR Review Skill 示例

---
name: pr-review
description: Review pull requests, diffs, and code changes for correctness, security, maintainability, test coverage, backward compatibility, and release risk. Use when the user asks for PR review, code review, patch review, merge readiness, or release risk analysis.
---

# PR Review Skill

## Purpose

Produce a practical engineering review that helps the team decide whether a PR is safe to merge.

## When to use

Use this skill when reviewing:
- GitHub pull requests
- Local diffs
- Proposed patches
- Refactors
- Bug fixes
- Feature branches

Do not use this skill for:
- General architecture brainstorming
- Product requirement review
- Non-code writing tasks

## Required inputs

Identify:
- PR or diff source
- Intended behavior
- Changed files
- Test command, if available
- Known constraints
- Release sensitivity

If information is missing, inspect the repository when possible and state assumptions clearly.

## Workflow

1. Understand the intent of the change.
2. Read the changed files.
3. Inspect nearby call sites and dependent modules.
4. Check correctness and edge cases.
5. Check security-sensitive paths.
6. Check backward compatibility.
7. Check whether tests exist or need to be added.
8. Identify release risks.
9. Separate blocking issues from suggestions.
10. Give a final merge recommendation.

## Output format

### Summary

Briefly explain what the PR changes.

### Blocking Issues

List issues that should block merge. Include file path and reason.

### Non-blocking Suggestions

List improvements that are useful but not required.

### Test Recommendations

Explain what tests should be run or added.

### Release Risk

Low / Medium / High, with reason.

### Final Verdict

Choose one:
- Ready to merge
- Ready after minor changes
- Do not merge yet

这个 Skill 不复杂，但已经具备了几个关键特征：

  • 触发明确；
  • 输入明确；
  • 流程明确；
  • 输出明确；
  • 验收明确；
  • 适合持续迭代。

十三、Codex Skills 对 AI Native Builder 的启发

Codex Skills 背后的信号，比功能本身更重要。

它说明 AI Coding 正在从三个阶段演进：

阶段一：Prompt 驱动

用户告诉 AI 做什么。能力主要取决于用户会不会写 Prompt。

阶段二：Workflow 驱动

用户把稳定流程交给 AI。能力开始取决于工作流是否清晰。

阶段三：Organization Memory 驱动

团队把自己的方法、标准、工具、上下文和判断逻辑沉淀下来。能力开始取决于组织是否能把经验变成 Agent 可执行资产。

这也是未来 AI Native 团队的重要分水岭。

普通团队会问：

怎么写一个更好的 Prompt？

更成熟的团队会问：

哪些工作流应该沉淀成 Skill？
哪些 Skill 应该变成团队标准？
哪些 Skill 应该打包成 Plugin？
哪些 Skill 可以和 MCP、Automation 组合成长期运行的 Agent 系统？

这才是 Codex Skills 真正打开的方向。

从 Prompt 到组织记忆的三个阶段
Skills 的终点不是提示词库，而是团队可调用、可审查、可迭代的组织记忆。

十四、结论

Codex Skills 的入门，不应该停留在“如何创建一个文件夹”。

真正的入门，是理解它背后的工作方式变化：

Prompt 是表达意图。
Skill 是沉淀方法。
Plugin 是分发能力。
MCP 是连接上下文。
Automation 是让稳定流程持续运行。

所以，Codex Skills 最适合做的事情，不是让 AI “多知道一点”，而是让 AI “按你的方法稳定工作”。

对个人来说，它是把经验复用起来。
对团队来说，它是把标准沉淀下来。
对产品来说，它是把工作流封装成可分发能力。
对 AI Native Builder 来说，它是从“会用 AI”走向“会设计 Agent 工作系统”的关键一步。

未来真正有价值的，不是每个人都保存一堆 Prompt。

而是每个团队都有一套自己的 Skills：

  • 会 Review；
  • 会发布；
  • 会复盘；
  • 会写报告；
  • 会做迁移；
  • 会查事故；
  • 会按团队标准完成工作。

这就是 Codex Skills 值得学习的原因。

它不是一个小功能。

它是 Agent 时代的工作方法封装层。

参考链接

OpenAI Developers：Agent Skills – Codex

OpenAI Developers：Save workflows as skills

OpenAI Developers：Best practices – Codex

OpenAI Developers：Workflows – Codex

OpenAI Developers：Glossary – Codex

OpenAI Academy：Plugins and skills

OpenAI Developers：Plugins – Codex

OpenAI Developers：Build plugins – Codex

GitHub：openai/plugins

Agent Skills Open Standard：Specification

GitHub：agentskills/agentskills

OpenAI API Docs：Skills