Codex 自定義 SKILL.md 團隊規範編寫教學:帶腳本與模板目錄的內部發版、單測與排錯技能包

把發版檢查、單測模板和排錯步驟全塞進 AGENTS.md 會迅速撐爆上下文。本文按 Agent Skills 標準講清 Codex 自定義 SKILL.md 與 scripts/、references/、assets/ 目錄結構,並給出發版、單測與排錯三套團隊技能包範本。

NNathaniel bigo··原創首發·AI 輔助撰寫
11 分鐘讀完
資料核對於 2026-11-19 · 依據官方文檔與公開資料整理 Plus 帳號

結論先說

  1. 技能包的核心優勢是「漸進式加載」,不會常駐佔滿上下文。會話啟動時 Codex 只讀取每個 SKILL.md 頭部極短的 name 與 description;只有當前任務匹配(或主動調用)時,才按需載入詳細說明、模板與文檔。
  2. 把確定性動作放進 scripts/,把大段規則拆進 references/,把樣板放進 assets/。讓模型直接執行經過評審的腳本而非現場拼複雜命令,既降低出錯率,也只把腳本輸出結果送進上下文,不浪費 Token 讀腳本源碼。
  3. 團隊共享技能直接提交在倉庫的 .agents/skills/<技能名>/ 下。隨 Git 版本管理與 PR 評審流轉,新人拉下代碼立刻自動擁有團隊發版、單測與排錯能力;個人通用技能則放在 ~/.agents/skills/。
  4. description 的觸發邊界寫得好不好,決定技能會不會被誤觸發或漏觸發。務必用一兩句清楚寫明「何時該用」與「不要在什麼場景下用」,避免多個相似技能互相搶佔。
  5. 在團隊倉庫持續迭代、調試多個帶腳本與參考文檔的技能包需要頻繁試跑驗證。國內無外幣卡的用戶可在本站開通 ChatGPT Plus 或高配額的 ChatGPT Pro,團隊多人協作可了解 ChatGPT Business 團隊定製。

SKILL.md 技能包四層目錄職責分工

圖:本站根據 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 註冊手機驗證服務。

三、編寫高質素團隊技能包的六項規範檢查

編寫團隊 SKILL.md 技能包六項規範核對

圖:本站根據 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 付款,無需交出帳號密碼,可開具增值稅發票;實時價格以商品頁展示為準,售後遵循掉訂閱按剩餘天數折退、封號不在質保範圍的規則。

相關教學

參考資料

  • 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

Nathaniel 的更多內容

  1. 01

    獨立開發者用 ChatGPT + Codex 跑通產品全流程:市場驗證、PRD、原型到代碼上線覆盤清單

    單人做獨立產品最容易陷入「閉門寫兩個月代碼上線零用戶」或「AI 寫到一半目錄越改越崩」。本文整理「ChatGPT 負責市場驗證、PRD 與覆盤 + Codex 負責工程實現與測試」的五階段雙軌流程,附起手提示詞與 7 項上線覆盤清單。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成規範文件命名規則、整理混亂目錄樹與合併零散發票抬頭清單腳本

    面對滿桌面的「新建文件夾」「最終版2」和上百張零散電子發票,手工改名抄台帳耗時又容易漏重。本文分享先脫敏取樣、再用 ChatGPT 生成帶預演和回滾日誌的本地 Python 腳本,離線安全完成目錄整理與發票抬頭合併去重的實戰流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外電郵營銷(EDM)受眾分層文案、A/B 主題行測試與防進垃圾箱自檢

    做海外獨立站或出海 SaaS 電郵營銷(EDM),最怕千人一面群發被直接送進垃圾箱。本文結合 Gmail/Yahoo 批量發件人規範,梳理用 ChatGPT 設計受眾分層文案、批量生成 A/B 主題行矩陣並開展發前垃圾詞與合規自檢的實戰提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫 Notion Formula 2.0 公式、Obsidian Dataview 查詢與 Airtable 自動化腳本

    給 Notion 數據庫寫多條件 Formula 2.0 公式、給 Obsidian 寫 Dataview 動態看板,或在 Airtable 裏寫自動化腳本,經常因為一個小括號或類型不匹配報錯半天。本文整理三大工具的通用上下文喂料規範與三套直接可複製的生成提示詞。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 處理複雜 JSON / YAML / XML 字段映射、格式轉換與校驗規則編寫實戰

    對接第三方 API、遷移 Kubernetes 配置或解析政企 XML 報文時,手工對照幾百行嵌套字段既慢又容易漏掉空值與類型邊界。本文整理用 ChatGPT 完成字段映射表梳理、生成確定性轉換腳本以及編寫 JSON Schema / Pydantic / XSD 校驗規則的實戰流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 準備本科/碩士畢業論文答辯:提煉答辯 PPT 結構、模擬導師犀利追問與 3 分鐘自述稿

    畢業論文寫完後,要在 3–5 分鐘內講清研究價值並頂住答辯評委的連環追問並不輕鬆。本文整理在嚴格遵守高校學術規範的前提下,用 ChatGPT 提煉答辯 PPT 結構、打磨 3 分鐘口語自述稿並開展模擬導師犀利追問的排練流程與提示詞。

    ChatGPT0

同產品的其他教學

  1. 01

    用 ChatGPT 整理家庭裝修預算明細、隱蔽工程驗收清單與主材優缺點對比表實戰

    第一次裝修面對幾十頁施工報價單、密密麻麻的水電防水隱蔽項目與五花八門的主材參數,極易踩坑增項。本文梳理用 ChatGPT 審查裝修報價漏項、生成帶公式的預算明細表、定製工地隱蔽工程驗收單與主材對比表的實戰提示詞。

    ChatGPT0
  2. 02

    用 ChatGPT 做費曼學習法讀書共讀:反向追問檢驗自己是否真讀懂專業書籍與整理書單筆記

    讀完一本專業硬書常感覺「合上書就忘」,直接讓 AI 概括全書又容易產生懂了的錯覺。本文介紹用 ChatGPT 結合 Study Mode 與費曼學習法做反向追問共讀,通過通俗複述、挑刺盲區到沉澱書單卡片的完整流程與提示詞。

    ChatGPT0
  3. 03

    用 ChatGPT 做外貿產品多語種目錄、展會邀約與客戶跟進節奏表(附脫敏與本地化提示詞)

    做外貿展會與海外推廣時,手工翻譯十幾款產品目錄費時且容易留下一堆中式英文,展後客戶跟進也常缺節奏。本文梳理用 ChatGPT 先脫敏建術語庫、再批量產出多語種目錄、展前邀約函與展後 21 天跟進節奏表的實戰流程與提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫高質素技術專欄文章、開源項目 Release Notes 與版本更新日誌實戰

    讓 AI 直接憑空寫技術文章容易滿篇空洞套話,直接甩 Git 記錄寫更新日誌又常常漏掉破壞性變更。本文整理用 ChatGPT 結合真實代碼片段、壓測數據與 PR 摘要,高效產出深度技術專欄、GitHub Release Notes 與 CHANGELOG 的實戰工作流。

    ChatGPT0
  5. 05

    用 ChatGPT 做產品用戶訪談紀要編碼、提煉高頻痛點需求池與 RICE 優先級打分實戰

    手頭攢了十幾份用戶訪談逐字稿,手工貼便利貼歸納痛點耗時又容易帶入主觀偏見。本文分享用 ChatGPT 完成脫敏檢查、逐份開放式編碼、跨樣本聚類高頻痛點並搭建 RICE 優先級打分表的 5 步實戰流,附可直接複製的三段核心提示詞。

    ChatGPT0
  6. 06

    ChatGPT 網頁版上載超過 10 個文件或回形針附件按鈕變灰怎麼辦:打包合併與配額限制排查

    在 ChatGPT 網頁版批量分析文檔時,常遇到一次選超 10 個文件被攔截或輸入框回形針按鈕變灰。本文依據 OpenAI 文件上載與存儲說明,梳理 6 類常見報錯的分流排查法,提供 ZIP 打包、本地合併與 Projects 複用方案及可直接複製的解包提示詞。

    ChatGPT0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~