生活分享
Skills 與 SKILL.md
Skill 將固定工作流程整理成可重用的指示與資源。最小結構是一個資料夾與 SKILL.md,檔案前段需要 name 和 description,正文描述操作與輸出。安裝技能不代表每個任務都必然使用,還要檢查是否載入。
閱讀時間約 12 分鐘 · 操作 25 分鐘

本篇目錄
返回 Codex 教學總目錄Codex 學習中心:完整教學目錄從安裝、第一個任務到 MD 規則與進階整合,規劃 60 篇 Codex 教學、十個單元。依程度、平台、需求或指令搜尋下一篇;尚未公開的教學會標示狀態,方便安排學習路線。閱讀全文
讀完能做到什麼
Skill 適合把會反覆使用的工作流程整理成可重用指引,例如每次改完待辦網站後的驗收。不要把所有專案規則都移過來:AGENTS.mdAGENTS.md 專案規則AGENTS.md 是讓 Codex 在開始工作前取得專案規則的檔案。全域規則、專案根目錄與工作目錄路徑中的子目錄規則會形成一條指令鏈;同一層有 AGENTS.override.md 時優先讀取它。規則愈具體愈容易遵循,仍需要驗證實際載入。閱讀全文處理持續適用的專案要求,Skill 則針對特定任務被選用。Plugins 可用來分發技能與連接服務,詳見插件教學Plugins 與外部服務Plugin 可以把 Skills 與 MCP 工具包在一起,提供可安裝的工作能力。安裝套件、連接外部帳號與實際執行工具是三個不同步驟;找到插件不代表已能讀你的服務資料。閱讀全文。
開始之前
準備已登入的 Codex CLI 或支援 Skills 的桌面/IDE 入口,並下載待辦網站教材。本篇先複製 expected 為 codex-practice;再保留 broken 作為稍後的獨立故障練習,不要把兩個版本的檔案混在一起。
測試使用 Node.js,瀏覽器預覽使用 Python 3。沒有瀏覽器工具時,技能應回報畫面檢查未執行,提供給你手動操作的步驟;不能因為寫了「檢查畫面」就假設環境會自動多出工具。你也可以下載完整技能範例,先閱讀再放入練習專案。
最少必要概念:名稱、描述與內容
一個技能至少是一個資料夾與其中的 SKILL.md。檔案開頭用 YAML frontmatter 保存 name 和 description,正文才是執行流程。Codex 先看到名稱與描述,決定使用後才讀完整內容,所以「什麼都幫忙」之類的描述很容易在不適合的任務被選中。
本例的名字是 todo-acceptance,描述把範圍限定為 Small Steps 的驗收,而不是任意網站開發。先保持純指引,不加腳本、外部服務或全域安裝。只有需要穩定重複的工具邏輯時,再將程式放進 scripts;大量參考資料可以另放 references 並在主文件指出何時讀取。
第一步:建立專案內的技能位置
從 codex-practice 根目錄建立 .agents/skills/todo-acceptance。前面的點是資料夾名稱的一部分;不是 .codex,也不是 agents 少一個點。Windows PowerShell 可執行以下命令;已存在時先看內容,不要覆蓋別人的技能。
New-Item -ItemType Directory -Force .agents/skills/todo-acceptance
mkdir -p .agents/skills/todo-acceptance
用純文字編輯器建立 SKILL.md,Windows 檢查不是 SKILL.md.txt,Linux 檢查大寫檔名。完成後的目錄如下。這個位置讓技能和練習專案一起管理,不會立刻變成所有專案共用的個人技能。
codex-practice/
index.html
style.css
app.js
core.mjs
core.test.mjs
.agents/
skills/
todo-acceptance/
SKILL.md
第二步:寫入完整技能
以下內容與下載範例相同。流程會讀現有程式、執行既有測試、在可用時檢查瀏覽器,最後以 PASS、FAIL、NOT RUN 區分結果。它不會為了讓驗收通過而偷偷修程式,讓你能先看懂實際問題再決定是否修改。
---
name: todo-acceptance
description: Verify the Small Steps todo practice website after a change, using its existing tests and browser checks. Use for acceptance checks of this exercise, not unrelated websites or feature implementation.
---
# Small Steps acceptance
Confirm the requested practice folder contains index.html, style.css, app.js,
core.mjs and core.test.mjs. If these are missing, stop and report the path checked.
Read the existing code, then run `node --test core.test.mjs` from that folder.
Do not rewrite tests or implementation to make an acceptance run pass.
If a browser is available, preview the site on a loopback address with a fresh
browser context. Add Read and Build, complete Read, check Active and Completed
filters, reload, and delete Read. Reject whitespace-only input. Check 390px and
1280px widths and visible Tab focus. Keep existing user browser data unchanged.
Report PASS, FAIL or NOT RUN for each check, with the command, observation or
limitation. Include the working folder and remaining issues. Do not claim that
tests, screenshots, deployment or publication happened without evidence.
If a check fails, report the reproduction and relevant file. If a required tool
is unavailable, report NOT RUN and the manual steps. Finish with results only;
implement fixes only when the user requests them.
name 適合用小寫英文、數字及連字號,資料夾名稱也保持相同。description 的觸發邊界寫在前面,正文則保留真正會影響決策的條件。本例沒有多餘的套件或設定檔;建立更多空資料夾不會讓技能更完整。
第三步:找到技能並明確使用
Codex 會偵測技能變更;沒有出現時重新開啟工作階段,確認工作目錄位於此專案。CLI 或 IDE 可用 /skills 或輸入 $ 尋找技能;桌面應用程式可由側欄 Skills 檢查可用項目,依目前介面選擇。選單能找到名稱,才是「已發現」的證據,仍不是已執行。
$todo-acceptance Check this Small Steps practice folder. Report the results without editing files.
桌面版若提供技能選擇器,先選 todo-acceptance,再送出同樣的驗收要求。開始時請確認它讀的是本專案 SKILL.md,而不是另一個同名技能。兩個同名技能不會自動合併;全域或其他目錄存在同名項目時,路徑尤其重要。
第四步:核對正常與故障結果
在 expected 副本,node --test core.test.mjs 應有 3 個測試通過。回應應列出實際命令與結果;如果也執行瀏覽器流程,應能描述 Read、Build、篩選、重新整理及空白輸入的結果。沒有瀏覽器時應把該項列 NOT RUN,這不是測試通過也不是整個技能失效。
再建立一份獨立 broken 副本,把同一個技能資料夾放到該副本的 .agents/skills,從那個位置建立新任務。這個版本刻意把 Completed 篩選反過來:Read 完成、Build 未完成時,會錯誤顯示 Build。資料測試應為 2 個通過、1 個失敗,技能應報告 FAIL 和重現方法,原始碼維持不變。
這個比較能驗證工作流程是否會忠實回報失敗。檔案格式檢查只證明 YAML、名稱與結構能解析,不證明代理真的照流程做;反過來,測試失敗也可能正是技能成功找到問題。請分開保存這些證據,避免只有一個模糊的「成功」勾選。
再驗證「材料不足就停止」
另外複製 expected 成一份獨立的 incomplete 練習目錄,放入同一份技能。先把這個副本的 core.test.mjs 移到該目錄外的備份位置,保留原始 expected 與 broken 不變,再從 incomplete 開新任務選用技能。合格結果是指出缺少的檔案與檢查路徑,停止後續驗收;不能自行補寫測試、改到另一份目錄執行,或沿用先前的通過結果。完成後把備份放回原位置,再重新驗收。
這與 broken 的差別是:broken 材料齊全、測試確實執行但失敗;incomplete 尚不符合起步條件;沒有瀏覽器工具則只讓畫面項目 NOT RUN。不要把三種情況都寫成同一個 FAIL。要整理更多輸入與觸發情境,接著看技能測試Skill 觸發與結果測試分開驗證格式、選用條件及實際結果,用應觸發與不應觸發的案例修正技能描述。閱讀全文;要加入腳本與參考文件,先看技能資源Skill 的腳本、參考文件與材料把重複邏輯與大型資料拆到必要的支援檔案,讓技能按需要讀取並驗證相對路徑。閱讀全文。
常見問題、停用與還原
技能沒有出現:先檢查 .agents/skills 的位置、SKILL.md 真正副檔名、frontmatter 是否以兩行 --- 包住,以及 name/description 是否存在。確認不是把整個 ZIP 放進資料夾後就以為已安裝。修正後重開 Codex 再查選單。
技能出現卻沒使用:先明確選取或以 $todo-acceptance 指定,檢查名稱及來源路徑。自動選用依描述與任務判斷,不保證任何一句相似文字都會觸發。若普通問候也經常觸發,應收窄描述,讓它只處理待辦網站驗收。
被選用卻無法測試:確認 Node.js 在實際主機可用、目前目錄含 core.test.mjs。從手機 Remote 使用時,技能與測試工具都在主機;電腦 A 裝好不代表電腦 B 也有。不要讓技能自行安裝所有缺少的工具來掩蓋環境條件。
停止進行中的驗收先在任務內中止;需要停用時,將這份練習技能移出專案的技能掃描位置,保留備份,再重開工作階段核對。更細的停用設定可以依官方 [[skills.config]] 說明處理,但要先保留既有 config.toml。停用不會刪除之前的報告,也不會撤銷任何過去修改。
| 狀態 | 可以證明什麼 | 尚不能證明什麼 |
|---|---|---|
| 格式有效 | 必要欄位可以解析 | 會被選到 |
| 已發現 | 選單找到正確名稱與路徑 | 已讀取完整流程 |
| 已採用 | 任務讀取技能內容 | 所有檢查都完成 |
| 已驗證 | 有實際測試或畫面結果 | 已經發布網站 |
小練習與驗證紀錄
比較兩個提示詞:「請驗收 Small Steps 的篩選與儲存」和「請解釋今天的練習目標」。前者適合使用技能,後者不需要完整驗收。記錄選用與否、實際路徑和結果,根據觀察調整描述;不要把一次選對就當成所有情境都通過。
技能機制依 Build skills 官方文件於 2026-09-14 查證。範例會做格式驗證,網站核心與故障結果已有實際測試;自動觸發與不同 Codex 介面的選擇器仍須分別實測,未列為全部通過。下一步可讀插件Plugins 與外部服務Plugin 可以把 Skills 與 MCP 工具包在一起,提供可安裝的工作能力。安裝套件、連接外部帳號與實際執行工具是三個不同步驟;找到插件不代表已能讀你的服務資料。閱讀全文、MCPMCP 設定與連線排除MCP 讓 Codex 使用外部工具與資料。STDIO 伺服器通常由本機命令啟動;HTTP 伺服器透過 URL 連線。設定檔寫入成功只代表設定存在,還需要確認服務啟動、驗證通過與工具回應。閱讀全文及測試與審查測試、Code Review 與 PR測試確認程式在指定條件的行為,Code Review 檢查變更是否有遺漏或風險,PR 則讓人查看並討論要合併的差異。三者互補;通過測試不等於審查通過,開 PR 也不是已合併。閱讀全文。
返回 Codex 教學總目錄Codex 學習中心:完整教學目錄從安裝、第一個任務到 MD 規則與進階整合,規劃 60 篇 Codex 教學、十個單元。依程度、平台、需求或指令搜尋下一篇;尚未公開的教學會標示狀態,方便安排學習路線。閱讀全文
閱讀完整文字說明
SKILL.md to Invoke to Output
覺得這篇整理實用嗎?分享給需要的朋友
同主題延伸閱讀
生活分享
Codex 學習中心:完整教學目錄
從安裝、第一個任務到 MD 規則與進階整合,規劃 60 篇 Codex 教學、十個單元。依程度、平台、需求或指令搜尋下一篇;尚未公開的教學會標示狀態,方便安排學習路線。
生活分享
Worktree 與多任務隔離
Worktree 讓同一個 Git 程式庫有不同的工作目錄,各自承接不同分支。它適合讓兩項工作分開改檔,但資料庫、連接埠與外部服務仍可能共用,不能把檔案隔離當成所有資源隔離。
生活分享
實戰:製作小網站
從 brief.md 規劃並製作 Small Steps 待辦網站,完成新增、完成、刪除、篩選與本機資料保存。將 HTML、CSS、資料函式、畫面事件與測試分開,以 Node 測試和瀏覽器操作驗收,並留下可重新啟動與還原的交接紀錄。
引用本文的文章
資料來源
- Build skills查證日期:
- Codex CLI developer commands查證日期:
本文依據上方所列參考來源與標示之核對日期整理;票價、時刻、功能規格或服務條款可能變動,出發、預訂或購買前請至相關官方網站確認最新資訊。