Claude Skills 最佳實務 2026 大改版：官方 7 條新規則，讓你的技能不再被忽略（逐條解讀）

2026 年 10 月 1 日，長期經營 agentic 系統主題的 YouTube 頻道 Simon Scrapes（約 10 萬訂閱）發布一支 12 分 48 秒的影片，標題相當直白：《Everything You Know About Skills IS OUTDATED》——「你對 Skills 的所有認知都過時了」。影片上線 6 小時內累積約 2.1 萬次觀看，留言區很快出現同一種困惑：技能檔明明寫得很完整，為什麼代理就是不理它？

影片給的答案不是「模型變笨了」，而是讀取行為的細節：當引用鏈太深時，代理可能用 head -100 這種指令「先看前 100 行」而不是整檔讀完——於是寫在第 100 行之後的規則，等於沒寫。

這篇文章把影片整理的 7 條規則逐條攤開，並對照 Anthropic 官方《Skill authoring best practices》文件原文逐項查核。官方文件才是權威來源，影片的價值在於它把散落各章的規則濃縮成一份可執行的檢查順序。

⚠️ 揭露：Simon Scrapes 的影片說明欄含其社群（Skool）與電子報推廣連結，本文不嵌入這些連結。本文以 Anthropic 官方文件為主要依據，影片僅作為整理框架；文末列出本文方法上的限制。

一、一句話說清楚：為什麼你的規則「被忽略了」

官方文件在「Avoid deeply nested references」一節寫得很明白：

Claude may partially read files when they’re referenced from other referenced files. When encountering nested references, Claude might use commands like head -100 to preview content rather than reading entire files.

翻譯成實務語言：引用再引用（A 檔指向 B 檔、B 檔再指向 C 檔）時，代理很可能只「預覽」而不是讀完。這帶來兩個直接後果：

二、舊建議 vs 新規則：一張表看懂差異

過去社群流傳的「Skills 寫法」多半來自早期教學，官方文件更新後，這些數字與做法已經需要修正：

三、規則 1：超過 100 行的參考檔，開頭一定要有目錄

這是整套新規則的起點，因為它直接對抗 head -100 的行為。官方原文：

For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads.

寫法就是把章節清單放在最前面：

# API Reference

## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples

## Authentication and setup
...

為什麼有效：代理即使只讀前 100 行，也已經知道「這個檔裡還有什麼」，於是能決定要不要繼續讀、或跳到哪一段。目錄本身就是給代理的導航地圖。

四、規則 2：設定「適當的自由度」

影片把它列為第二條，官方文件標題是「Set appropriate degrees of freedom」——依照任務的脆弱度與變異度決定指令要多細：

官方給的比喻很好懂：把代理想成走在一條路上的機器人。

• 兩側都是懸崖的窄橋——只有一條安全路徑，要給明確護欄與精確指令（低自由度，例：資料庫遷移必須依序執行）。
• 毫無障礙的曠野——條條大路通羅馬，給大方向就好，讓代理自己找最佳路線（高自由度，例：程式碼審查）。

換句話說：規則寫太少會亂做，寫太死會綁死。多數「技能不聽話」的案例，其實是自由度設錯了層級。

五、規則 3：先在「每個你會用到的模型」上測

官方文件說得直接：Skills 是加在模型上的補充，效果取決於底層模型，所以要在所有會用到的模型上測。

原文提醒：What works perfectly for Opus might need more detail for Haiku.——對 Opus 剛好的寫法，對 Haiku 可能太簡略。同一份技能要跨模型用，就得寫成「對三者都夠用」的版本。

六、規則 4：引用只留一層，不要嵌套

這條是規則 1 的孿生兄弟。官方明確要求：Keep references one level deep from SKILL.md——所有參考檔都應由 SKILL.md 直接連出。

# ❌ 太深
SKILL.md   → See advanced.md
advanced.md → See details.md
details.md  → 真正的資訊在這裡

# ✅ 一層
SKILL.md
├── 基本用法：寫在 SKILL.md 內
├── 進階功能：See advanced.md
├── API 參考：See reference.md
└── 範例：See examples.md

理由是行為而非美學：嵌套越深，代理越可能用預覽方式讀取，資訊就越容易缺漏。順帶一提，官方也要求檔名要有描述性（form_validation_rules.md 而非 doc2.md），並一律用正斜線（reference/guide.md，不要用 Windows 的反斜線）。

七、規則 5：用「可勾選的檢核清單」帶流程

複雜流程不要只寫編號步驟，官方建議改成代理可以複製到自己的回覆裡逐項打勾的清單：

## PDF form filling workflow

Copy this checklist and check off items as you complete them:

Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)

官方解釋，這份清單同時服務兩個對象：代理知道現在走到哪，人也看得見進度，而且「明確的步驟」能防止代理跳過關鍵驗證。這個模式不需要寫程式也能用——研究彙整、內容審查、法遵檢查都適用。

八、規則 6：留一個「自我修正迴圈」

核心模式只有一句：執行驗證器 → 修錯 → 重複。官方舉了兩個版本：

• 無程式版：以 STYLE_GUIDE.md 當驗證器，代理邊讀邊比對，未通過就修，全部達標才繼續。
• 有程式版：改完 word/document.xml 後立刻跑 python ooxml/scripts/validate.py unpacked_dir/，失敗就修、再驗，驗證通過才打包。

原文對此的評價是：The validation loop catches errors early.（驗證迴圈能提早攔下錯誤。）更進一步的版本是官方的「plan-validate-execute」模式——面對批次操作或高風險操作時，先產出一份結構化的計畫檔（如 changes.json），用腳本驗證計畫，通過後才真正執行。官方列出四個好處：提早發現錯誤、可被機器客觀驗證、計畫階段不動原始檔（可反覆試）、錯誤訊息能精準指向問題。

九、規則 7：依賴要「明講」，不要靠代理猜

最後一條處理的是「跑不起來」的經典原因：

官方給的「自帶說明」寫法值得照抄：

# HTTP requests typically complete within 30 seconds
# Longer timeout accounts for slow connections
REQUEST_TIMEOUT = 30

# Three retries balances reliability vs speed
# Most intermittent failures resolve by the second retry
MAX_RETRIES = 3

另外一條容易被忽略的原則：腳本要「解決問題」而不是「把問題丟回給代理」——檔案不存在就建一個預設檔並印出訊息，而不是讓代理自己看著例外猜。這叫 Solve, don’t defer。

十、發佈前檢核清單

官方文件最後附了一份完整的檢查表，分成三大類：

核心品質

• Description 具體、含關鍵詞
• Description 同時說明「做什麼」與「何時用」
• SKILL.md 本文低於 500 行
• 額外細節已拆到獨立檔案
• 沒有時效性資訊（或收在「舊做法」區塊）
• 全篇術語一致
• 範例具體、不抽象
• 檔案引用只有一層
• 正確使用漸進式揭露
• 工作流程有明確步驟

程式與腳本

• 腳本解決問題，而非把問題丟回代理
• 錯誤處理明確且有用
• 沒有無法解釋的魔術數字
• 所需套件已列出並確認可用
• 腳本有清楚文件
• 沒有 Windows 風格路徑（全部用正斜線）
• 關鍵操作有驗證／確認步驟
• 品質關鍵任務有回饋迴圈

測試

• 至少建立三個評估案例
• 已在 Haiku、Sonnet、Opus 上測試
• 用真實使用情境測過
• 已納入團隊回饋（若適用）

小技巧：官方建議先建評估、再寫文件——先讓代理在沒有技能的情況下跑代表性任務，記錄它具體失敗在哪，然後只寫「補足這些缺口」的最小內容。這能避免寫出一套「解決你想像中問題」的技能。

十一、這不只是 Anthropic 生態的事

值得一提的是，Agent Skills 已經在 2025 年 12 月 18 日由 Anthropic 公開為跨平台開放標準（agentskills.io），SKILL.md 的格式與這些最佳實務因此具備跨工具的參考價值——凡是採用同一種「資料夾＋SKILL.md＋漸進式揭露」架構的代理系統，都會遇到本文提到的 head -100、嵌套引用、自由度設定等相同問題。

這也是為什麼一份看起來「只是寫給 Claude 看的說明文件」，實際上是一門為代理設計資訊架構的功夫：目錄、單層引用、檢核清單、回饋迴圈——這些都是傳統技術寫作早就存在的概念，只是現在讀者換成了代理。

十二、需要保留的懷疑

• 官方文件是建議，不是規格。文中「應該／建議」的語氣是刻意的；超過 500 行、引用兩層不一定會立刻壞掉，只是失敗機率上升。
• head -100 是「可能」而非「保證」。官方原文用 might——這是觀察到的傾向，不是硬性行為；換模型、換上下文長度都可能不同。
• 100 行與 500 行是不同尺度的門檻。100 行是「參考檔要有目錄」的門檻，500 行是「SKILL.md 本文」的建議上限，兩者不要混用。
• 影片是個人頻道的整理，不是官方發布。本文逐條回查官方文件後才採用，但影片若有文件未涵蓋的補充，未經查核者本文不採信。
• 代理商生態變動極快。這份文件本身也可能再改版——建議實作前直接讀一次官方原文。

資料來源

• Skill authoring best practices（Anthropic 官方文件）
• Everything You Know About Skills IS OUTDATED（Simon Scrapes，2026-10-01）
• Equipping agents for the real world with Agent Skills（Anthropic Engineering）
• Agent Skills 開放標準

延伸閱讀

• Anthropic Skills：Claude Code 官方開源代理技能套件
• Claude Skills 教學：把 AI Agent 工作流變成可重用技能
• Agent Skills 完整教學：讓 Claude Code、Cursor 自動遵循工程紀律