Claude Code｜建立第一個 SKILL.md

本篇會建立一個名為 todo-review 的 Skill，讓你在 Claude Code 對話輸入斜線名稱，就能重用同一套待辦專案審查流程。成果是一個可讀、可修改、可移除的 SKILL.md，以及一次包含具體檔名與驗證狀態的審查報告。

請先準備待辦練習專案，並閱讀 Markdown 基礎。以下路徑都相對於專案根目錄，示範的是 Claude Code 專案 Skill；其他產品的技能上傳欄位與可用設定可能不同，不能直接假設完全相容。

了解資料夾與 frontmatter

閱讀完整文字說明

建立第一個 SKILL.md，以流程和文件圖形呈現教學重點。

一個 Skill 至少有一份 SKILL.md，放在 .claude/skills/技能名稱/。檔案開頭兩段三連字元之間是 YAML frontmatter，用來描述名稱、用途及呼叫方式；後面的 Markdown 才是實際工作步驟。檔案名稱的大寫與副檔名應完整保留。

本例使用專案範圍，方便和練習材料一起管理。如果要讓所有專案都可用，可以放在使用者的 ~/.claude/skills/，但先在單一專案驗證較容易排錯。同名的個人、專案與外掛技能可能發生覆蓋，應避免用過於通用的名稱。

建立第一份技能

在編輯器建立 .claude/skills/todo-review/SKILL.md，貼入以下完整內容。這個範例刻意採手動觸發，讓每次啟動時機可控；它也沒有預先授予 shell 或寫檔權限。

---
name: todo-review
description: 審查待辦清單專案的程式與目前差異，回報證據和未驗證事項。
disable-model-invocation: true
---
# 待辦專案審查
先確認目前資料夾，讀取 package.json、model.js 與 app.js。
若存在 Git 儲存庫，查看目前差異；不存在時明確說明。
檢查新增、切換完成狀態與刪除是否依照識別碼操作。
檢查使用者輸入是否透過 textContent 等安全方式顯示。
只讀取與分析，不修改檔案，不提交、推送或連接外部服務。
輸出以下三部分：
1. 發現：具體檔名、可重現條件與影響。
2. 驗證：實際執行過的檢查；沒有執行測試就明確標示。
3. 下一步：最多三個按影響排序的建議。

description 應回答「什麼情況使用」，不能只寫「很棒的工具」。步驟則要指出讀什麼、觀察什麼、交付什麼。這裡的只讀要求是流程指引；若需要技術上限制可用工具，仍要查看權限設定與技能欄位的實際作用。

在正確的對話呼叫

從專案根目錄啟動 Claude Code，在輸入框鍵入技能名稱。一般本機 SKILL.md 文字變更支援偵測更新；如果清單沒有刷新，先確認檔案位置與格式，再重新啟動 session。不要為了找不到名稱，立刻把整份檔案複製到多個範圍。

/todo-review

預期 Claude 會載入技能並讀取指定材料，報告應包含 model.js 或 app.js 的具體觀察。只有「技能已建立」的回覆不算完成驗證，因為那可能只是描述檔案存在。請確認真正發生一次呼叫，並把輸出與磁碟內容對照。

若原始專案沒有 Git，報告應說明無法取得 Git 差異，繼續做可行的檔案審查，而不是自行初始化或捏造提交紀錄。若尚未執行測試，也應寫「未執行」，不能把閱讀測試程式當成測試已通過。

分清楚兩個呼叫開關

disable-model-invocation 設為 true，表示不讓 Claude 自動選用，使用者仍可手動呼叫。user-invocable 設為 false，則隱藏使用者斜線入口並阻止手動呼叫，適合只由 Claude 選用的背景知識。兩者的用途不同，別為了「不要自動執行」而關掉手動入口。

目前文件也提醒，手動限定的技能不能直接作為排程自動觸發的技能提示。若之後要做排程，需重新審查觸發條件，不能只把同一斜線名稱塞進排程就認定會執行。

調整內容並再次驗證

把輸出要求加上一欄「證據位置」，重新呼叫技能，確認第二次報告真的引用檔名與可辨認內容。已載入對話的技能指引會留在上下文中，修改磁碟不會回頭改寫舊訊息；測試重大修改時可開新 session，減少舊指引干擾。

不要把整個團隊知識庫塞入同一份檔案。主檔保留決策步驟，長範本與說明放到附屬材料，並在需要時明確指定讀取。參數與材料篇會把此範例改為能指定檔案的版本。

把技能檔與一份實際輸出放在同一次版本審查中，讓別人能看到規則與效果是否一致。輸出使用假資料，並註明這是測試紀錄，避免被誤讀成目前專案的最新狀態。

找不到技能時如何排查

停用練習技能時，把整個 todo-review 資料夾移出 .claude/skills/ 掃描位置並保留備份，再開新 session 確認名稱消失。只改 description 不會等於停用；而已經進入對話的舊指引也不會因為移檔自動消失。

小練習是為報告加入「可重現操作」欄，呼叫兩次並核對輸出差異。完成判準是名稱能找到、步驟真正被套用、結果有檔案證據，而且知道如何移除及恢復。這比累積大量從未驗證的技能更容易長期維護。

準備好練習完整流程時，接著閱讀Skill SOP 工作坊，使用獨立材料進行故障重現與成果驗證。

回 Claude Code 教學總目錄

• AI 工具
• 教學
• Claude Code