结论先说
- 技能包的核心优势是「渐进式加载」,不会常驻占满上下文。会话启动时 Codex 只读取每个
SKILL.md头部极短的name与description;只有当前任务匹配(或主动调用)时,才按需载入详细说明、模板与文档。 - 把确定性动作放进
scripts/,把大段规则拆进references/,把样板放进assets/。让模型直接执行经过评审的脚本而非现场拼复杂命令,既降低出错率,也只把脚本输出结果送进上下文,不浪费 Token 读脚本源码。 - 团队共享技能直接提交在仓库的
.agents/skills/<技能名>/下。随 Git 版本管理与 PR 评审流转,新人拉下代码立刻自动拥有团队发版、单测与排错能力;个人通用技能则放在~/.agents/skills/。 description的触发边界写得好不好,决定技能会不会被误触发或漏触发。务必用一两句清楚写明「何时该用」与「不要在什么场景下用」,避免多个相似技能互相抢占。- 在团队仓库持续迭代、调试多个带脚本与参考文档的技能包需要频繁试跑验证。国内无外币卡的用户可在本站开通 ChatGPT Plus 或高配额的 ChatGPT Pro,团队多人协作可了解 ChatGPT Business 团队定制。

图:本站根据 OpenAI Codex 官方文档:Build skills 整理的示意图
本文根据 OpenAI Codex 官方文档《Build skills》《Skills and plugins》及 Agent Skills 开放规范整理,资料核对于 2026-11-19。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 团队里已经写了一份很长的
AGENTS.md,但发现每次启动 Codex 都消耗大量上下文、规则一多反而容易顾此失彼的研发负责人; - 想把内部发版清单、单元测试夹具模板、日志脱敏排错脚本打包成可复用资产,让全员在 Codex 里一键复用的工程师;
- 刚学会安装别人现成技能,准备按标准规范从零编写团队专属
SKILL.md技能包的开发者。
一、标准技能包目录结构与 AGENTS.md 的分工
很多团队会把技能和 AGENTS.md、自定义斜杠提示词混着写(区别可对照 /guides/codex-skills-how-to-use-install 与 /guides/codex-memories-how-to-use-vs-agents-md)。简单原则是:每次对话都要遵守的全局铁律(构建命令、目录约定、代码风格)留给 AGENTS.md(读取机制见 /guides/codex-agents-md-how-it-reads);只在特定任务才触发的流程、脚本与模板全部封装成技能包。
一个标准团队技能包目录如下:
text
.agents/skills/release-check/
├── SKILL.md # 必填:YAML 元数据 + 精简操作步骤
├── scripts/ # 可选:确定性校验或格式化脚本(.py / .sh / .js)
│ └── verify_changelog.py
├── references/ # 可选:长篇检查清单、错误码表、历史故障手册
│ └── rollout-checklist.md
└── assets/ # 可选:输出模板、样板文件、配置文件骨架
└── release-notes.md
四个层级的分工非常明确:
| 目录或文件 | 职责定位 | 上下文开销特点 |
|---|---|---|
SKILL.md | 声明触发条件(Frontmatter)与执行主流程 | 启动仅读头部元数据,命中后载入正文 |
scripts/ | 封装校验、脱敏、版本检查等确定性逻辑 | 模型直接运行脚本,只回收执行结果 |
references/ | 存放长文档、规范细则与错误码索引 | 仅在流程明确指引查阅某文件时按需读取 |
assets/ | 存放标准发版模板、测试脚手架等静态素材 | 供代理复制或按占位符填充生成目标文件 |
二、三套可直接套用的团队技能包范本
本站建议团队优先把最高频、最怕漏步的三类流程做成独立技能,分别放在 .agents/skills/ 下维护:
1. 内部发版校验技能(release-check)
用于发版前自动检查版本号、核对变更日志并按统一模板输出发布说明草稿:
markdown
---
name: release-check
description: 核对即将发布分支的版本号、Changelog 完整性并生成内部发版说明。仅在准备打 Tag、汇总发版变更或检查发版前项时使用;普通日常功能提交不要触发。
---
# 内部发版前检查流程
1. 先运行 `python .agents/skills/release-check/scripts/verify_changelog.py` 检查版本号与未归档条目。
2. 如脚本报告缺失项或存在破坏性变更,查阅 `references/rollout-checklist.md` 核实灰度与回滚要求。
3. 以 `assets/release-notes.md` 为模板生成发布草稿,明确列出涉及数据库迁移的服务名与人工复核清单。
4. 禁止自动执行 `git tag` 或 `git push`,所有命令仅停留在生成本地草稿阶段。
2. 团队单元测试编写技能(unit-test-author)
把公司规定的 Mock 写法、命名规范和夹具骨架抽成模板,避免 AI 每次写出来的单测风格各异:
SKILL.md:规定先跑一遍现有测试基线,新增用例必须覆盖正常路径、空值边界与异常分支,严禁为了跑绿而删改已有业务断言;assets/test-fixture-template.ts:放一份标准的工厂函数与清理钩子样板;references/mock-rules.md:列明哪些外部依赖允许 Mock(如短信、支付网关),哪些核心计算必须走真实逻辑。
3. 线上报错快速排错技能(prod-triage)
用于把线上告警日志做本地脱敏、对照内部错误码表并定位到仓库源码路径:
scripts/redact_logs.py:先过滤手机号、令牌与内网密钥再交由模型分析;references/error-codes.md:维护核心业务错误码与归属模块映射表,减少盲目全仓搜索;SKILL.md:要求先输出「触发路径、直接根因、影响范围、最小止血方案」四段结构化结论,再征求确认是否落盘修复。
订阅与账号准备提示:开发并反复试跑团队多套技能包时,经常需要连续做多轮触发测试与脚本联调。若 Plus 档配额在高频调试期不够用,可在本站升级 ChatGPT Pro 充值 或选用 ChatGPT Pro 5x iOS 可覆盖档;若新注册 OpenAI 账号在手机验证环节受阻,也可查看 Codex 注册手机验证服务。
三、编写高质量团队技能包的六项规范检查

图:本站根据 Agent Skills 开放规范 整理的示意图
为了让技能包在多人协作与长期迭代里一直好用,上线合并前建议按下面六条逐一复核:
name使用简短小写字母加连字符(如release-check),且与所在文件夹名称保持完全一致;description明确写出触发场景与排除场景,防止模型在普通问答时频繁误载入大段流程;SKILL.md正文保持精炼、聚焦操作顺序与红线禁忌,长篇查表类资料全部下沉到references/按需读取;scripts/中的脚本具备幂等性与清晰的退出码,且仅做本地检查或只读转换,高危写操作必须由人工二次确认;- 所有脚本和模板均走常规 Git PR 评审合入,严禁在技能包里写入任何真实密钥、内部账号密码或绕过权限的指令;
- 定期清理废弃技能,并在简单单轮文本复用场景下区分好自定义提示词与技能包的边界(对比见 /guides/codex-custom-prompts-slash-commands-guide)。
常见问题
问:团队技能放在 .agents/skills/ 里提交到 Git 后,成员还需要每人手工安装吗?
答:不需要。仓库级技能放在项目 .agents/skills/<技能名>/ 下并随代码提交后,成员只要拉取最新分支并在该项目目录启动 Codex,客户端就会自动发现这些技能的元数据并按需加载。
问:技能包里的 scripts/ 脚本如果执行失败了,Codex 会怎么做?
答:模型会收到该脚本的标准输出与报错信息,并据此向你汇报失败的具体校验项或退出原因。因此编写脚本时尽量输出清晰、单行定位明确的错误提示(例如指明缺失的字段名或文件路径),能大幅提升排错准确度。
问:国内没有外币信用卡,或者公司需要开增值税发票报销,怎么开通适合全队使用自定义技能包的 Codex 订阅?
答:可通过本站 AI 会员充值总览 办理 ChatGPT Plus 卡密自助兑换 或高配额 ChatGPT Pro,多人研发团队可直接选择 ChatGPT Business 团队定制。支持支付宝、微信支付及 AlipayHK 付款,无需交出账号密码,可开具增值税发票;实时价格以商品页展示为准,售后遵循掉订阅按剩余天数折退、封号不在质保范围的规则。
相关教程
- Codex Skills 技能怎么安装与使用
- Codex 怎么读取 AGENTS.md 与层级优先级
- Codex Memories 记忆功能怎么用?与 AGENTS.md 的区别
- Codex 自定义提示词与斜杠命令配置指南
参考资料
- OpenAI Codex 官方文档:Build skills — https://learn.chatgpt.com/docs/build-skills
- OpenAI Codex 官方文档:Skills and plugins — https://learn.chatgpt.com/docs/skills-and-plugins
- Agent Skills 开放规范:Specification — https://agentskills.io/specification
0 条评论
还没有评论,来抢沙发~