生活分享

Skills 與 SKILL.md

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

閱讀時間約 12 分鐘 · 操作 25 分鐘

LINE 分享
實作順序示意圖,非產品介面截圖。
圖片:Mokaair (© Mokaair)
本篇目錄
  1. 1. 讀完能做到什麼
  2. 2. 開始之前
  3. 3. 最少必要概念:名稱、描述與內容
  4. 4. 第一步:建立專案內的技能位置
  5. 5. 第二步:寫入完整技能
  6. 6. 第三步:找到技能並明確使用
  7. 7. 第四步:核對正常與故障結果
  8. 8. 常見問題、停用與還原
  9. 9. 小練習與驗證紀錄

讀完能做到什麼

Skill 適合把會反覆使用的工作流程整理成可重用指引,例如每次改完待辦網站後的驗收。不要把所有專案規則都移過來:處理持續適用的專案要求,Skill 則針對特定任務被選用。Plugins 可用來分發技能與連接服務,詳見。

開始之前

準備已登入的 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 可執行以下命令;已存在時先看內容,不要覆蓋別人的技能。

Windows PowerShell;codex-practice 根目錄 · powershell
New-Item -ItemType Directory -Force .agents/skills/todo-acceptance
macOS / Linux 終端機;codex-practice 根目錄 · bash
mkdir -p .agents/skills/todo-acceptance

用純文字編輯器建立 SKILL.md,Windows 檢查不是 SKILL.md.txt,Linux 檢查大寫檔名。完成後的目錄如下。這個位置讓技能和練習專案一起管理,不會立刻變成所有專案共用的個人技能。

codex-practice 內的完整必要結構 · text
codex-practice/
  index.html
  style.css
  app.js
  core.mjs
  core.test.mjs
  .agents/
    skills/
      todo-acceptance/
        SKILL.md

第二步:寫入完整技能

以下內容與下載範例相同。流程會讀現有程式、執行既有測試、在可用時檢查瀏覽器,最後以 PASS、FAIL、NOT RUN 區分結果。它不會為了讓驗收通過而偷偷修程式,讓你能先看懂實際問題再決定是否修改。

寫入 .agents/skills/todo-acceptance/SKILL.md;完整檔案 · markdown
---
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 檢查可用項目,依目前介面選擇。選單能找到名稱,才是「已發現」的證據,仍不是已執行。

Codex CLI 或 IDE 對話輸入框;不是系統 shell · text
$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。要整理更多輸入與觸發情境,接著看;要加入腳本與參考文件,先看。

常見問題、停用與還原

技能沒有出現:先檢查 .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 介面的選擇器仍須分別實測,未列為全部通過。下一步可讀、及。

23. Skills 與 SKILL.md — 實作順序示意圖,非產品介面截圖。 SKILL.md → Invoke → Output
23. Skills 與 SKILL.md — 實作順序示意圖,非產品介面截圖。 SKILL.md → Invoke → Output · 圖片:Mokaair (© Mokaair)
閱讀完整文字說明

SKILL.md to Invoke to Output

覺得這篇整理實用嗎?分享給需要的朋友

LINE 分享

回總目錄

  • 生活分享

    Codex 學習中心:完整教學目錄

    從安裝、第一個任務到 MD 規則與進階整合,規劃 60 篇 Codex 教學、十個單元。依程度、平台、需求或指令搜尋下一篇;尚未公開的教學會標示狀態,方便安排學習路線。

  • 生活分享

    Worktree 與多任務隔離

    Worktree 讓同一個 Git 程式庫有不同的工作目錄,各自承接不同分支。它適合讓兩項工作分開改檔,但資料庫、連接埠與外部服務仍可能共用,不能把檔案隔離當成所有資源隔離。

  • 生活分享

    實戰:製作小網站

    從 brief.md 規劃並製作 Small Steps 待辦網站,完成新增、完成、刪除、篩選與本機資料保存。將 HTML、CSS、資料函式、畫面事件與測試分開,以 Node 測試和瀏覽器操作驗收,並留下可重新啟動與還原的交接紀錄。

  • 生活分享

    用量與效率:減少重工

    記錄任務條件、模型選項、時間與成果,找出能減少無效重試和過多上下文的調整。

資料來源

本文依據上方所列參考來源與標示之核對日期整理;票價、時刻、功能規格或服務條款可能變動,出發、預訂或購買前請至相關官方網站確認最新資訊。

生活分享