Claude Code 工程實踐揭秘：Anthropic 內部 Skills 設計的九類框架與編寫最佳實踐

作者：AI 啓蒙小夥伴
日期：2026年6月5日 上午7:50
來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點 高亮

Anthropic 工程團隊總結 Claude Code Skills 嘅九類框架同編寫最佳實踐，核心係將組織隱性知識封裝成可複用文件夾，而唔係單一提示詞。

整理版摘要

呢篇文章出自 Anthropic 官方博客，由 Claude Code 團隊分享內部經驗。佢哋想解決嘅問題係：點樣將團隊累積嘅部落知識（tribal knowledge）結構化咁注入 AI 工作流，令 Claude Code 唔只係寫到 code，仲可以正確調用內部 API、跟足團隊規範、避開已知陷阱。整體結論係：Skill 嘅本質係一個文件夾，透過文件系統實現上下文工程，配合九類分類框架同四大編寫原則，先至可以將 AI 輔助編程提升到組織級別。

文章首先釐清一個關鍵認知：Skill 唔係 prompt，而係一個文件夾。設計哲學包括單一職責（每個 Skill 乾淨咁落入一個類別）、漸進式披露（用文件結構分層提供資訊）、同持續迭代（根據實際失敗點不斷改進）。Anthropic 團隊將內部過百個 Skill 歸納成 9 個類別，涵蓋 Library 引用、Product Verification、Data Analysis、Business Automation 等範疇。特別值得留意係 Product Verification 類別被認為對 Claude 輸出質量影響最大、最可量化，值得投入一週時間專門打磨。

編寫 Skill 有四大最佳實踐：唔好講廢話（Claude 已經識寫 code，要提供特殊知識）、建立陷阱章節（累積實際失敗案例）、利用文件系統做漸進式披露（用 SKILL.md 做樞紐分派到具體文件）、避免過度指…

  • Skill 本質係文件夾而唔係提示詞，用嚟封裝組織嘅部落知識，透過文件系統做上下文工程。
  • 九大分類框架幫助團隊系統化識別知識缺口，其中 Product Verification 對輸出質量影響最大。
  • 最佳實踐：避開重述基礎能力、聚焦陷阱章節、用漸進式披露、避免過度指令化。
  • 動態配置技巧（`!` 語法）實現輕量狀態管理，令 Skill 首次使用時可互動設定。
  • AI 編程競爭正由模型能力轉向組織知識工程，Skill 係將隱性知識轉為 machine-readable context 嘅基礎設施。
整理重點

核心認知：Skill 係文件夾，唔係 prompt

呢篇文章開宗明義就話：Skill 唔係一個 prompt，而係一個文件夾。佢代表將組織內嘅隱性經驗（tribal knowledge）封裝做可複用 AI 上下文嘅工程實踐。

設計哲學包括：單一職責（最好嘅 skill 乾淨咁落入一個類別）、漸進式披露（透過文件系統結構實現上下文工程）、持續迭代（跟住實際使用中嘅失敗點不斷進化）。

呢個認知好重要，因為佢改變咗我哋對 AI 輔助工具嘅設計思維：唔係寫一條超長 prompt，而係管理一個文件夾。

整理重點

九大分類框架：系統化識別知識缺口

Anthropic 團隊將內部所有 skill 歸納為 9 個類別，呢個框架本身好有參考價值，以下係各類別嘅核心功能同典型示例：

  • Library & API Reference：內部庫、CLI、SDK 嘅正確用法同陷阱，例如 billing-lib、platform-cli。
  • Product Verification：驅動運行中產品做端到端驗證，例如 signup-driver、checkout-verifier。團隊特別強調呢個類別對 Claude 輸出質量影響最大、最可量化。
  • Data & Analysis：連接數據棧同監控體系，例如 funnel-query、grafana、datadog。
  • Business Automation：多工具工作流一鍵化，例如 standup-post、weekly-recap。
  • Scaffolding & Templates：框架正確嘅程式碼腳手架，例如 new-app、new-migration。
  • Code Quality & Review：程式碼質量方法論，例如 adversarial-review、code-style。
  • CI/CD & Deployment：安全咁提交、推送、部署，例如 babysit-pr、deploy-service。
  • Incident Runbooks：症狀→調查→報告嘅故障處理，例如 oncall-runner、queue-debug。
整理重點

編寫 Skill 嘅四大最佳實踐

  1. 1 唔好講廢話：Claude 已經識編程、識讀 code。Skill 嘅價值係提供特殊知識，幫佢推出默認思維模式。例如前端設計 skill 唔係教點寫 CSS，而係通過迭代訓練「設計品味」，避免 Inter 字體同紫色漸變等陳詞濫調。
  2. 2 建立陷阱章節：呢個係最高信號價值嘅內容。Gotchas 應來自 Claude 實際使用嘅失敗點，持續累積。例如「subscriptions 表係 append-only，要揾 version 最高嘅行，唔係 created_at 最新嘅」。
  3. 3 利用文件系統做漸進式披露：Skill 係文件夾，用 SKILL.md 做樞紐進行調度，具體工作由 spoke 文件完成。例如 queue-debugging/SKILL.md 得 30 行，透過症狀匹配表分派到 stuck-jobs.md、dead-letters.md 等文件。
  4. 4 避免過度指令化：Skill 應提供資訊而非僵化流程。對比示例：唔好寫「Step 1 執行 git log → Step 2 執行 git cherry-pick → Step 3...」，而係「Cherry-pick the commit onto a clean branch. Resolve conflicts preserving intent. If it can't land cleanly, explain why.」
整理重點

動態配置與深層啟示

文章展示咗一個精妙嘅工程技巧：喺 standup-post skill 入面，利用 !`command` 語法喺 Claude 讀取 prompt 前執行 shell 命令，實現動態配置。

動態配置示例 bash 
!`cat ${CLAUDE_SKILL_DIR}/config.json 2>/dev/null || echo "NOT_CONFIGURED"`

呢個技巧實現咗輕量級 skill 狀態管理：第一次用時詢問用戶 Slack 頻道同格式偏好，寫入 config.json；之後直接複用。

深層啟示：AI coding assistant 嘅競爭正由模型能力轉向組織知識工程。Skill 本質上係將 tribal knowledge 轉化為 machine-readable context 嘅基礎設施，而文件系統作為「上下文工程」嘅載體，比單一 prompt 更接近軟件工程本質——模組化、可維護、可演進。

總括嚟講，呢篇文章提供咗一套可操作嘅框架同原則，幫助團隊從「用 AI 寫 code」進階到「用 AI 正確地、符合組織規範地、可驗證地寫 code」。

Claude 官方網誌

呢篇網誌係 Anthropic 工程團隊內部實踐嘅經驗總結，主題圍繞 Claude Code 中 "Skills" 嘅設計、分類同最佳實踐。係一份工程組織點樣將隱性知識顯性化、結構化咁注入 AI 工作流程嘅方法論文檔。

圖片

Lessons from building Claude Code: How we use skills

What we learned building and scaling hundreds of skills internally at Anthropic.

https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills

Skills 嘅本質：由「提示詞」變「組織知識庫」

文章首先建立咗一個關鍵認知：Skill 唔係一個 prompt，佢係一個資料夾。佢代表一種將組織內部嘅隱性經驗（tribal knowledge）封裝成可重用 AI 上下文嘅工程實踐。

核心設計哲學：

  • 單一職責：最好嘅 skill 可以乾淨咁歸入一個類別；試圖涵蓋多個領域嘅 skill 會令 agent 混淆
  • 漸進式披露：透過檔案系統結構實現上下文工程，而唔係將所有資訊塞入一個檔案
  • 持續迭代：skill 係活嘅文件，會隨住實際使用中嘅失敗點不斷進化

九大 Skill 分類體系

Anthropic 團隊將內部所有 skill 歸納成 9 個類別，呢個 framework 本身有極高參考價值：

類別核心功能典型例子
Library & API Reference內部 Library/CLI/SDK 嘅正確用法同陷阱billing-lib, platform-cli
Product Verification驅動運行中嘅產品做端到端驗證signup-driver, checkout-verifier
Data & Analysis連接數據棧同監控體系funnel-query, grafana, datadog
Business Automation多工具工作流程一鍵化standup-post, weekly-recap
Scaffolding & Templates框架正確嘅程式碼腳手架new-app, new-migration
Code Quality & Review程式碼質量方法論adversarial-review, code-style
CI/CD & Deployment安全咁提交、推送、部署babysit-pr, deploy-service
Incident Runbooks症狀→調查→報告嘅故障處理oncall-runner, queue-debug
Infrastructure Ops帶安全門嘅運維操作orphans, cost-investigation

值得注意嘅洞察：

  • Product Verification 被特別強調為「對 Claude 輸出質量影響最大、最可量化嘅 skill 類別」，團隊認為值得投入一個工程師一星期時間專門打磨
  • Infrastructure Ops 涉及破壞性操作，所以強調「safety-gated」（帶安全門）嘅設計，體現對 AI 自主執行風險嘅操作性思考

編寫 Skill 嘅四大最佳實踐

1. Don't state the obvious（唔好講一啲顯而易見嘅嘢）

Claude 已經識寫程式、識睇 code。Skill 嘅價值唔在於重複基本能力，而在於提供能夠將佢推出預設思維模式嘅特殊知識。

正面案例：前端設計 skill 唔係教 Claude 點樣寫 CSS，而係透過迭代訓練佢嘅「設計品味」，明確避免 Inter 字體同紫色漸變呢啲陳腔濫調。

2. Build a gotchas section（建立「陷阱」章節）

呢個係文章強調最高信號價值嘅內容。Gotchas 應該嚟自 Claude 實際使用中嘅失敗點，持續累積。

示例：

  • "subscriptions 「表係 append-only，你要揾嘅係 version 最高嘅行，唔係 created_at 最新嗰個」
  • 「Staging 環境就算 Stripe webhook 冇實際處理都會返回 200，要查 payment_events 睇真實狀態」

3. Use the file system and progressive disclosure（用檔案系統做到漸進式披露）

Skill 係一個資料夾，而唔係一個 markdown 檔案。透過 SKILL.md 作為 hub（樞紐）做調度，具體工作由 spoke（輻條）檔案完成。

示例：queue-debugging/SKILL.md 得 30 行，透過症狀匹配表分派去 stuck-jobs.md、dead-letters.md 等具體檔案。

4. Avoid railroading Claude（避免過度指令化）

Skill 應該提供資訊而唔係 rigid procedure（僵化流程）。對比例子好清楚：

  • 過度指令化：Step 1 行 git log → Step 2 行 git cherry-pick → Step 3...
  • 更好嘅做法：「Cherry-pick the commit onto a clean branch. Resolve conflicts preserving intent. If it can't land cleanly, explain why.」

一個好巧妙嘅工程技巧：動態配置

文章展示咗 standup-post skill 入面利用 !...` 語法喺 Claude 讀取 prompt 之前執行 shell 命令嘅技巧：

!`cat ${CLAUDE_SKILL_DIR}/config.json 2>/dev/null || echo "NOT_CONFIGURED"`

咁樣就做到首次使用時嘅互動式配置：如果未配置，會問用戶 Slack 頻道同格式偏好，然後寫入 config.json；之後直接重用。呢個係一種輕量級嘅 skill 狀態管理機制。

深層啟示：AI 時代嘅「組織知識管理」

呢篇文章嘅深層價值在於佢揭示咗一個趨勢：AI coding assistant 嘅競爭正喺度由模型能力轉向組織知識工程。

  • 唔係「AI 寫得幾多 code」，而係「AI 能夠正確調用幾多內部 API、跟到幾多團隊規範、避開幾多已知陷阱」
  • Skill 本質上係將組織嘅 tribal knowledge（部落知識）轉化為 machine-readable context 嘅基礎設施
  • 檔案系統作為「上下文工程」嘅載體，比起單一個 prompt 更加接近軟件工程嘅本質——模組化、可維護、可演進

總結

呢篇網誌係一份高質素嘅工程實踐文檔，冇空洞嘅理論，全部嚟自 Anthropic 內部 Claude Code 團隊嘅實際經驗。佢嘅核心貢獻係：

  1. 提供咗一套可操作嘅 skill 分類框架（9 大類別），幫助團隊系統化咁識別知識缺口
  2. 明確咗 skill 編寫嘅反模式同正模式（避免重複基本能力、聚焦 gotchas、避免過度指令化）
  3. 展示咗檔案系統作為 AI 上下文工程基礎設施嘅設計思路

對於正在構建或者優化 AI 編程工作流程嘅團隊，呢篇文章提供咗由「用 AI 寫 code」到「用 AI 正確咁、符合組織規範咁、可驗證咁寫 code」嘅進階路徑。

相關資源推薦

OpenAI Codex 團隊分享 Prompt，深挖你反覆做緊嘅嘢沉澱成 Skills、Subagent 同 Automation（附 Claude Code / Cursor 落地指南）

一齊睇下 Cursor 團隊內部最常用嘅 Skills

點樣寫好 Skill？OpenAI、Anthropic 同 Sentry 嘅 Skill-Creator 對比結合：由快速原型到工程化工作流程持續迭代

Claude 官方博客

這篇博客是 Anthropic 工程團隊內部實踐的經驗總結，主題圍繞 Claude Code 中 "Skills" 的設計、分類與最佳實踐。是一份工程組織如何將隱性知識顯性化、結構化地注入 AI 工作流的方法論文檔。

圖片

Lessons from building Claude Code: How we use skills

What we learned building and scaling hundreds of skills internally at Anthropic.

https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills

Skills 的本質：從"提示詞"到"組織知識庫"

文章首先建立了一個關鍵認知：Skill 不是一個 prompt，它是一個文件夾。它代表一種將組織內的隱性經驗（tribal knowledge）封裝為可複用 AI 上下文的工程實踐。

核心設計哲學：

  • 單一職責：最好的 skill  cleanly fit into one category（乾淨地落入一個類別）；試圖覆蓋多個領域的 skill 會讓 agent 困惑
  • 漸進式披露：通過文件系統結構實現上下文工程（context engineering），而非把所有信息塞進一個文件
  • 持續迭代：skill 是活的文檔，隨實際使用中的失敗點不斷進化

九大 Skill 分類體系

Anthropic 團隊將內部所有 skill 歸納為 9 個類別，這個框架本身具有很強的參考價值：

類別核心功能典型示例
Library & API Reference內部庫/CLI/SDK 的正確用法與陷阱billing-lib, platform-cli
Product Verification驅動運行中的產品進行端到端驗證signup-driver, checkout-verifier
Data & Analysis連接數據棧與監控體系funnel-query, grafana, datadog
Business Automation多工具工作流一鍵化standup-post, weekly-recap
Scaffolding & Templates框架正確的代碼腳手架new-app, new-migration
Code Quality & Review代碼質量方法論adversarial-review, code-style
CI/CD & Deployment安全地提交、推送、部署babysit-pr, deploy-service
Incident Runbooks症狀→調查→報告的故障處理oncall-runner, queue-debug
Infrastructure Ops帶安全門的運維操作orphans, cost-investigation

值得注意的洞察：

  • Product Verification 被特別強調為"對 Claude 輸出質量影響最大、最可量化的 skill 類別"，團隊認為值得投入一名工程師一週時間專門打磨
  • Infrastructure Ops 涉及破壞性操作，因此強調"safety-gated"（帶安全門）的設計，體現對 AI 自主執行風險的操作性思考

編寫 Skill 的四大最佳實踐

1. Don't state the obvious（不要陳述顯而易見的內容）

Claude 已經會編程、會讀代碼。Skill 的價值不在於重述基礎能力，而在於提供能將其推出默認思維模式的特殊知識。

正面案例：前端設計 skill 不是教 Claude 怎麼寫 CSS，而是通過迭代訓練其"設計品味"，明確避免 Inter 字體和紫色漸變等陳詞濫調。

2. Build a gotchas section（建立"陷阱"章節）

這是文章強調的最高信號價值內容。Gotchas 應來自 Claude 實際使用中的失敗點，持續積累。

示例：

  • "subscriptions 表是 append-only 的，你要找的是 version 最高的行，不是 created_at 最新的"
  • "Staging 環境即使 Stripe webhook 沒實際處理也會返回 200，要查 payment_events 看真實狀態"

3. Use the file system and progressive disclosure（利用文件系統實現漸進式披露）

Skill 是一個文件夾，而非單個 markdown 文件。通過 SKILL.md 作為 hub（樞紐）進行調度，具體工作由 spoke（輻條）文件完成。

示例：queue-debugging/SKILL.md 僅 30 行，通過症狀匹配表分派到 stuck-jobs.md、dead-letters.md 等具體文件。

4. Avoid railroading Claude（避免過度指令化）

Skill 應提供信息而非 rigid procedure（僵化流程）。對比示例清晰：

  • 過度指令化：Step 1 運行 git log → Step 2 運行 git cherry-pick → Step 3...
  • 更好的方式："Cherry-pick the commit onto a clean branch. Resolve conflicts preserving intent. If it can't land cleanly, explain why."

一個精妙的工程技巧：動態配置

文章展示了 standup-post skill 中利用 !...`` 語法在 Claude 讀取 prompt 前執行 shell 命令的技巧：

!`cat ${CLAUDE_SKILL_DIR}/config.json 2>/dev/null || echo "NOT_CONFIGURED"`

這實現了首次使用時的交互式配置：如果未配置，詢問用戶 Slack 頻道和格式偏好，然後寫入 config.json；後續直接複用。這是一種輕量級的 skill 狀態管理機制。

深層啓示：AI 時代的"組織知識管理"

這篇文章的深層價值在於它揭示了一個趨勢：AI coding assistant 的競爭正在從模型能力轉向組織知識工程。

  • 不是"AI 能寫多少代碼"，而是"AI 能正確調用多少內部 API、遵循多少團隊規範、避免多少已知陷阱"
  • Skill 本質上是將組織的 tribal knowledge（部落知識）轉化為 machine-readable context 的基礎設施
  • 文件系統作為"上下文工程"的載體，比單個 prompt 更接近軟件工程的本質——模塊化、可維護、可演進

總結

這篇博客是一份高質量的工程實踐文檔，沒有空洞的理論，全部來自 Anthropic 內部 Claude Code 團隊的實際經驗。它的核心貢獻在於：

  1. 提供了一套可操作的 skill 分類框架（9 大類別），幫助團隊系統化地識別知識缺口
  2. 明確了 skill 編寫的反模式與正模式（避免重述基礎能力、聚焦 gotchas、避免過度指令化）
  3. 展示了文件系統作為 AI 上下文工程基礎設施的設計思路

對於正在構建或優化 AI 編程工作流的團隊，這篇文章提供了從"用 AI 寫代碼"到"用 AI 正確地、符合組織規範地、可驗證地寫代碼"的進階路徑。

相關資源推薦

OpenAI Codex 團隊分享 Prompt，深挖你反覆在做的事沉澱成 Skills、Subagent 和 Automation（附 Claude Code / Cursor 落地指南）

一起看看 Cursor 團隊內部最常用的 Skills

怎麼寫好 Skill ？OpenAI、Anthropic 與 Sentry 的 Skill-Creator 對比結合：從快速原型到工程化工作流持續迭代