我今日本來冇打算挖到咁深。我當時只係想搞清楚，點解同事嘅 Claude Code 設定同我嘅差咁遠——結果答案原來就擺喺一個我幾乎冇留意過嘅資料夾入面。
Claude Code Skills Documentation 講緊乜
"anthropic claude code skills documentation" 呢個詞組喺好多開發者搜尋入面都會出現，我覺得係有原因嘅：skills 呢套系統真係散落喺幾個唔同嘅介面同文件頁面上，要慢慢先砌得出佢哋之間究竟點樣接起嚟。
呢篇文章係基於 Anthropic 嘅官方資料。但我想補上嘅，係單靠官方文件未必完全俾到你嗰一層——一種慢慢長出嚟嘅理解，係由觀察一點點砌返出嚟嘅。
官方文件喺邊度睇
最正統嘅起點係 Anthropic's Claude Code skills reference，佢涵蓋咗完整嘅 skill lifecycle、SKILL.md 格式，同 Claude 會點樣自動發現兼載入 skills。
如果你想理解 skills 放返入更大嘅 agent 圖景入面係咩位置——包括佢同 Projects、MCP、subagents 點樣比較——Anthropic 仲發過一篇幾有用嘅博客：Skills explained: How Skills compares to prompts, Projects, MCP, and subagents。嗰篇幫我睇清楚嘅，唔只係 what，仲有 when。
呢篇文章比官方文件多咗咩
官方文件係準確嘅，結構都好清楚。但佢未必成日捉到嗰啲細微又惱人嘅模式——有時某個 skill 唔觸發，有時又觸發得太闊，又或者你突然發現，原來自己一直將 SKILL.md 同 CLAUDE.md 當成差唔多嘅嘢，但佢哋其實做緊兩份有少少唔同嘅工。
我想喺呢度追住睇嘅，就係嗰啲位。
SKILL.md 格式參考
檔案位置同命名
每個 skill 都要有一個 SKILL.md 檔案，入面分成兩個部分：YAML frontmatter（夾喺 --- 標記之間），話俾 Claude 知幾時應該用呢個 skill；以及 markdown 正文，寫 Claude 喺 skill 被調用時要跟住做嘅指令。
喺 Claude Code 入面，skills 可以放喺 Project 內嘅 .claude/skills/<skill-name>/SKILL.md，亦都可以放喺使用者全域嘅 ~/.claude/skills/<skill-name>/SKILL.md。資料夾名同 frontmatter 入面嘅 name 欄位會變成斜線指令，所以如果 .claude/skills/explain-code/SKILL.md 入面寫咗 name: explain-code，就會建立 /explain-code 呢個指令。
定義喺 .claude/skills/ 下面、而且係透過 --add-dir 加入嘅 skills，會自動載入，live change detection 亦都會跟得上，所以你甚至可以喺會話途中直接改佢哋，唔使重啟。呢點真係令我有少少意外——我原本以為要重新開過。
支援邊啲指令類型
Skills 透過指令同程式碼，幫 Claude 補上一啲新能力。實際上，markdown 正文幾乎可以放任何 Claude 讀得明、推理到嘅嘢：逐步流程、風格規則、輸出模板、領域術語、參考內容，同埋內嵌示例。寫指令時，最好用祈使式。
官方 skill-creator 文件入面有個細節，我覺得幾值得記低：description 欄位先係最主要嘅觸發機制——你要同時寫清楚呢個 skill 做乜，同埋乜情境之下應該用佢。所有「幾時要用」嘅資訊，都應該放喺呢度，而唔係正文。
格式語法同結構
最基本可用嘅 SKILL.md 會係咁：
---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---
# My Skill Name
[Instructions Claude follows when this skill is active]
啟動時，agent 會先將每個已安裝 skill 嘅 name 同 description 預載入 system prompt。呢份 metadata 就係漸進式揭露嘅第一層：先俾 Claude 啱啱好嘅資訊，等佢知道幾時應該用邊個 skill，而唔係一開始就將全部內容塞爆上下文。
Skills 亦都可以帶 supporting files——參考文件、scripts、素材——放喺子目錄入面。將填表說明之類嘅內容拆去獨立檔案之後，skill 作者就可以令核心 skill 保持精簡，假設 Claude 只會喺真係有需要時先去讀嗰個檔案。
字數同長度限制
SKILL.md 本身冇硬性字數上限。一個 skill 能夠打包入去嘅上下文，理論上幾乎冇邊界，因為漸進式揭露代表 Claude 只會喺需要時先載入額外檔案。不過實務上，如果你將 SKILL.md 聚焦喺核心指令——控制喺 500 行以內——上下文膨脹就會細好多。更詳細嘅內容，最好搬去 references/，再喺正文度連過去。
Claude Code Skills 可以指揮乜
風格同格式偏好
Skills 好適合編碼輸出標準：報告應該點樣排、語氣用邊種、要帶咩標題。你完全可以整一個品牌規範 skill，將公司嘅配色、字體規則同版面要求都放入去。咁 Claude 之後做簡報或者文件時，就會自動跟呢啲標準，唔使你每次再講一次。
領域專用知識
呢度大概係 skills 喺日常工作入面最有用嘅地方。凡係 Claude 靠通用訓練唔可能知道、但又一定要知道嘅領域資訊——例如你哋內部嘅 API 慣例、專有資料格式、公司自己嘅 workflow——都可以打包做成一個 skill，之後重複用返，唔使每個 prompt 都再講。
工具使用偏好
Skills 仲可以指定 Claude 應該優先用邊啲工具、按咩次序用、喺咩條件下用。當 Claude 調用一個 skill 時，系統會行一條幾簡單嘅流程：先載入 SKILL.md，再將佢展開成更細緻嘅指令，將嗰啲指令當成新嘅 user messages 注入對話上下文，修改執行上下文（可用工具、模型選擇），之後喺呢個被增強咗嘅環境度繼續對話。
輸出結構要求
你亦都可以喺 skill 入面定義非常精確嘅輸出模板。Anthropic skills GitHub repository 入面有唔少例子，示範點樣將 Claude 鎖定喺明確格式上——報告結構、commit message 模式、測試檔案版型。
Skills 做唔到乜
執行程式碼
SKILL.md 係指令內容，唔係可執行程式碼。佢話俾 Claude 知 點樣 去處理任務；佢自己唔會跑任何嘢。放喺 skill 嘅 /scripts 目錄入面嘅腳本，可以由 Claude 喺任務執行期間調用，但 SKILL.md 本身就只係文字。
從錯誤入面自己學
Custom Skills 唔會喺唔同 surface 之間自動同步。你上傳到一個 surface 嘅 skill，唔會自動喺其他 surface 上可用。再根本少少講，skill 亦都唔會因為過去某次會話發生咗乜而自己更新。只要你唔改佢，入面嘅指令就係靜態嘅。我一直提醒自己要記住呢點——skill 係一份被定格咗嘅經驗，唔係一個學習閉環。
自動喺 agents 或 sessions 之間共享
Skills 嘅作用域，取決於佢哋裝喺邊個 surface。你喺 Claude Code 建嘅 skill，唔會自動出現喺 Claude.ai 或 API 入面，除非你另外再上傳一次。
Skills、System Prompts、Project Rules 同 Memory 有咩分別
我喺呢度花咗最多時間，亦都最易俾自己搞亂。到而家，我大概係咁理解佢哋嘅分別：
| 機制 | 做乜 | 範圍 | 會唔會跨 session 保留？ |
|---|---|---|---|
| SKILL.md | 按需要載入嘅領域專用指令 | Project 或 user-global | 會（檔案式） |
| CLAUDE.md | 一直載入嘅 Project 上下文同慣例 | Project 級 | 會（檔案式） |
| System prompt | 設定模型嘅基礎行為 | API/SDK 級 | 只有次次都設定先會 |
| Projects (claude.ai) | 為持續進行中嘅工作保存長期上下文 | Claude.ai workspace | 會 |
| Memory | 跨對話回想偏好 | 使用者級 | 會（如果有開） |
Skills 係教 Claude how 去做一件事。一個 Project 可能裝住你成個產品發佈嘅背景，而一個 skill 則可以教 Claude 你團隊嘅寫作標準，或者 code review 流程。
CLAUDE.md 係 Claude 每次開始對話都會讀嘅特殊檔案。你可以喺入面放 Bash commands、程式碼風格同 workflow 規則。佢提供嘅，係 Claude 單靠程式碼本身推唔出嚟嘅持久上下文。佢同 SKILL.md 最關鍵嘅分別係：CLAUDE.md 會 always 載入；skills 只會喺 when relevant 嘅時候載入。
Claude Code 嘅 system prompt 本身已經有大約 50 條獨立指令。視乎模型而定，呢個數字差唔多已經用咗 agent 能夠穩定遵循指令總量嘅三分之一——仲未計 rules、plugins、skills 或 user messages。呢個數字一直留喺我腦入面。佢會改變你點樣諗每一層到底應該放幾多內容。
FAQ
1 官方嘅 Claude Code Skills documentation 喺邊度？
最主要嘅參考係 Claude Code skills documentation。如果你想睇更大範圍嘅 Agent Skills 標準——包括 pre-built skills 同 custom skills 喺 Claude.ai 同 API 入面點樣運作——可以睇 Anthropic 平台文件入面嘅 Agent Skills overview。
2 SKILL.md 用嘅係咩格式？
SKILL.md 係一個帶 YAML frontmatter 嘅 Markdown 檔案。frontmatter 必須包含兩個欄位——name 同 description——Claude 會喺 session 啟動時讀取佢哋，藉此判斷幾時應該載入呢個 skill。Markdown 正文入面放嘅，就係 Claude 喺 skill 被調用時真係會跟嘅指令。進階少少嘅執行控制，仲可以用 context 同 agent 呢啲可選欄位。
3 SKILL.md 檔案可以有幾長？
冇強制嘅硬上限。令 Agent Skills 同時保持靈活同可擴展嘅核心設計原則，就係漸進式揭露——skills 令 Claude 只會喺需要時先載入資訊，所以一個 skill 可以打包入去嘅上下文，理論上幾乎冇邊界。即使係咁，大多數更實用嘅建議仍然係：將核心 SKILL.md 控制喺 500 行以內，把更細嘅內容拆去 references/。
我到而家都仲唔敢話，自己已經將呢度所有邊角情況都畫清楚。skill 嘅觸發行為——Claude 幾時會覺得一個 skill 相關，幾時又唔會——其實比格式文件俾人嘅印象更難預測。Claude 有時會對 skill 「觸發不足」——明明有用，佢都未必會用。寫 description 欄位時，呢點真係值得記住。
我會繼續睇住呢件事之後點樣沉澱落去。
