文章总结： 本文系统介绍如何将提示词经验沉淀为可复用的Codex工作流技能。核心内容包括技能设计原则（可重复性、有界性、可测试性）、技能结构（SKILL.md蓝图、渐进式披露）、工作流设计方法及部署策略。文档提供了详细的技能构建模式、决策矩阵和实际案例，指导用户从本地迭代到团队分发的完整流程。 综合评分： 78 文章分类： 安全开发,技术标准,安全工具,安全运营,其他

---

Codex Skills 指南：如何把提示词经验沉淀为可复用工作流

原创

JavaEdge JavaEdge

JavaEdge

2026年6月11日 23:11 上海

在小说阅读器读本章

去阅读

点击下方“JavaEdge”，选择“设为星标”

第一时间关注技术干货！

本文已收录在Github，关注我，紧跟本系列专栏文章，咱们下篇再续！

• 🚀 魔都架构师 | 全网30W技术追随者
• 🔧 大厂分布式系统/数据中台实战专家
• 🏆 主导交易系统百万级流量调优 & 车联网平台架构
• 🧠 AIGC应用开发先行者 | 区块链落地实践者
• 🌍 以技术驱动创新，我们的征途是改变世界！
• 👉 实战干货：编程严选网

将客户知识转化为可重复使用的 Codex 工作流。

---

第一章 指导原则

在编写文件之前，先确定工作方向。

核心理念

skill不是最终结果，采用的工作流才是结果。

当 Codex skill能够将重复的人工提示转化为一致的、可测试的流程时，它才是有用的。工作始于识别真实的工作流、其所有者、源系统、审批流程和完成定义。

1. 可重复性

• 工作流发生的频率足够高，使得可重用的指令变得重要。

2. 有界性

• 预期的输入、输出和审查标准是已知的。

3. 可测试性

• 工作流可以通过提示、输出、追踪或脚本进行检查。

---

执行摘要

Codex skills打包可重复的专业知识。

Codex skill是可重用的工作流指令。一个skill将 SKILL.md 文件与可选的脚本、参考资料和资源打包在一起，使 Codex 能够遵循流程，而无需用户每次重新解释。

当团队有标准方法时使用skill。示例包括客户简报、发布审查、实施计划、报告生成、仓库清单和工具连接的操作工作流。

| 概念 | 说明 | | — | — | | skill | 教授流程：步骤、参考资料、脚本、验证、输出格式。 | | 插件 | 打包和分发skill、应用映射、MCP 配置、钩子和元数据。 | | 治理 | 使用文档化的控制进行审批、沙箱、托管配置和审查。 |

---

核心心智模型

能力栈

使用此模型来决定需求所属的位置。将工作流指令、工具访问、包分发和策略控制分开。

| 概念 | 用途 | | — | — | | MCP 或应用 | Codex 可以访问什么。 | | skill | Codex 应该如何使用这些访问权限。 | | 插件 | 能力如何打包和分发。 | | 托管控制 | 审批、访问和约束的策略边界。 |

---

决策矩阵

选择适合发布范围的最小表面。

| 情况 | 推荐的表面 | 原因 | | — | — | — | | 一个人在实验 | USER SKILL | 快速迭代，无打包开销。 | | 工作流属于项目 | REPO SKILL | 保持流程指导贴近工作。 | | 工作流应该共享或捆绑 | PLUGIN | 可安装单元，用于skill、应用集成、MCP 配置和元数据。 | | 托管产品或代理需要skill捆绑包 | API SKILL | API 环境的版本化skill附件。 | | 仓库需要基准指令 | AGENTS.MD | 持久的项目指导和工作协议。 | | 企业需要策略约束 | MANAGED CONFIG | 支持审批、沙箱、功能和相关需求的控制。 |

不要过早过度打包。从本地或仓库skill开始。当工作流稳定、可重用且需要分发或捆绑集成时，再打包为插件。

---

第二章 skill结构

围绕渐进式披露构建skill。

skill构建原则

保持触发器简洁，工作流清晰，参考资料可选。

Codex 最初只看到skill名称、描述和路径。它只在选择使用skill时才读取完整指令。因此，描述是第一道质量门。

skill剖析

一个 Codex skill是一个包含一个必需文件的文件夹。

customer-brief/
├── SKILL.md          # 必需
├── scripts/
│   └── validate_brief.py
├── references/
│   ├── source-map.md
│   └── brief-rubric.md
├── assets/
│   └── brief-template.md
└── agents/
    └── openai.yaml

SKILL.md – 必需的前置元数据和 Markdown 指令。

scripts/ – 确定性检查、转换、渲染器或辅助命令。

references/ – 仅在需要时加载的详细文档：模式、评分标准、API 说明、策略。

assets/ 和 agents/openai.yaml – 模板、图像、UI 元数据、调用策略和工具依赖。

SKILL.MD 蓝图

必需文件应简洁且具有操作性。

---
name: customer-brief
description: 根据批准的源材料准备客户账户简报。当用户要求账户简报、客户摘要、利益相关者准备、续约准备或会议简报时使用。
---

# Customer Brief

## Workflow
1. 确定客户、会议目的和可用的源材料。
2. 在起草前阅读批准的来源。
3. 区分事实、决策、风险和未解决的问题。
4. 使用必需的结构生成简报。
5. 在回复前运行最终清单。

好的skill主体做四件事：

• 定义工作流适用的情况
• 描述必需的输入和输出
• 给出有序的工作流
• 命名验证和故障处理规则

将细节放在主体之外。将长源映射、评分标准、样式指导、模式和示例移到 references/ 中，并从工作流中链接到它们。

---

渐进式披露

描述是触发表面。

设计含义：Codex 文档描述了初始skill列表预算。如果安装了许多skill，描述可能会缩短或从初始列表中省略。将用例和触发词放在前面。

1. 名称 – 简短、稳定且具体，足以识别。
2. 描述 – 结果、触发短语和边界。
3. SKILL.md – 当 Codex 选择skill时加载。
4. 参考资料 – 仅在对任务有用时加载。
5. 脚本 – 当确定性行为很重要时执行或检查。

---

描述模式

像路由规则一样编写描述。

可重用模式： [结果]。当用户要求 [特定触发短语、工件、工作流或文件类型] 时使用。不要用于 [附近但无关的任务]。

强描述： 为软件项目准备实施就绪审查。当用户要求启动就绪、发布审查、部署清单、发布风险或 go/no-go 准备时使用。不要用于一般代码审查。

为什么有效：结果、触发短语和边界都很明确。

弱描述： 帮助处理项目工作。

为什么失败：没有结果、没有触发语言、没有范围边界。

---

指令主体

大多数skill使用一种格式。

# skill名称

## 何时使用
使用此skill当...

## 输入
必需：
- ...

可选：
- ...

## 工作流
1. ...
2. ...
3. ...

## 质量检查
- ...

## 输出格式
返回...

## 失败模式
- 如果...，则...

从要完成的工作开始。使用命令式步骤。定义输入和输出。将关键检查放在顶部。

---

第三章 工作流设计

在打包之前设计客户工作流。

工作流优先设计

先确定操作流程，然后选择 Codex 表面。

一个好的skill候选具有明确的所有者、源系统、预期输出、审批点和成功指标。没有这些，打包只会隐藏歧义。

工作流收集

在编写skill之前使用此模板。

• 工作流名称：
• 业务结果：
• 主要用户：
• 当前触发器：
• 当前输入：
• 源系统：
• Codex 应该采取的行动：
• 需要人工批准的行动：
• 预期输出：
• 完成定义：
• 质量检查：
• 失败模式：
• 采用指标：
• 所有者：
• 审查节奏：

好的候选：

• 反复发生
• 使用稳定的来源
• 具有标准输出格式
• 可以用提示测试
• 节省时间或减少返工

差的候选：

• 需要未定义的判断
• 依赖无法访问的系统
• 每次都发生根本性变化
• 没有所有者
• 需要高影响行动但没有审批

---

用例模式

当工作重复时，提示变成skill。

| 工作模式 | skill应捕获的内容 | | — | — | | 简报和摘要 | 源系统、摘要部分、事实/推理分离、过期上下文处理和更新节奏。 | | 演示文稿、报告和备忘录 | 受众、工件结构、来源引用规则、缺失数据行为以及渲染或审查检查。 | | 数据清理和整合 | 字段映射、去重键、验证规则、审查选项卡、假设和变更日志要求。 | | 优先级排序和审查 | 排名标准、证据要求、必填字段、升级规则和所有者审查点。 | | 工作流审计 | 当前步骤、卡住点、重复问题、自动化候选和流程文档输出格式。 |

skill阈值： 当相同的工作流将重复发生、来源和输出格式稳定、团队需要护栏或测试以使结果可重复时，将提示转换为skill。

---

调用与发现

使入口点明确。

| 方式 | 语法 | 用途 | | — | — | — | | SKILL | $skill 或 /skills | 当用户确切知道哪个skill应该处理任务时使用。 | | IMPLICIT | 描述匹配 | 当请求与skill描述匹配时，Codex 可以选择skill。 | | PLUGIN | @plugin | 用于显式调用插件或其捆绑的skill之一。 |

不要模糊语法。在skill特定部分使用 $skill 示例。在插件部分使用 @plugin 示例。

---

skill位置

Codex 从多个作用域读取skill。

| 作用域 | 位置 | 用途 | | — | — | — | | REPO | $CWD/.agents/skills 和到仓库根目录的父文件夹 | 项目特定的工作流和共享仓库标准。 | | USER | $HOME/.agents/skills | 跨仓库的个人可重用工作流。 | | ADMIN | /etc/codex/skills | 机器或容器级别的默认skill。 | | SYSTEM | 与 Codex 捆绑 | OpenAI 提供的默认skill。 |

skill与 AGENTS.md： 使用 AGENTS.md 进行持久项目指令。使用skill进行可重用任务工作流。当项目指导应该指向工作流特定skill时，两者都使用。

---

第四章 插件与部署

仅在工作流稳定后打包。

插件与部署

插件是分发单元，不是工作流设计的替代品。

当skill应该被安装、共享、在市场中策划或与应用集成、MCP 配置、钩子或元数据捆绑时，构建插件。

插件结构

插件是可安装的捆绑包。

my-plugin/
├── .codex-plugin/
│   └── plugin.json    # 必需
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── .app.json
├── .mcp.json
├── hooks/
│   └── hooks.json
└── assets/

{
  "name": "customer-workflows",
  "version": "0.1.0",
  "description": "Reusable customer workflow skills for Codex.",
  "skills": "./skills/"
}

路径规则： 保持清单路径相对于插件根目录，路径以 ./ 开头，并且只在 .codex-plugin/ 中保留 plugin.json。

---

插件市场

使用文档化的市场模式进行团队发布。

{
  "name": "local-workflows",
"interface": {
    "displayName": "Local Workflows"
  },
"plugins": [
    {
      "name": "customer-workflows",
      "source": {
        "source": "local",
        "path": "./plugins/customer-workflows"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

文档化位置：

• 官方策划的插件目录
• 仓库市场：$REPO_ROOT/.agents/plugins/marketplace.json
• 个人市场：~/.agents/plugins/marketplace.json

安装策略值：AVAILABLE、INSTALLED_BY_DEFAULT 和 NOT_AVAILABLE 在市场示例中有文档记录。

---

发布与版本控制

使用文档化的原语进行受控发布。

文档化原语：

• 插件清单版本
• 已安装插件缓存路径包含市场、插件和版本
• Git 支持的市场条目可以使用 ref 或 sha
• 企业控制包括 Codex 访问、策略、RBAC、托管配置和可观测性

不要暗示：

• 用于自定义插件发布渠道的企业管理控制台
• 每个插件或插件版本的 RBAC
• 托管自定义插件推广工作流
• 官方插件目录的公开自助发布

推荐发布语言： 对于团队发布，使用文档化模式：仓库skill、管理员安装skill、仓库/个人/Git 支持的市场、插件清单版本、Git ref/sha 固定和企业托管配置。

---

部署模式

将发布范围与控制表面匹配。

01 本地迭代在 $HOME/.agents/skills 中创建skill，测试提示，仅在需要时打包。

02 项目共享存储在 .agents/skills 下，从仓库指南引用，并像代码一样审查更改。

03 分发捆绑包打包稳定skill与插件元数据、市场条目和集成设置说明。

04 使其可发现使用文档化的市场模式，必要时用 ref 或 sha 固定 Git 支持的条目。

05 治理访问对支持的策略约束使用托管配置和审批控制。

API skill部署是独立的： 当产品或托管代理需要版本化捆绑包时使用 API skill。将skill说明视为用户提供的工作流输入，而不是更高优先级的策略控制。

---

API SKILLS

适用于代理环境的版本化捆绑包。

API Skills 支持托管和本地 shell 环境、版本指针、默认版本和显式引用。保持此表面与本地 Codex skill发现区分开。

---

第五章 评估

测试工作流，而不仅仅是文件。

评估原则

好的skill通过触发行为、工作流完成度和输出质量来衡量。

测试应显示skill是否在应该触发时触发，避免无关任务，完成工作流，并相对于基线提高一致性、质量或速度。

---

测试策略

在发布前使用四项检查。

01 触发测试

• 明显提示、转述提示、上下文提示和负向控制

02 功能测试

• 源读取成功、工具调用成功、输出结构匹配、处理缺失数据

03 跟踪测试

• 使用 --json 标志进行非交互式运行并检查 JSON 事件

04 质量测试

• 首先应用确定性检查，然后在结构不足时使用评分标准检查

应触发：

• 为明天的续约会议准备客户简报
• 从这些笔记构建利益相关者准备摘要
• 在高管检查前总结账户风险

不应触发：

• 写一封通用感谢信
• 审查这个拉取请求
• 解释什么是客户成功计划

---

评估循环

使回归测试轻量化。

{
  "id": "brief-obvious-001",
  "prompt": "Prepare a customer brief for the Acme renewal meeting using the provided notes.",
  "should_trigger": true,
  "required_checks": [
    "has_risks",
    "has_open_questions",
    "separates_fact_from_inference"
  ]
}

01 定义用例创建带有预期触发行为和必需检查的提示 fixtures。

02 运行 Codex使用非交互模式并捕获换行符分隔的 JSON 事件。

03 评分从确定性检查开始。仅在需要时添加评分标准检查。

---

度量

在编写skill之前定义成功标准。

触发准确性、误报率、工作流完成率、用户更正、生成可用输出的时间和输出评分标准分数是比”skill存在”更好的衡量标准。

---

第六章 治理

将skill作为特权工作流指令进行治理。

治理原则

审查捆绑包、约束操作、明确所有权。

skill可以影响代理读取、写入、运行和生成的内容。在广泛发布之前，它们需要审查、批准边界和运营所有权。

---

安全与治理

在部署前审查skill：

• SKILL.md 说明
• 脚本和命令入口点
• 参考资料和源材料
• 生成输出中使用的资源
• 插件清单
• MCP 和应用配置
• 生命周期钩子
• 审批门和策略检查

不要将skill用作策略控制： 将skill说明视为工作流输入。对安全和治理要求使用明确的产品、平台和企业控制。

优先使用最小权限： 将skill映射到有限的工作流。避免任意不受信任的skill目录。将敏感凭据排除在skill和资源之外。

---

附录

工作坊模板

在实施之前捕获工作流。

会话目标：团队：工作流候选：为什么现在：当前流程：痛点：输入：记录系统：预期输出：决策点：需要人工批准：风险：合规约束：好的结果是什么样的：我们将如何测试：试点用户：发布路径：所有者：

发现提示：

• 用户反复要求 Codex 做什么？
• 哪些输出因用户提示方式不同而有所差异？
• 哪些工作流每次都需要相同的源检查？
• 哪些手动步骤容易忘记？
• 哪些操作需要在 Codex 继续之前获得批准？
• 什么会使这个工作流足够可信以供日常使用？

---

就绪检查清单

在试点skill之前使用。

• 工作流有明确的所有者和审查节奏
• 触发语言、输入和输出已知
• 源系统和批准点已记录
• 成功指标在实施前已定义
• 描述包括结果、触发条件和边界
• SKILL.md 简洁且参考资料链接清晰
• 仅在添加可靠性时包含脚本
• 明显、转述和负向控制提示通过
• 工具或 MCP 设置已验证
• 高影响操作需要批准
• 选择了正确的发布范围
• 反馈循环已到位

---

故障排除

| 症状 | 可能原因 | 修复方案 | | — | — | — | | skill不触发 | 描述模糊、缺少触发短语、请求不匹配范围 | 前置结果、添加实际短语、测试显式调用 | | skill触发过于频繁 | 描述宽泛、与其他skill重叠、无负向边界 | 缩小触发条件、添加”不用于”语言、拆分宽泛skill | | 不遵循说明 | 说明过长、关键检查被掩盖、必需参考不清楚 | 将细节移至参考、将检查放在顶部、将脆弱检查转换为脚本 | | 插件不出现 | 市场路径错误、清单路径无效、需要重启或刷新 | 验证市场 JSON、检查 .codex-plugin/plugin.json、确认源路径 | | 工具或 MCP 调用失败 | 认证不完整、服务器未配置、权限设置阻止执行 | 独立测试工具访问、验证 MCP 配置、记录批准要求 |

---

反模式

避免这些失败模式：

01 过大范围：试图覆盖整个部门的巨型skill变得难以触发、测试和维护。

02 通用描述：”帮助运营”给 Codex 没有可靠的路由信号。

03 隐藏策略声明：仓库指南和skill说明不能替代托管策略控制。

04 过早打包：在工作流测试之前打包为插件会创建没有证据的分发。

05 不安全写入：高影响操作需要明确的批准门和策略检查。

06 夸大发布声明：仅通过目标环境文档化的功能描述自定义插件部署。

编程严选网：http://www.javaedge.cn/

专注分享AI时代下软件开发全场景最新最佳实践~

---

免责声明：

本文所载程序、技术方法仅面向合法合规的安全研究与教学场景，旨在提升网络安全防护能力，具有明确的技术研究属性。

任何单位或个人未经授权，将本文内容用于攻击、破坏等非法用途的，由此引发的全部法律责任、民事赔偿及连带责任，均由行为人独立承担，本站不承担任何连带责任。

本站内容均为技术交流与知识分享目的发布，若存在版权侵权或其他异议，请通过邮件联系处理，具体联系方式可点击页面上方的联系我。

本文转载自：JavaEdge JavaEdge JavaEdge《Codex Skills 指南：如何把提示词经验沉淀为可复用工作流》