OpenAI 官方博客：用技能（Skills）加速開源項目維護
整理版優先睇
OpenAI 用 Skills 系統將開源維護效率提升 44%：AGENTS.md + 本地技能 + CI 自動化
呢篇文章係 OpenAI 官方博客，由開發者關係團隊撰寫。佢地分享咗點樣用 Codex 同埋 Skills 系統嚟維護 OpenAI Agents SDK 嘅 Python 同 TypeScript 倉庫。佢地想解決開源維護入面重複性工程工作嘅效率問題，整體結論係：將工作流編碼成技能（skills），配合 AGENTS.md 強制執行，再將機械性操作交俾腳本，可以明顯加快 PR 處理同發佈流程。
具體嚟講，佢地將 Python 同 TypeScript 兩個倉庫嘅 PR 合併數從 316 升到 457（三個月內），增長約 44%。技能係一包操作知識，包含 SKILL.md、scripts/、references/ 等，採用漸進式披露模型——淨係喺揀中技能嗰陣先載入完整內容。AGENTS.md 係倉庫級別嘅指令，用簡短嘅「如果/則」規則強制觸發技能，例如改動運行時代碼前要先執行 $implementation-strategy。description 字段係路由契約，要寫得具體，例如「Run the mandatory verification stack when changes affect runtime code…」而唔係淨係「Run verification」。
佢地仲明確劃分咗模型同腳本嘅分工——模型負責解讀、對比同判斷，腳本負責確定性重複操作，例如按順序執行驗證命令、收集日誌。自動化集成測試方面，先構建非…
- 結論：透過 Skills 系統（AGENTS.md + 本地技能 + CI），OpenAI Agents SDK 倉庫嘅 PR 合併數三個月內提升咗 44%，從 316 增至 457。
- 方法：採用四層架構：AGENTS.md 策略層 → 技能層 → 腳本層 → CI 層；每個技能都有明確嘅觸發條件、執行契約同輸出格式。
- 差異：模型同腳本嘅分工——模型處理需要上下文嘅解讀、對比同判斷，腳本處理確定性、重複性嘅操作（例如執行驗證命令、收集日誌）。
- 啟發：description 係路由關鍵，要寫具體觸發條件而唔係籠統描述；工作流應該先喺本地穩定再上 CI。
- 可行動點：開源項目維護者可以申請 Codex for Open Source，然後喺倉庫建立 .agents/skills 目錄同 AGENTS.md，將重複性工程工作編碼成技能。
OpenAI Agents SDK - Python
Python 版本 SDK 倉庫，包含完整技能示範
OpenAI Agents SDK - JS
TypeScript/JS 版本 SDK 倉庫
Codex GitHub Action
將技能自動化到 CI 中嘅工具
AGENTS.md 指南
倉庫級別嘅指令文件最佳實踐
結構示例
# AGENTS.md## Project overview- Core SDK code lives under `src/agents/` or `packages/*/src/`.- Tests live under `tests/` or `packages/*/test/`.- Sample apps and integration surfaces live under `examples/`.## Mandatory skill usage- Use `$implementation-strategy` before editing runtime or API changes that may affect compatibility boundaries.- Run `$code-change-verification` when runtime code, tests, examples, or build/test behavior changes.- Use `$openai-knowledge` for OpenAI API or platform work.- Use `$pr-draft-summary` when substantial code work is ready for review.## Build and test commands- Python: `make format`, `make lint`, `make typecheck`, `make tests`- TypeScript: `pnpm i`, `pnpm build`, `pnpm -r build-check`, `pnpm lint`, `pnpm test`## Compatibility rules- Preserve positional compatibility for public constructors and dataclass fields.背景與成果
呢篇文章係 OpenAI 官方博客，分享咗佢地點樣用 Codex 同 Skills 系統嚟維護 OpenAI Agents SDK 嘅兩個倉庫（Python 同 TypeScript）。
佢地想解決開源維護入面重複性工程工作嘅效率問題
結果好亮眼：由 2025 年 12 月到 2026 年 2 月，兩個倉庫一共合併咗 457 個 PR，比起之前三個月嘅 316 個，增長咗約 44%。Python 倉庫由 182 增至 226，TypeScript 倉庫由 134 增至 231。
457 個 PR，比起先前三個月嘅 316 個
四層架構與漸進式披露
呢套系統嘅核心係四層架構：AGENTS.md 策略層 → 技能層 → 腳本層 → CI 層。AGENTS.md 係倉庫級別嘅指令，喺 Codex 開始工作之前就生效。技能層放喺 .agents/skills/ 目錄，每個技能係一小包操作知識。
AGENTS.md 策略層 → 技能層 → 腳本層 → CI 層
技能採用漸進式披露模型：開頭淨係睇到 name 同 description，揀中之後先載入完整嘅 SKILL.md，有需要先讀取參考資料或執行腳本。呢個設計避免一開始就撐大上下文。
漸進式披露模型
- Python 倉庫有 8 個技能，包括 code-change-verification、docs-sync、examples-auto-run 等
- JavaScript 倉庫另外有 3 個專屬技能：changeset-validation、integration-tests、pnpm-upgrade
Python 倉庫有 8 個技能
AGENTS.md 點樣強制技能執行
AGENTS.md 唔單止係倉庫簡介，仲用簡短嘅「如果/則」規則強制 Codex 喺特定情況下調用技能。
每次改運行時代碼之前，先執行 $implementation-strategy
改動 SDK 代碼、測試、示例或構建行為時，執行 $code-change-verification
例如喺 JavaScript 倉庫，當 packages/ 下有變更時，強制執行 $changeset-validation。呢個技能唔只檢查變更集文件存在，仲會對比 git diff 嚟驗證版本升級級別。
AGENTS.md 指南
簡短嘅「如果/則」規則
Description 字段係路由契約，例如 code-change-verification 嘅 description 寫明「Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior」，而唔係淨係話「Run verification」。呢個細節好重要：先修描述，再加代碼。
Description 係路由契約，要寫具體觸發條件
模型同腳本嘅分工
佢地將工作流入面嘅任務分開：模型負責解讀、對比同判斷，腳本負責確定性重複操作。例如喺自動化集成測試，先構建非交互式示例執行基礎，再用模型對比源碼同日誌嚟驗證正確性。
模型負責解讀、對比同判斷，腳本負責確定性重複操作
- 1 腳本負責：按固定順序運行驗證命令、啟動示例並收集日誌、獲取上一個發佈標籤等
- 2 模型負責：閲讀源碼推斷預期行為、將日誌與預期對比、判斷兼容性風險、生成發佈就緒判斷
發佈審查技能從「可以安全發佈」出發，只有當差異中出現具體證據先切換為阻止。每個阻止決定都必需附上解除阻擋清單。
每個阻止決定都必需附上解除阻擋清單
小改快發
整體嚟講，呢套模式令到日常工程工作更明確可靠，小改快發。維護者可以專注喺需要判斷力嘅高位審查，而重複性工作交俾 Codex。
我哋用 Codex 改變咗維護 OpenAI Agents SDK[1] 倉庫嘅方式。倉庫本地嘅技能（skills）、AGENTS.md 文件同埋 GitHub Actions，令我哋將重複出現嘅工程工作——驗證、發佈準備、示例集成測試、PR 審查，變做可重複執行嘅工作流程。就算配置好簡單，都明顯提升咗呢啲活躍倉庫嘅開發效率。2025 年 12 月 1 日至 2026 年 2 月 28 日期間，兩個倉庫總共合併咗 457 個 PR，而之前三個月（2025 年 9 月 1 日至 11 月 30 日）得 316 個（Python：182 → 226，TypeScript：134 → 231）。
簡單介紹嚇背景：個 SDK 提供 Python[2] 同 TypeScript[3] 兩個版本。佢為建立智能體應用提供咗核心組件，亦係喺 Realtime API[4] 之上建立語音智能體嘅簡潔方案，支持多智能體、工具調用同人工審核環節（HITL）。用嘅人唔少：截至 2026 年 3 月 6 日近 30 日內，Python 套件喺 PyPI 嘅下載量大約 1470 萬次，TypeScript 套件喺 npm 嘅下載量大約 150 萬次。
呢套配置好簡單：
• 倉庫策略寫喺 AGENTS.md[5] 裏• 倉庫本地技能放喺 .agents/skills/目錄下• 技能內部可以包含腳本同參考資料 • 當同一個工作流程需要喺 CI 入面運行時，使用 Codex GitHub Action[6]
呢套配置令到 Codex 對倉庫嘅運作方式有穩定嘅上下文，令重複性嘅工程工作更快、更準。
如果你維護緊一個公開嘅開源項目，可以睇嚇 Codex for Open Source[7]。符合條件嘅維護者可以申請帶 Codex 嘅 ChatGPT Pro、API 額度，同埋 Codex Security 嘅有條件訪問權限。
將工作流程留喺倉庫度
喺呢啲倉庫入面，我哋用技能嚟承載倉庫特有嘅工作流程。一個技能就係一小包操作知識：一個 SKILL.md 清單文件，加埋可選嘅 scripts/、references/ 和 assets/ 目錄。Codex 自定義文檔[8]解釋咗點解咁樣效果好：技能好適合承載可重複嘅工作流程，因為佢哋可以攜帶更豐富嘅指令、腳本同參考資料，同時唔會一開始就撐大智能體嘅上下文。
呢個正好符合技能採用嘅漸進式披露（progressive disclosure）模型：
• 首先淨係見到 name和description等元數據• 只有當技能俾揀中時，先加載 SKILL.md嘅完整內容• 淨係需要嗰陣先讀取參考資料或者運行腳本
兩個 SDK 倉庫都將呢啲工作流程放喺代碼旁邊：
• openai-agents-python 嘅 .agents/skills[9] • openai-agents-js 嘅 .agents/skills[10]
Python 倉庫係更簡潔嘅基礎版本：
• code-change-verification——當代碼或者構建行為有變嗰陣，運行必需嘅格式化、lint、類型檢查同測試流程。• docs-sync——對照代碼庫審計文檔，發現缺失、唔正確或者過時嘅文檔。• examples-auto-run——喺自動模式下運行示例，生成日誌同重試輔助文件。• final-release-review——將上一個發佈標籤同當前發佈候選版本做對比，檢查發佈就緒狀態。• implementation-strategy——修改運行時或者 API 變更之前，先確定兼容性邊界同實現方案。• openai-knowledge——透過官方 Docs MCP 工作流程拉最新嘅 OpenAI API 同平台文檔。• pr-draft-summary——交接時準備分支名建議、PR 標題同草稿描述。• test-coverage-improver——運行覆蓋率檢查，揾最大嘅缺口，然後提出高影響力嘅測試建議。
JavaScript 倉庫跟同樣嘅總體模式，然後針對佢嘅 npm monorepo（單倉庫）同發佈流程增加咗幾個倉庫特有嘅技能：
• changeset-validation——檢查變更集同版本升級級別係咪真係匹配套件嘅差異。• integration-tests——將套件發佈到本地 Verdaccio（本地 npm 套件註冊中心）註冊表，並且驗證喺各支持運行時入面嘅安裝同行為。• pnpm-upgrade——協調更新 pnpm 工具鏈同 CI 入面嘅版本鎖定。
比起具體嘅技能列表，更重要嘅係呢個模式本身。每個技能都有職責明確嘅契約、清晰嘅觸發條件同具體嘅輸出。
其中一啲最有用的技能唔係硬性關卡。docs-sync 和 test-coverage-improver 係「先報告再行動」嘅工作流程：佢哋先檢查當前嘅差異或者覆蓋率產物，排出優先級，然後編輯之前徵求批准。喺 Python 倉庫入面，docs-sync 仲將源碼入面嘅 docstring 同註釋作為生成參考文檔嘅權威來源，而唔係手動修補生成嘅輸出。JavaScript 專屬嘅 pnpm-upgrade 技能都係窄範圍維護工作流程嘅好例子：佢將本地 pnpm 版本、packageManager 字段同工作流程入面嘅版本鎖定一齊更新，而唔係退而求其次做全局搜尋取代。
令工作流程變成強制要求
技能要真正發揮作用，就要喺啱嘅時機被強制觸發。呢個就係 AGENTS.md 嘅用武之地。
AGENTS.md 指南[11]將呢類文件定義為倉庫級別嘅指令，隨代碼庫一齊傳遞，喺智能體開始工作之前生效。指南仲建議保持文件精簡。喺 Agents SDK 倉庫入面，我哋用呢個空間嚟放 Codex 每次都應該遵守嘅規則，而且將最重要嘅規則放喺最前面。
實際操作上，兩個倉庫都使用簡短嘅「如果/則」規則嚟強制使用技能。修改運行時或者 API 變更之前，先調用 $implementation-strategy 確定兼容性邊界同實現方案。如果變更影響到 SDK 代碼、測試、示例或者構建行為，調用 $code-change-verification。如果 JavaScript 套件變更影響到發佈元數據，調用 $changeset-validation。如果工作涉及 OpenAI API 或者平台集成，調用 $openai-knowledge。當工作完成同準備交接嗰陣，調用 $pr-draft-summary。
呢個結構亦同 agents.md[5] 嘅建議一致：將項目概述、構建同測試命令、代碼風格、測試指導、安全注意事項同其他倉庫特有規則集中喺一個地方。Agents SDK 倉庫跟咗呢個結構，但係將日常工作入面最重要嘅操作觸發規則放喺最前面。一個精簡版睇起嚟係咁：
# AGENTS.md
## Project overview
- Core SDK code lives under `src/agents/` or `packages/*/src/`.
- Tests live under `tests/` or `packages/*/test/`.
- Sample apps and integration surfaces live under `examples/`.
## Mandatory skill usage
- Use `$implementation-strategy` before editing runtime or API changes that may affect compatibility boundaries.
- Run `$code-change-verification` when runtime code, tests, examples, or build/test behavior changes.
- Use `$openai-knowledge` for OpenAI API or platform work.
- Use `$pr-draft-summary` when substantial code work is ready for review.
## Build and test commands
- Python: `make format`, `make lint`, `make typecheck`, `make tests`
- TypeScript: `pnpm i`, `pnpm build`, `pnpm -r build-check`, `pnpm lint`, `pnpm test`
## Compatibility rules
- Preserve positional compatibility for public constructors and dataclass fields.實際嘅文件會喺呢個基礎上加倉庫特有嘅細節，例如 JavaScript 倉庫入面嘅 $changeset-validation，同埋兩個文件入面更詳細嘅運行時、文檔同發佈指導。如果你想睇完整示例，請參閲 openai-agents-python 嘅 AGENTS.md[12] 同 openai-agents-js 嘅 AGENTS.md[13]。
AGENTS.md 唔止用嚟觸發技能。Python 倉庫仲喺入面記錄咗一條公共 API 兼容性規則：保持導出嘅構造函數參數同 dataclass 字段嘅位置含義唔變，盡量將新嘅可選參數追加喺尾，如果焗住要重新排序就加兼容性測試。呢個都係好做法：將發佈相關嘅兼容性規則同技能觸發規則放喺同一個地方。
驗證規則
一個清晰嘅例子係 $code-change-verification。
喺兩個倉庫入面，規則唔係「每次都行一輪好長嘅驗證流程」，而係「當運行時代碼、測試、示例或者構建/測試行為有變嗰陣先運行，而且喺通過之前唔標記工作完成」。
條件部分令純文檔修改保持輕量。強制部分確保 SDK 代碼變更加過倉庫嘅標準驗證步驟。
實際嘅驗證流程編碼喺技能本身。
喺 Python 倉庫入面，佢要求執行：
make format
make lint
make typecheck
make tests喺 JavaScript 倉庫入面，技能要求按呢個精確順序執行：
pnpm i
pnpm build
pnpm -r build-check
pnpm -r -F "@openai/*" dist:check
pnpm lint
pnpm test技能編碼咗倉庫對「已驗證」嘅定義，而 AGENTS.md 令呢個定義具有強制力。
變更集驗證
JavaScript 倉庫對套件變更加多一個強制步驟：$changeset-validation，基於 Changesets[14] 構建。
當 packages/ 下面有任何變更，或者 .changeset/ 有變嗰陣，模型唔可以齋跑測試就算。佢必須建立或者更新正確嘅變更集，驗證版本升級級別，同確認變更集真係同差異匹配。
呢個技能做嘅唔止係檢查文件存在與否。佢要求 Codex 審查 git diff，而且將驗證規則放喺一個共享嘅 prompt 入面，咁樣本地運行同 GitHub Actions 用嘅係同一套邏輯。佢仲編碼咗倉庫特有嘅策略，例如：
• 當分支上已經有變更集嗰陣，用現有嘅而唔係再開一個 • 摘要保持一行，採用 Conventional Commit（約定式提交）風格，噉樣佢可以兼任提交標題 • 喺 1.0 之前，正常功能開發避免主版本升級，而且將明確標記為預覽嘅新增內容視為補丁級變更（前提係唔改變現有行為） • 根據實際嘅套件變更驗證需要嘅版本升級級別
呢個令到 Codex 喺宣佈工作完成之前，要先負責驗證自己建立嘅發佈元數據。
使用最新文檔
兩個倉庫都要求喺涉及 OpenAI API 或者平台集成嘅工作入面使用 $openai-knowledge。
呢個技能係對官方 OpenAI Docs MCP[15] 嘅輕量封裝。佢唔俾模型靠記憶答，而係叫 Codex 用 OpenAI 開發者文檔嘅 MCP 伺服器去揾 Responses API、工具、流式傳輸、Realtime 同 MCP 等接口嘅最新文檔。
如果 MCP 伺服器未喺本地 Codex 環境入面配置好，個技能會引導維護者去 Docs MCP 快速入門[16] 同官方 MCP 伺服器端點[17]。
準備 PR 交接
喺實質性工作結束嗰陣，兩個倉庫都用 $pr-draft-summary。
呢個技能淨係任務實際完成或者準備好審查，而且變更涉及有意義嘅代碼、測試、示例、有行為影響嘅文檔或者構建/測試配置嗰陣先觸發。然後佢會自動收集分支名、工作樹狀態、變更文件、diff 統計同最近嘅提交，並輸出：
• 分支名建議 • PR 標題 • PR 描述草稿
輸出格式係刻意固定嘅。一個典型嘅結果係咁樣：
# Pull Request Draft
## Branch name suggestion
git checkout -b fix/tracing-lazy-init-fork-safety
## Title
fix: #2489 lazily initialize tracing globals to avoid import-time fork hazards
## Description
This pull request fixes import-time tracing side effects that could break fork-based process models by moving tracing bootstrap to lazy, first-use initialization.
It updates tracing setup so initialization happens once on first access while preserving the existing public tracing APIs.
It also adds regression tests for import-time behavior, one-time bootstrap, and custom provider handling.
This pull request resolves #2489.一旦你信得過模型可以驗證同總結自己嘅工作，叫佢生成 PR 草稿就係順理成章嘅最後一步。咁樣保持咗交接嘅一致性，亦減少咗編碼工作完成之後重複性嘅書寫工作。
寫好描述字段
技能 SKILL.md 嘅 frontmatter（文件頭元數據）入面嘅 description 字段係路由契約嘅一部分。
呢個係結構性問題，唔係風格問題。Agent Skills 規範[18]把 name 和 description 定為 SKILL.md frontmatter 嘅必填字段，其漸進式披露模型規定呢啲字段喺啟動嗰陣就會為所有技能加載。SKILL.md 嘅完整正文同埋 scripts/、references/ 或 assets/ 淨係技能被實際激活嗰陣先加載。
Codex 技能文檔[19]同自定義文檔[8]從 Codex 嘅角度描述咗一樣嘅行為：Codex 先獲取每個技能嘅元數據用嚟發現，淨係揀中某個技能嗰陣先加載 SKILL.md，淨係需要嗰陣先讀取參考資料或者運行腳本。Skills in OpenAI API cookbook[20] 從託管環境嘅角度同樣明確咁講咗呢點：OpenAI 先讀取每個技能嘅 name、description 同路徑，模型根據呢啲資訊決定幾時讀取完整嘅 SKILL.md。其 SKILL.md frontmatter 章節[21]更直接咁指出：name 和 description 對發現同路由至關重要。
喺 Agents SDK 倉庫入面，呢個意思係 description 係 Codex 讀取技能其餘內容之前嘅主要路由信號之一。
下面是 code-change-verification 嘅一個具體例子。
太籠統：
description: Run the mandatory verification stack in the OpenAI Agents JS monorepo.更好嘅寫法（實際使用嘅描述）：
description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo.短版本已經話咗俾 Codex 技能做啲乜，但冇講到佢幾時適用、邊類變更應該觸發佢、同埋呢啲檢查係咪可選。更具體嘅版本將呢三點都講清楚咗。
同樣嘅模式亦出現喺 pr-draft-summary 上。
太籠統：
description: Create a PR title and draft description for a pull request.更好嘅寫法（實際使用嘅描述）：
description: Create a PR title and draft description after substantive code changes are finished. Trigger when wrapping up a moderate-or-larger change (runtime code, tests, build config, docs with behavior impact) and you need the PR-ready summary block with change summary plus PR draft text.同樣，真正嘅描述就係路由元數據。佢話俾 Codex 知：
• 呢個係一個任務結束時嘅技能 • 佢適用於實質性變更，唔係每次對話 • 輸出係一個可以直接用嚟做 PR 嘅結構化塊，而唔係一段文字摘要
呢啲倉庫嘅經驗係：喺 description 上花時間。如果路由感覺唔可靠，先改描述，再加代碼。
將機械性操作放進腳本
接下來嘅問題係：咩應該留喺模型入面，咩應該下沉到腳本。
一個可靠嘅劃分原則係：
• 解讀、對比同報告留俾模型 • 確定性嘅、重複嘅 shell 操作放進 scripts/
呢個同公開嘅指導一致。Codex 自定義文檔[8]將技能描述為一種方式，令 Codex 得到更豐富嘅指令、腳本同參考資料去執行可重複嘅工作流程，同時唔會一開始就撐大上下文。呢個適合以模型為先嘅架構：畀 Codex 處理依賴上下文嘅部分，淨係需要嗰陣先引入腳本處理確定性嘅部分。Skills in OpenAI API cookbook[22] 亦建議將技能腳本設計成微型 CLI：從命令行運行、輸出確定性嘅 stdout、出錯時顯式報錯，需要嗰陣將輸出寫入已知嘅文件路徑。
喺 Agents SDK 倉庫入面，我哋盡量將模型用喺佢嘅智能真係有價值嘅地方，例如：
• 閲讀源碼嚟推斷預期行為 • 將日誌同預期行為做對比 • 判斷一個發佈差異入面有冇真正嘅兼容性風險 • 生成維護者可以據此行動嘅解釋
腳本就負責呢啲工作周圍嘅機械性操作，例如：
• 按固定順序運行倉庫要求嘅驗證命令 • 啟動示例運行、收集每個示例嘅日誌、為失敗嘅示例生成重試文件 • 喺發佈就緒性審查之前獲取上一個發佈標籤 • 暴露好似 start、stop、status、logs、tail、collect和rerun呢類嘅輔助命令，令同一個工作流程可以方便噉重複運行
如果模型每次都要重新發現同一套 shell 腳本流程，通常意味住呢套流程應該變成一個腳本。如果任務取決於上下文、權衡或者解釋，嗰部分就應該留喺模型度。
自動化集成測試
兩個倉庫入面最有用的工作流程領域之一係自動化集成測試。呢度有兩個相關嘅層次：喺兩個倉庫入面自動驗證倉庫內嘅示例，同埋喺 JavaScript 倉庫入面單獨驗證發佈嘅套件喺用戶實際嘅安裝方式下係咪仍然正常運作。
喺呢套配置之前，驗證示例多數靠手動。你可以運行示例，但最後一公里往往取決於肉眼檢查日誌或者憑經驗判斷輸出係咪正確。對一個示例嚟講仲頂得住，但喺一個不斷增長嘅 SDK 倉庫入面就難以為繼啦。
第一層係 examples-auto-run，但技能係喺運行器之後先出現嘅。要實現示例驗證嘅自動化，我哋首先要喺兩個倉庫入面建立非交互式示例執行嘅底層支持。即係要令示例腳本可以喺自動模式下運行，包括一啲通常要用戶輸入或者審批嘅示例。
呢啲基礎工作包括：
• 自動回答常見嘅交互式提示 • 喺運行器支持嘅範圍內，自動通過人工審核環節（HITL）、MCP、 apply_patch同 shell 操作• 將仍然唔適合自動化嘅示例放喺跳過列表入面，例如需要額外運行時配置嘅 Realtime 或者 Next.js 應用示例 • 為每次示例運行編寫結構化日誌 • 生成重試文件，噉樣失敗嗰陣唔使重新運行所有嘢
基礎就位之後，我哋將佢組織成一個技能，令工作流程變得可複用同容易調用。喺 Python 倉庫入面，examples-auto-run 封裝了 uv run examples/run_examples.py --auto-mode --write-rerun --main-log ... --logs-dir ...。喺 JavaScript 倉庫入面，佢先運行構建檢查，然後喺自動模式下執行 pnpm examples:start-all，帶有逐示例嘅日誌同重試支持。
為咗提高驗證質量，運行器嘅任務係執行示例並將佢哋嘅 stdout 同 stderr 保存到逐示例嘅日誌入面。然後技能叫 Codex 逐一檢查呢啲日誌，同埋同源碼做對比：
• 閲讀示例嘅源碼同註釋 • 推斷預期嘅執行流程 • 打開對應嘅日誌 • 將預期行為同實際嘅 stdout 同 stderr 做比較 • 對每個成功運行嘅示例都噉做，而唔係抽查一個
呢個比起將正確性編碼成固定嘅腳本級斷言更準確同更靈活。成功嘅退出碼有用，但對於調用真實 API、使用工具或者產生結構化輸出嘅示例嚟講係唔夠嘅。通過先記錄實際輸出，再仔細對照源碼檢查，我哋可以根據每個示例嘅真實意圖嚟驗證佢。
喺 JavaScript 倉庫入面，仲有第二層：獨立嘅 integration-tests 技能。呢個工作流程唔止喺倉庫入面運行源碼示例。佢將套件發佈到本地 Verdaccio 註冊中心，然後喺多種環境入面測試安裝同行為，包括 Node.js、Bun、Deno、Cloudflare Workers 同 Vite React 應用。呢個捉嘅係另一類問題：唔係「示例喺倉庫入面行唔行得通」，而係「套件經過發佈、安裝同運行時集成之後，行為係咪仍然正確」。
夾埋嚟睇，就能夠理解點解技能、腳本同模型判斷嘅組合管用。腳本令運行可重複、捕獲證據、覆蓋手動檢查起嚟好麻煩嘅安裝路徑。Codex 就利用呢啲證據，做出比簡單嘅腳本通過/失敗檢查更細緻嘅對比。
增加發布檢查
發佈準備係呢個模式特別適合嘅另一個場景。
兩個倉庫入面嘅發佈審查工作流程從揾上一個發佈標籤開始，同最新嘅 main 分支做 diff，然後要求 Codex 檢查該差異入面嘅：
• 公共 API 同面向用戶嘅 SDK 行為入面嘅向後兼容性問題 • 迴歸問題，包括預期行為嘅細微變化 • 需要遷移說明或者發佈說明更新但係未加嘅變更
根據呢啲發現，技能做出整體嘅發佈就緒性判斷。
一個具體嘅例子係 openai/openai-agents-python#2480[23]，喺呢次發佈審查入面，整體結論係綠燈放行，同時指出咗 Python 3.9 支持嘅移除同佢需要嘅發佈說明跟進：
Release readiness review (excerpt)
Release call:
🟢 GREEN LIGHT TO SHIP. Minor-version bump includes expected breaking change
(Python 3.9 drop) with no concrete regressions found.
Scope summary:
- 38 files changed (+1450/-789); key areas touched: `src/agents/tool.py`,
`src/agents/extensions/`, `src/agents/realtime/`, `tests/`,
`pyproject.toml`, `uv.lock`.
Python 3.9 support removed
- Risk: 🟡 MODERATE. Users pinned to Python 3.9 will be unable to install the
0.9.0 release.
- Evidence: `pyproject.toml` now sets `requires-python = ">=3.10"` and drops
the Python 3.9 classifier; CI skip logic for 3.9 was removed.
- Action: Ensure release notes clearly call out the Python 3.9 drop and that
packaging metadata remains `>=3.10`.技能仲定義咗關卡決策嘅方式。審查從「可以安全發佈」出發，只有當差異入面出現咗真實問題嘅具體證據嗰陣先切換為阻止發佈。每個阻止決定都必須附帶具體嘅解除阻止清單。呢個令輸出更易用：綠燈代表差異入面冇發現阻止發佈嘅問題，紅燈代表有真實問題同明確嘅下一步。
呢個比起泛泛而談嘅「請審查一下今次發佈」有用得多。佢迫使模型基於具體嘅差異進行推理，並用可操作嘅術語解釋結果。如果發佈係安全嘅，就直接話安全。如果唔安全，就指出確實嘅證據同確實嘅後續步驟。
喺 CI 入面運行工作流程
當一個技能喺本地驗證有用之後，Codex GitHub Action[6] 可以輕鬆咁將同一個工作流程自動化到 CI 入面。最好等本地工作流程穩定咗先上 CI，因為手動行先係除錯指令、打磨腳本、發現邊界情況嘅過程。
對於公開倉庫嚟講，觸發器嘅設計同技能本身同樣重要。GitHub Action 安全清單[24]建議限制邊個可以啟動工作流程、優先使用可信事件或者顯式審批、對來自 PR、提交、issue 或者評論嘅 prompt 輸入進行清理、用 drop-sudo 或者非特權用戶保護 OPENAI_API_KEY，同埋將 Codex 作為任務入面嘅最後一步運行。
如果一個工作流程有寫權限而且接受不可信嘅公開輸入，風險通常出喺技能周圍嘅觸發器設計、輸入處理同運行時權限上。
喺 PR 審查入面使用 Codex
技能係呢啲倉庫效率提升嘅一部分。Codex GitHub PR 自動審查[25]係另一部分。
自從 Codex GitHub PR 自動審查上線以嚟，Codex 喺呢啲倉庫嘅大多數代碼變更審查入面都有幫助。我哋當佢係常規審查環節，唔係特殊工具。
對於直接嘅程序錯誤、迴歸同缺失嘅測試，將 Codex 作為必要嘅審查路徑喺實踐入面已經夠可靠。佢能夠始終如一噉重複檢查同樣嘅正確性模式，並消除咗小修復同日常改進嘅一個主要瓶頸。
人工審查依然重要，但係針對另一類變更。
當核心問題唔係「呢段代碼啱唔啱」而係「喺多個合理嘅方案入面我哋應該揀邊個，同埋點樣發佈」嗰陣，人工審查仍然不可或缺。呢個包括：
• API 或者架構變更，存在多個合理嘅設計方案，維護者需要做出明確選擇 • 行為變更，影響產品預期、向後兼容性承諾或者發佈策略 • 命名、遷移同發佈溝通決策，難點在於揀對用戶同貢獻者最清晰嘅方案 • 需要維護者或者團隊之間對齊嘅變更，例如確定範圍、排列優先級，或者決定邊啲內容而家發佈、邊啲之後先講
Codex 喺所有呢啲場景入面仍然可以提供有用嘅貢獻，但佢哋仍然需要人類決策者同直接討論。
AGENTS.md 亦可以編碼呢種分工：倉庫可以話俾 Codex 知喺正確性審查入面咩係重要嘅，Codex 就能夠持續一致咁應用呢啲指導。
呢個都係效率提升嘅重要貢獻者。重複性嘅審查同驗證工作唔再需要為每個低風險變更等審查者時間，而維護者可以專注於需要佢哋判斷力嘅高上下文審查。呢種轉變幫我哋快咗處理積壓嘅 bug 同小規模嘅功能改進。
寫喺最後
喺 OpenAI Agents SDK 倉庫入面，技能喺融入倉庫嘅日常工作配置時效果最好。
AGENTS.md 話俾 Codex 知邊啲工作流程係必需嘅。description 話俾佢知幾時路由到呢啲工作流程。scripts/ 處理確定性嘅部分。模型處理需要上下文嘅部分。而當一個工作流程喺本地穩定之後，Codex GitHub Action[6] 可以將同樣嘅流程帶入 CI。
呢個令呢啲倉庫入面嘅日常工程工作變得更明確、更可靠。小改進嘅發佈都快咗，驗證、發佈審查同 PR 交接都行同一套流程。
參考資源
• OpenAI Agents SDK for Python[2] • OpenAI Agents SDK for JS[3] • Skills in Codex[8] • Custom instructions with AGENTS.md[26] • Codex GitHub Action[6] • Use Codex in GitHub[25] • Skills in OpenAI API cookbook[27] • Agent Skills specification[18] • Skills in OpenAI API: operational best practices[22]
引用連結
[1] OpenAI Agents SDK: https://developers.openai.com/api/docs/guides/agents-sdk[2] Python: https://github.com/openai/openai-agents-python[3] TypeScript: https://github.com/openai/openai-agents-js[4] Realtime API: https://developers.openai.com/api/docs/guides/realtime[5] `AGENTS.md`: https://agents.md/[6] Codex GitHub Action: https://developers.openai.com/codex/github-action[7] Codex for Open Source: https://developers.openai.com/codex/community/codex-for-oss[8] Codex 自定義文檔: https://developers.openai.com/codex/concepts/customization#skills[9] openai-agents-python 中的 .agents/skills: https://github.com/openai/openai-agents-python/tree/main/.agents/skills[10] openai-agents-js 中的 .agents/skills: https://github.com/openai/openai-agents-js/tree/main/.agents/skills[11] AGENTS.md 指南: https://developers.openai.com/codex/guides/agents-md#layer-project-instructions[12] openai-agents-python 的 AGENTS.md: https://github.com/openai/openai-agents-python/blob/main/AGENTS.md[13] openai-agents-js 的 AGENTS.md: https://github.com/openai/openai-agents-js/blob/main/AGENTS.md[14] Changesets: https://github.com/changesets/changesets[15] OpenAI Docs MCP: https://developers.openai.com/resources/docs-mcp[16] Docs MCP 快速入門: https://developers.openai.com/resources/docs-mcp#quickstart[17] 官方 MCP 服務器端點: https://developers.openai.com/mcp[18] Agent Skills 規範: https://agentskills.io/specification[19] Codex 技能文檔: https://developers.openai.com/codex/skills[20] Skills in OpenAI API cookbook: https://developers.openai.com/cookbook/examples/skills_in_api/#what-is-a-skill[21] SKILL.md frontmatter 章節: https://developers.openai.com/cookbook/examples/skills_in_api/#skillmd-frontmatter[22] Skills in OpenAI API cookbook: https://developers.openai.com/cookbook/examples/skills_in_api/#operational-best-practices[23] openai/openai-agents-python#2480: https://github.com/openai/openai-agents-python/pull/2480[24] GitHub Action 安全清單: https://developers.openai.com/codex/github-action#security-checklist[25] Codex GitHub PR 自動審查: https://developers.openai.com/codex/integrations/github[26] Custom instructions with AGENTS.md: https://developers.openai.com/codex/guides/agents-md[27] Skills in OpenAI API cookbook: https://developers.openai.com/cookbook/examples/skills_in_api
我們用 Codex 改變了維護 OpenAI Agents SDK[1] 倉庫的方式。倉庫本地的技能（skills）、AGENTS.md 文件和 GitHub Actions，讓我們把反覆出現的工程工作——驗證、發佈準備、示例集成測試、PR 審查，變成了可重複執行的工作流。即便配置相當簡單，也明顯提升了這些活躍倉庫的開發效率。2025 年 12 月 1 日至 2026 年 2 月 28 日期間，兩個倉庫共合併了 457 個 PR，而此前三個月（2025 年 9 月 1 日至 11 月 30 日）只有 316 個（Python：182 → 226，TypeScript：134 → 231）。
簡單介紹一下背景：該 SDK 提供 Python[2] 和 TypeScript[3] 兩個版本。它為構建智能體應用提供了核心組件，也是在 Realtime API[4] 之上構建語音智能體的簡潔方案，支持多智能體、工具調用和人工審核環節（HITL）。用的人不少：截至 2026 年 3 月 6 日的近 30 天內，Python 包在 PyPI 上的下載量約為 1470 萬次，TypeScript 包在 npm 上的下載量約為 150 萬次。
這套配置很簡單：
• 倉庫策略寫在 AGENTS.md[5] 裏• 倉庫本地技能放在 .agents/skills/目錄下• 技能內部可以包含腳本和參考資料 • 當同一個工作流需要在 CI 中運行時，使用 Codex GitHub Action[6]
這套配置讓 Codex 對倉庫的運作方式有了穩定的上下文，讓重複性的工程工作更快、更準。
如果你維護着一個公開的開源項目，可以看看 Codex for Open Source[7]。符合條件的維護者可以申請帶 Codex 的 ChatGPT Pro、API 額度，以及 Codex Security 的有條件訪問權限。
把工作流留在倉庫裏
在這些倉庫中，我們用技能來承載倉庫特有的工作流。一個技能就是一小包操作知識：一個 SKILL.md 清單文件，加上可選的 scripts/、references/ 和 assets/ 目錄。Codex 自定義文檔[8]解釋了為什麼這樣做效果好：技能很適合用來承載可重複的工作流，因為它們可以攜帶更豐富的指令、腳本和參考資料，同時不會一開始就撐大智能體的上下文。
這正好符合技能採用的漸進式披露（progressive disclosure）模型：
• 首先只看到 name和description等元數據• 只有當技能被選中時，才加載 SKILL.md的完整內容• 只在需要時才讀取參考資料或運行腳本
兩個 SDK 倉庫都把這些工作流放在代碼旁邊：
• openai-agents-python 中的 .agents/skills[9] • openai-agents-js 中的 .agents/skills[10]
Python 倉庫是更簡潔的基礎版本：
• code-change-verification——當代碼或構建行為發生變化時，運行必需的格式化、lint、類型檢查和測試流程。• docs-sync——對照代碼庫審計文檔，發現缺失、不正確或過時的文檔。• examples-auto-run——在自動模式下運行示例，生成日誌和重試輔助文件。• final-release-review——將上一個發佈標籤與當前發佈候選版本進行對比，檢查發佈就緒狀態。• implementation-strategy——在修改運行時或 API 變更之前，先確定兼容性邊界和實現方案。• openai-knowledge——通過官方 Docs MCP 工作流拉取最新的 OpenAI API 和平台文檔。• pr-draft-summary——在交接時準備分支名建議、PR 標題和草稿描述。• test-coverage-improver——運行覆蓋率檢查，找到最大的缺口，並提出高影響力的測試建議。
JavaScript 倉庫遵循同樣的總體模式，然後針對其 npm monorepo（單倉庫）和發佈流程增加了幾個倉庫特有的技能：
• changeset-validation——檢查變更集和版本升級級別是否真正匹配包的差異。• integration-tests——將包發佈到本地 Verdaccio（本地 npm 包註冊中心）註冊表，並驗證在各支持運行時中的安裝和運行行為。• pnpm-upgrade——協調更新 pnpm 工具鏈和 CI 中的版本鎖定。
比起具體的技能列表，更重要的是這個模式本身。每個技能都有職責明確的契約、清晰的觸發條件和具體的輸出。
其中一些最有用的技能並不是硬性關卡。docs-sync 和 test-coverage-improver 是“先報告再行動”的工作流：它們先檢查當前的差異或覆蓋率產物，排出優先級，然後在編輯之前徵求批准。在 Python 倉庫中，docs-sync 還把源碼中的 docstring 和註釋作為生成參考文檔的權威來源，而不是手動修補生成的輸出。JavaScript 專屬的 pnpm-upgrade 技能也是窄範圍維護工作流的好例子：它把本地 pnpm 版本、packageManager 字段和工作流中的版本鎖定一起更新，而不是退而求其次地做全局搜索替換。
讓工作流成為強制要求
技能要真正發揮作用，得在對的時機被強制觸發。這就是 AGENTS.md 的用武之地。
AGENTS.md 指南[11]把這類文件定義為倉庫級別的指令，隨代碼庫一起傳遞，在智能體開始工作之前生效。指南還建議保持文件精簡。在 Agents SDK 倉庫中，我們用這個空間來放 Codex 每次都應遵守的規則，並把最重要的規則放在最前面。
實際操作中，兩個倉庫都使用簡短的“如果/則”規則來強制使用技能。在修改運行時或 API 變更之前，先調用 $implementation-strategy 確定兼容性邊界和實現方案。如果變更影響了 SDK 代碼、測試、示例或構建行為，調用 $code-change-verification。如果 JavaScript 包變更影響了發佈元數據，調用 $changeset-validation。如果工作涉及 OpenAI API 或平台集成，調用 $openai-knowledge。當工作完成並準備交接時，調用 $pr-draft-summary。
這個結構也與 agents.md[5] 的建議一致：把項目概述、構建和測試命令、代碼風格、測試指導、安全注意事項和其他倉庫特有規則集中在一個地方。Agents SDK 倉庫遵循了這個結構，但把日常工作中最重要的操作觸發規則放在最前面。一個精簡版看起來是這樣的：
# AGENTS.md
## Project overview
- Core SDK code lives under `src/agents/` or `packages/*/src/`.
- Tests live under `tests/` or `packages/*/test/`.
- Sample apps and integration surfaces live under `examples/`.
## Mandatory skill usage
- Use `$implementation-strategy` before editing runtime or API changes that may affect compatibility boundaries.
- Run `$code-change-verification` when runtime code, tests, examples, or build/test behavior changes.
- Use `$openai-knowledge` for OpenAI API or platform work.
- Use `$pr-draft-summary` when substantial code work is ready for review.
## Build and test commands
- Python: `make format`, `make lint`, `make typecheck`, `make tests`
- TypeScript: `pnpm i`, `pnpm build`, `pnpm -r build-check`, `pnpm lint`, `pnpm test`
## Compatibility rules
- Preserve positional compatibility for public constructors and dataclass fields.實際的文件會在這個基礎上加入倉庫特有的細節，例如 JavaScript 倉庫中的 $changeset-validation，以及兩個文件中更詳細的運行時、文檔和發佈指導。如果你想看完整示例，請參閲 openai-agents-python 的 AGENTS.md[12] 和 openai-agents-js 的 AGENTS.md[13]。
AGENTS.md 不只是用來觸發技能的。Python 倉庫還在其中記錄了一條公共 API 兼容性規則：保持導出的構造函數參數和 dataclass 字段的位置含義不變，儘量把新的可選參數追加在末尾，如果不得不重新排序則添加兼容性測試。這也是個好做法：把發佈相關的兼容性規則和技能觸發規則放在同一個地方。
驗證規則
一個清晰的例子是 $code-change-verification。
在兩個倉庫中，規則不是“每次都跑一遍長長的驗證流程”，而是“當運行時代碼、測試、示例或構建/測試行為發生變化時才運行，並且在通過之前不標記工作完成”。
條件部分讓純文檔修改保持輕量。強制部分確保 SDK 代碼變更經過倉庫的標準驗證步驟。
實際的驗證流程編碼在技能本身中。
在 Python 倉庫中，它要求執行：
make format
make lint
make typecheck
make tests在 JavaScript 倉庫中，技能要求按這個精確順序執行：
pnpm i
pnpm build
pnpm -r build-check
pnpm -r -F "@openai/*" dist:check
pnpm lint
pnpm test技能編碼了倉庫對“已驗證”的定義，而 AGENTS.md 讓這個定義具有了強制力。
變更集驗證
JavaScript 倉庫對包變更還有一個額外的強制步驟：$changeset-validation，基於 Changesets[14] 構建。
當 packages/ 下有任何變更，或 .changeset/ 發生變化時，模型不能只是跑測試了事。它必須創建或更新正確的變更集，驗證版本升級級別，並確認變更集確實與差異匹配。
這個技能做的不僅僅是檢查文件是否存在。它要求 Codex 審查 git diff，並且把驗證規則放在一個共享的 prompt 中，這樣本地運行和 GitHub Actions 使用的是同一套邏輯。它還編碼了倉庫特有的策略，例如：
• 當分支上已有變更集時，使用現有的而不是再創建一個 • 摘要保持一行，採用 Conventional Commit（約定式提交）風格，這樣它可以兼作提交標題 • 在 1.0 之前，正常功能開發避免主版本升級，並且把明確標記為預覽的新增內容視為補丁級變更（前提是不改變現有行為） • 根據實際的包變更驗證所需的版本升級級別
這讓 Codex 在宣佈工作完成之前，必須先負責驗證自己創建的發佈元數據。
使用最新文檔
兩個倉庫都要求在涉及 OpenAI API 或平台集成的工作中使用 $openai-knowledge。
這個技能是對官方 OpenAI Docs MCP[15] 的輕量封裝。它不讓模型憑記憶回答，而是告訴 Codex 使用 OpenAI 開發者文檔的 MCP 服務器來查找 Responses API、工具、流式傳輸、Realtime 和 MCP 等接口的最新文檔。
如果 MCP 服務器尚未在本地 Codex 環境中配置，該技能會引導維護者前往 Docs MCP 快速入門[16] 和官方 MCP 服務器端點[17]。
準備 PR 交接
在實質性工作結束時，兩個倉庫都使用 $pr-draft-summary。
這個技能只在任務實際完成或準備好審查，且變更涉及有意義的代碼、測試、示例、有行為影響的文檔或構建/測試配置時才觸發。然後它會自動收集分支名、工作樹狀態、變更文件、diff 統計和最近的提交，並輸出：
• 分支名建議 • PR 標題 • PR 描述草稿
輸出格式是刻意固定的。一個典型的結果是這樣的：
# Pull Request Draft
## Branch name suggestion
git checkout -b fix/tracing-lazy-init-fork-safety
## Title
fix: #2489 lazily initialize tracing globals to avoid import-time fork hazards
## Description
This pull request fixes import-time tracing side effects that could break fork-based process models by moving tracing bootstrap to lazy, first-use initialization.
It updates tracing setup so initialization happens once on first access while preserving the existing public tracing APIs.
It also adds regression tests for import-time behavior, one-time bootstrap, and custom provider handling.
This pull request resolves #2489.一旦你信任模型能驗證並總結自己的工作，讓它來生成 PR 草稿就是順理成章的最後一步。這保持了交接的一致性，也減少了編碼工作完成後重複性的書寫工作。
寫好描述字段
技能 SKILL.md 的 frontmatter（文件頭元數據）中的 description 字段是路由契約的一部分。
這是結構性的，不是風格問題。Agent Skills 規範[18]把 name 和 description 定為 SKILL.md frontmatter 的必填字段，其漸進式披露模型規定這些字段在啓動時就會為所有技能加載。SKILL.md 的完整正文以及 scripts/、references/ 或 assets/ 只在技能被實際激活時才加載。
Codex 技能文檔[19]和自定義文檔[8]從 Codex 的角度描述了同樣的行為：Codex 先獲取每個技能的元數據用於發現，只在選中某個技能時才加載 SKILL.md，只在需要時才讀取參考資料或運行腳本。Skills in OpenAI API cookbook[20] 從託管環境的角度同樣明確地描述了這一點：OpenAI 先讀取每個技能的 name、description 和路徑，模型根據這些信息決定何時讀取完整的 SKILL.md。其 SKILL.md frontmatter 章節[21]更直接地指出：name 和 description 對發現和路由至關重要。
在 Agents SDK 倉庫中，這意味着 description 是 Codex 在讀取技能其餘內容之前的主要路由信號之一。
下面是 code-change-verification 的一個具體例子。
太籠統：
description: Run the mandatory verification stack in the OpenAI Agents JS monorepo.更好的寫法（實際使用的描述）：
description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents JS monorepo.簡短版本已經告訴了 Codex 技能做什麼，但沒有說明它何時適用、哪類變更應該觸發它、以及這些檢查是否可選。更具體的版本把這三點都說清楚了。
同樣的模式也出現在 pr-draft-summary 上。
太籠統：
description: Create a PR title and draft description for a pull request.更好的寫法（實際使用的描述）：
description: Create a PR title and draft description after substantive code changes are finished. Trigger when wrapping up a moderate-or-larger change (runtime code, tests, build config, docs with behavior impact) and you need the PR-ready summary block with change summary plus PR draft text.同樣，真正的描述就是路由元數據。它告訴 Codex：
• 這是一個任務結束時的技能 • 它適用於實質性變更，而不是每次對話 • 輸出是一個可直接用於 PR 的結構化塊，而不僅僅是一段文字摘要
這些倉庫的經驗是：在 description 上花時間。如果路由感覺不可靠，先修描述，再加代碼。
把機械性操作放進腳本
接下來的問題是：什麼該留在模型裏，什麼該下沉到腳本中。
一個可靠的劃分原則是：
• 解讀、對比和報告留給模型 • 確定性的、重複的 shell 操作放進 scripts/
這與公開的指導一致。Codex 自定義文檔[8]把技能描述為一種方式，讓 Codex 獲得更豐富的指令、腳本和參考資料來執行可重複的工作流，同時不會一開始就撐大上下文。這適合以模型為先的架構：讓 Codex 處理依賴上下文的部分，只在需要時引入腳本處理確定性的部分。Skills in OpenAI API cookbook[22] 也建議把技能腳本設計成微型 CLI：從命令行運行、輸出確定性的 stdout、出錯時顯式報錯，需要時把輸出寫入已知的文件路徑。
在 Agents SDK 倉庫中，我們儘量把模型用在它的智能真正有價值的地方，例如：
• 閲讀源碼以推斷預期行為 • 將日誌與預期行為進行對比 • 判斷一個發佈差異中是否存在真正的兼容性風險 • 生成維護者可以據此行動的解釋
腳本則負責這些工作周圍的機械性操作，例如：
• 按固定順序運行倉庫要求的驗證命令 • 啓動示例運行、收集每個示例的日誌、為失敗的示例生成重試文件 • 在發佈就緒性審查之前獲取上一個發佈標籤 • 暴露諸如 start、stop、status、logs、tail、collect和rerun之類的輔助命令，讓同一個工作流可以方便地反覆運行
如果模型每次都要重新發現同一套 shell 腳本流程，那通常意味着這套流程應該變成一個腳本。如果任務取決於上下文、權衡或解釋，那部分就該留在模型裏。
自動化集成測試
兩個倉庫中最有用的工作流領域之一是自動化集成測試。這裏有兩個相關的層次：在兩個倉庫中自動驗證倉庫內的示例，以及在 JavaScript 倉庫中單獨驗證發佈的包在用戶實際的安裝方式下是否仍能正常工作。
在這套配置之前，驗證示例大多靠手動。你可以運行示例，但最後一公里往往取決於肉眼檢查日誌或憑經驗判斷輸出是否正確。對一個示例來說還能應付，但在一個不斷增長的 SDK 倉庫中就難以為繼了。
第一層是 examples-auto-run，但技能是在運行器之後才出現的。要實現示例驗證的自動化，我們首先得在兩個倉庫中構建非交互式示例執行的底層支持。這意味着讓示例腳本能夠在自動模式下運行，包括那些通常需要用戶輸入或審批的示例。
這些基礎工作包括：
• 自動回答常見的交互式提示 • 在運行器支持的範圍內，自動通過人工審核環節（HITL）、MCP、 apply_patch和 shell 操作• 把仍不適合自動化的示例放在跳過列表中，例如需要額外運行時配置的 Realtime 或 Next.js 應用示例 • 為每次示例運行編寫結構化日誌 • 生成重試文件，這樣失敗時無需重新運行所有內容
基礎就位後，我們把它組織成了一個技能，讓工作流變得可複用且易於調用。在 Python 倉庫中，examples-auto-run 封裝了 uv run examples/run_examples.py --auto-mode --write-rerun --main-log ... --logs-dir ...。在 JavaScript 倉庫中，它先運行構建檢查，然後在自動模式下執行 pnpm examples:start-all，帶有逐示例的日誌和重試支持。
為了提高驗證質量，運行器的任務是執行示例並將它們的 stdout 和 stderr 保存到逐示例的日誌中。然後技能讓 Codex 逐一檢查這些日誌，並與源碼進行對比：
• 閲讀示例的源碼和註釋 • 推斷預期的執行流程 • 打開對應的日誌 • 將預期行為與實際的 stdout 和 stderr 進行比較 • 對每個成功運行的示例都這樣做，而不只是抽檢一個
這比把正確性編碼為固定的腳本級斷言更準確也更靈活。成功的退出碼有用，但對於調用真實 API、使用工具或產生結構化輸出的示例來說是不夠的。通過先記錄實際輸出，再仔細對照源碼檢查，我們可以根據每個示例的真實意圖來驗證它。
在 JavaScript 倉庫中，還有第二層：獨立的 integration-tests 技能。這個工作流不止於在倉庫內運行源碼示例。它把包發佈到本地 Verdaccio 註冊中心，然後在多種環境中測試安裝和運行，包括 Node.js、Bun、Deno、Cloudflare Workers 和 Vite React 應用。這抓的是另一類問題：不是“示例在倉庫裏能不能跑”，而是“包在經過發佈、安裝和運行時集成之後，行為是否仍然正確”。
合在一起看，就能理解為什麼技能、腳本和模型判斷的組合管用。腳本讓運行可重複、捕獲證據、覆蓋手動檢查起來繁瑣的安裝路徑。Codex 則利用這些證據，做出比簡單的腳本通過/失敗檢查更細緻的對比。
增加發布檢查
發佈準備是這個模式特別合適的另一個場景。
兩個倉庫中的發佈審查工作流從查找上一個發佈標籤開始，將其與最新的 main 分支進行 diff，然後要求 Codex 檢查該差異中的：
• 公共 API 和麪向用戶的 SDK 行為中的向後兼容性問題 • 迴歸問題，包括預期行為的細微變化 • 需要遷移說明或發佈說明更新但尚未添加的變更
根據這些發現，技能做出整體的發佈就緒性判斷。
一個具體的例子是 openai/openai-agents-python#2480[23]，在這次發佈審查中，整體結論是綠燈放行，同時指出了 Python 3.9 支持的移除以及它所需的發佈說明跟進：
Release readiness review (excerpt)
Release call:
🟢 GREEN LIGHT TO SHIP. Minor-version bump includes expected breaking change
(Python 3.9 drop) with no concrete regressions found.
Scope summary:
- 38 files changed (+1450/-789); key areas touched: `src/agents/tool.py`,
`src/agents/extensions/`, `src/agents/realtime/`, `tests/`,
`pyproject.toml`, `uv.lock`.
Python 3.9 support removed
- Risk: 🟡 MODERATE. Users pinned to Python 3.9 will be unable to install the
0.9.0 release.
- Evidence: `pyproject.toml` now sets `requires-python = ">=3.10"` and drops
the Python 3.9 classifier; CI skip logic for 3.9 was removed.
- Action: Ensure release notes clearly call out the Python 3.9 drop and that
packaging metadata remains `>=3.10`.技能還定義了關卡決策的方式。審查從“可以安全發佈”出發，只有當差異中出現了真實問題的具體證據時才切換為阻止發佈。每個阻止決定都必須附帶具體的解除阻止清單。這讓輸出更易使用：綠燈意味着差異中未發現阻止發佈的問題，紅燈意味着存在真實問題且有明確的下一步。
這比泛泛的“請審查一下這次發佈”要有用得多。它迫使模型基於具體的差異進行推理，並用可操作的術語解釋結果。如果發佈是安全的，就直接說安全。如果不安全，就指出確切的證據和確切的後續步驟。
在 CI 中運行工作流
當一個技能在本地驗證有用之後，Codex GitHub Action[6] 可以輕鬆地把同一個工作流自動化到 CI 中。最好等本地工作流穩定了再上 CI，因為手動跑才是調試指令、打磨腳本、發現邊界情況的過程。
對於公開倉庫，觸發器的設計和技能本身同樣重要。GitHub Action 安全清單[24]建議限制誰能啓動工作流、優先使用可信事件或顯式審批、對來自 PR、提交、issue 或評論的 prompt 輸入進行清理、用 drop-sudo 或非特權用戶保護 OPENAI_API_KEY，以及把 Codex 作為任務中的最後一步運行。
如果一個工作流具有寫權限且接受不可信的公開輸入，風險通常出在技能周圍的觸發器設計、輸入處理和運行時權限上。
在 PR 審查中使用 Codex
技能是這些倉庫效率提升的一部分。Codex GitHub PR 自動審查[25]是另一部分。
自從 Codex GitHub PR 自動審查上線以來，Codex 在這些倉庫的大多數代碼變更審查中都有幫助。我們把它當常規審查環節，不是特殊工具。
對於直接的程序錯誤、迴歸和缺失的測試，把 Codex 作為必要的審查路徑在實踐中已經足夠可靠。它能始終如一地反覆檢查同樣的正確性模式，並消除了小修復和日常改進的一個主要瓶頸。
人工審查依然重要，但針對的是另一類變更。
當核心問題不是“這段代碼正確嗎”而是“在多個合理的方案中我們該選哪個，以及該如何發佈”時，人工審查仍然不可或缺。這包括：
• API 或架構變更，存在多個合理的設計方案，維護者需要做出明確選擇 • 行為變更，影響產品預期、向後兼容性承諾或發佈策略 • 命名、遷移和發佈溝通決策，難點在於選擇對用戶和貢獻者最清晰的方案 • 需要維護者或團隊間對齊的變更，比如確定範圍、排列優先級，或決定哪些內容現在發佈、哪些以後再說
Codex 在所有這些場景中仍然能提供有用的貢獻，但它們仍然需要人類決策者和直接討論。
AGENTS.md 也可以編碼這種分工：倉庫可以告訴 Codex 在正確性審查中什麼是重要的，Codex 就能持續一致地應用這些指導。
這也是效率提升的重要貢獻者。重複性的審查和驗證工作不再需要為每個低風險變更等待稀缺的審查者時間，而維護者可以專注於需要他們判斷力的高上下文審查。這種轉變幫助我們更快地處理了積壓的 bug 和小規模的功能改進。
寫在最後
在 OpenAI Agents SDK 倉庫中，技能在融入倉庫的日常工作配置時效果最好。
AGENTS.md 告訴 Codex 哪些工作流是必需的。description 告訴它何時路由到這些工作流。scripts/ 處理確定性的部分。模型處理需要上下文的部分。而當一個工作流在本地穩定之後，Codex GitHub Action[6] 可以把同樣的流程帶入 CI。
這讓這些倉庫中的日常工程工作變得更明確、更可靠。小改進的發佈也更快了，驗證、發佈審查和 PR 交接都走同一套流程。
參考資源
• OpenAI Agents SDK for Python[2] • OpenAI Agents SDK for JS[3] • Skills in Codex[8] • Custom instructions with AGENTS.md[26] • Codex GitHub Action[6] • Use Codex in GitHub[25] • Skills in OpenAI API cookbook[27] • Agent Skills specification[18] • Skills in OpenAI API: operational best practices[22]
引用連結
[1] OpenAI Agents SDK: https://developers.openai.com/api/docs/guides/agents-sdk[2] Python: https://github.com/openai/openai-agents-python[3] TypeScript: https://github.com/openai/openai-agents-js[4] Realtime API: https://developers.openai.com/api/docs/guides/realtime[5] `AGENTS.md`: https://agents.md/[6] Codex GitHub Action: https://developers.openai.com/codex/github-action[7] Codex for Open Source: https://developers.openai.com/codex/community/codex-for-oss[8] Codex 自定義文檔: https://developers.openai.com/codex/concepts/customization#skills[9] openai-agents-python 中的 .agents/skills: https://github.com/openai/openai-agents-python/tree/main/.agents/skills[10] openai-agents-js 中的 .agents/skills: https://github.com/openai/openai-agents-js/tree/main/.agents/skills[11] AGENTS.md 指南: https://developers.openai.com/codex/guides/agents-md#layer-project-instructions[12] openai-agents-python 的 AGENTS.md: https://github.com/openai/openai-agents-python/blob/main/AGENTS.md[13] openai-agents-js 的 AGENTS.md: https://github.com/openai/openai-agents-js/blob/main/AGENTS.md[14] Changesets: https://github.com/changesets/changesets[15] OpenAI Docs MCP: https://developers.openai.com/resources/docs-mcp[16] Docs MCP 快速入門: https://developers.openai.com/resources/docs-mcp#quickstart[17] 官方 MCP 服務器端點: https://developers.openai.com/mcp[18] Agent Skills 規範: https://agentskills.io/specification[19] Codex 技能文檔: https://developers.openai.com/codex/skills[20] Skills in OpenAI API cookbook: https://developers.openai.com/cookbook/examples/skills_in_api/#what-is-a-skill[21] SKILL.md frontmatter 章節: https://developers.openai.com/cookbook/examples/skills_in_api/#skillmd-frontmatter[22] Skills in OpenAI API cookbook: https://developers.openai.com/cookbook/examples/skills_in_api/#operational-best-practices[23] openai/openai-agents-python#2480: https://github.com/openai/openai-agents-python/pull/2480[24] GitHub Action 安全清單: https://developers.openai.com/codex/github-action#security-checklist[25] Codex GitHub PR 自動審查: https://developers.openai.com/codex/integrations/github[26] Custom instructions with AGENTS.md: https://developers.openai.com/codex/guides/agents-md[27] Skills in OpenAI API cookbook: https://developers.openai.com/cookbook/examples/skills_in_api