Skills 是什么

在 Claude Code 的語(yǔ)境里，Skill 不是一個(gè)內(nèi)置功能，而是一套自定義擴(kuò)展機(jī)制。

它的本質(zhì)是：把針對(duì)特定任務(wù)的專業(yè)知識(shí)打包成文件，讓 Claude Code 在遇到相應(yīng)場(chǎng)景時(shí)能夠調(diào)用這套知識(shí)，而不是每次都重新描述。

這和 CLAUDE.md 不同。CLAUDE.md 是項(xiàng)目級(jí)上下文，回答的是"這個(gè)項(xiàng)目是什么"；Skill 是任務(wù)級(jí)指令，回答的是"這類任務(wù)應(yīng)該怎么做"。

從官方源碼看，Skills 的文件結(jié)構(gòu)非常清晰：

skill-name/
├── SKILL.md ? ? ? ? ? ? ?← 必須文件，YAML frontmatter + 核心指令
├── references/ ? ? ? ? ? ← 可選，參考文檔，按需加載
├── examples/ ? ? ? ? ? ? ← 可選，工作示例
└── scripts/ ? ? ? ? ? ? ← 可選，可執(zhí)行腳本

Claude Code 啟動(dòng)時(shí)會(huì)掃描 skills/ 目錄，把每個(gè)子目錄里的 SKILL.md 的 name 和 description 加載進(jìn)上下文。當(dāng)用戶的描述觸發(fā)了某個(gè) description，Claude 會(huì)把對(duì)應(yīng)的 SKILL.md 全文讀入，然后按照里面的指令執(zhí)行。

為什么需要 Skills

三個(gè)場(chǎng)景能說(shuō)清楚：

第一，團(tuán)隊(duì)知識(shí)傳承。

你團(tuán)隊(duì)里最好的工程師，他的代碼審查方式、安全掃描邏輯、部署規(guī)范，都是靠多年經(jīng)驗(yàn)積累的。如果只靠口口相傳，每次換人都要重新教。有了 Skill，這些經(jīng)驗(yàn)可以固化成文件，新工程師加上項(xiàng)目 CLAUDE.md，AI 就能用團(tuán)隊(duì)的標(biāo)準(zhǔn)工作。

第二，復(fù)雜任務(wù)的決策框架。

一段 prompt 只能給出一個(gè)答案，一個(gè) Skill 可以給出一個(gè)決策樹(shù)。Claude 遇到不同情況，應(yīng)該走哪條分支，輸出什么，都有明確的規(guī)范，而不是每次生成一段看似合理但不一致的內(nèi)容。

第三，反復(fù)重寫(xiě)的確定性任務(wù)。

有些任務(wù)每次都要重新寫(xiě)差不多的代碼，比如每次新建組件都要搭腳手架、每次做代碼遷移都要處理同一套模式。把這些任務(wù)的"正確做法"寫(xiě)成 Skill，Claude 每次都能用最優(yōu)方式執(zhí)行，不會(huì)每次都從零推理。

Skills 的真實(shí)結(jié)構(gòu)：從官方源碼看設(shè)計(jì)

SKILL.md 的 frontmatter

官方 frontend-design 插件的 Skill 文件是這個(gè)樣子的：

---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications.
---
# Frontend Design Guidance
## Design Thinking
Before coding, understand the context and commit to a BOLD aesthetic direction...
## Technical Requirements
Implement production-grade code that is...

frontmatter 里只有三個(gè)字段有實(shí)際作用：

其中 description 是整個(gè) Skill 最重要的字段。官方 plugin-dev 插件的方法論明確指出：description 的質(zhì)量直接決定 Skill 能不能被正確觸發(fā)。

官方推薦的 description 寫(xiě)法是第三人稱 + 具體觸發(fā)短語(yǔ)：

# 正確示范
description:?This?skill?should?be?used?when?the?user?asks?to?"create a hook",?"add a PreToolUse hook",?"validate tool use"...
# 錯(cuò)誤示范
description:?Provides?guidance?for?working?with?hooks.? ?# 模糊，沒(méi)有觸發(fā)短語(yǔ)
description:?Load?this?skill?when?user?asks...? ? ? ? ?# 第二人稱

正文：不是步驟清單，是決策框架

官方 frontend-design Skill 的正文是這樣一個(gè)結(jié)構(gòu)：

## Design Thinking
- Purpose: 這個(gè)界面解決什么問(wèn)題？
- Tone: 選擇一個(gè)設(shè)計(jì)方向（極簡(jiǎn)、復(fù)古、奢華……）
- Constraints: 技術(shù)約束是什么？
- Differentiation: 什么讓它令人印象深刻？
## Frontend Aesthetics Guidelines
- Typography: 字體選擇
- Color & Theme: 配色體系
- Motion: 動(dòng)效
- Spatial Composition: 空間布局

這給 Claude 的是一套思考框架，不是一串執(zhí)行步驟。Claude 在這個(gè)框架內(nèi)自主判斷每一步怎么做，而不是機(jī)械地讀指令。

官方 Skill Development 方法論里專門(mén)強(qiáng)調(diào)了這一點(diǎn)：正文應(yīng)該用祈使句/不定式（verb-first），而不是第二人稱。

# 正確
To create a hook, define the event type.
Configure the MCP server with authentication.
Validate settings before use.
# 錯(cuò)誤
You should create a hook by defining the event type.
You need to configure the MCP server.

漸進(jìn)披露：三層加載機(jī)制

這是 Skills 系統(tǒng)最核心的設(shè)計(jì)思想，來(lái)自官方 Skill Development 方法論。

Claude Code 對(duì) Skill 的加載分為三個(gè)層級(jí)：

層級(jí)一：元數(shù)據(jù)（name + description）
? → 始終加載，約 100 詞，占用最少上下文
層級(jí)二：SKILL.md 正文
? → Skill 被觸發(fā)時(shí)加載，目標(biāo) 1500-2000 詞，上限 5000 詞
層級(jí)三：references/ + examples/ + scripts/
? → 按需加載，加載時(shí)機(jī)由 Claude 判斷，無(wú)上限

這套機(jī)制解決了一個(gè)核心矛盾：大模型上下文有限，但專業(yè)任務(wù)需要大量細(xì)節(jié)。漸進(jìn)披露讓 Claude 只在真正需要的時(shí)候才加載詳細(xì)內(nèi)容，保持上下文高效運(yùn)轉(zhuǎn)。

具體怎么分工：

• SKILL.md 放什么：核心概念、關(guān)鍵流程、快速參考、常用模式
• references/ 放什么：詳細(xì)文檔、API 參考、模式大全
• scripts/ 放什么：驗(yàn)證工具、測(cè)試腳本、自動(dòng)化腳本（可執(zhí)行，不占上下文）
• examples/ 放什么：完整的可運(yùn)行示例，用戶可直接復(fù)制使用

官方插件體系：14 個(gè)真實(shí)參考案例

anthropics/claude-code 倉(cāng)庫(kù)的 plugins/ 目錄包含了 14 個(gè)官方插件，每個(gè)都是 Skills 的真實(shí)實(shí)現(xiàn)案例。

plugin-dev：系統(tǒng)級(jí)的 Skill 創(chuàng)建方法論

plugin-dev 插件的 skill-development 子目錄完整展示了如何創(chuàng)建一個(gè) Skill，六步組織：

Step 1：理解 Skill 的具體使用場(chǎng)景。 從真實(shí)案例出發(fā)，找到 3-5 個(gè)這個(gè) Skill 會(huì)被用到的具體場(chǎng)景，然后圍繞這些場(chǎng)景設(shè)計(jì)指令。

Step 2：規(guī)劃 Skill 的資源結(jié)構(gòu)。 scripts/ 處理重復(fù)性腳本任務(wù)，references/ 處理需要按需查閱的文檔，assets/ 處理模板和輸出文件。

Step 3：創(chuàng)建目錄結(jié)構(gòu)。 標(biāo)準(zhǔn)結(jié)構(gòu)確保 Claude 能夠正確發(fā)現(xiàn)和加載 Skill。

Step 4：編寫(xiě) SKILL.md。 核心原則：description 要用第三人稱 + 觸發(fā)短語(yǔ)，正文用祈使句，控制在 1500-2000 詞，詳細(xì)內(nèi)容移到 references/。

Step 5：驗(yàn)證與測(cè)試。 用 skill-reviewer agent 做自動(dòng)檢查，對(duì)照驗(yàn)證清單逐項(xiàng)審查。

Step 6：迭代改進(jìn)。 在實(shí)際使用中發(fā)現(xiàn) SKILL.md 哪里不夠精準(zhǔn)，哪里容易觸發(fā)但輸出質(zhì)量不穩(wěn)定，持續(xù)優(yōu)化。

hookify：專業(yè)領(lǐng)域的深度 Skill

hookify 插件演示了專業(yè)領(lǐng)域 Skill 的典型寫(xiě)法，它的 description 包含了 9 個(gè)具體觸發(fā)短語(yǔ)：

description:?This?skill?should?be?used?when?the?user?asks?to?"create a hook",
"add a PreToolUse hook",?"validate tool use",?"implement prompt-based hooks",
"${CLAUDE_PLUGIN_ROOT}",?"block dangerous commands",?or?mentions?hook?events.

觸發(fā)短語(yǔ)寫(xiě)得越具體，Claude 越能準(zhǔn)確判斷什么時(shí)候該調(diào)用這個(gè) Skill。

agent-development：多組件協(xié)同的 Skill

agent-development Skill 展示了 Skill 如何和其他組件（agents、commands）協(xié)同工作，Skill 和 scripts/ 的分工很清楚：

• SKILL.md：什么時(shí)候創(chuàng)建 agent、創(chuàng)建后如何使用
• validate-agent.sh：如何驗(yàn)證 agent 配置是否正確

前者是知識(shí)，后者是確定性操作。

寫(xiě)好 Skill 的 8 條實(shí)踐規(guī)則

規(guī)則 1：description 是整個(gè) Skill 的命門(mén)

description 決定觸發(fā)準(zhǔn)確性。要寫(xiě)觸發(fā)條件，不要寫(xiě)功能說(shuō)明。

# 差：功能說(shuō)明
description: "This skill helps with code reviews."
# 好：具體觸發(fā)條件
description: "This skill should be used when the user asks to review a pull request,
audit code changes, or analyze commit history for potential issues."

觸發(fā)短語(yǔ)越多、越具體，Claude 越能準(zhǔn)確判斷。

規(guī)則 2：正文給決策框架，不給步驟清單

步驟清單是給機(jī)器執(zhí)行的，決策框架是給 Claude 思考的。Claude 不是復(fù)讀機(jī)，它需要知道在什么情況下做什么判斷，而不是一步一步執(zhí)行什么操作。

規(guī)則 3：規(guī)定下限，不限上限

明確告訴 Claude"至少要包含什么"，但不限制 Claude 在此基礎(chǔ)上能額外做什么。好的 Skill 讓 Claude 知道最低質(zhì)量標(biāo)準(zhǔn)是什么，剩下的空間留給它發(fā)揮。

規(guī)則 4：一個(gè) Skill 只做一個(gè)領(lǐng)域

不要把代碼審查、安全掃描、風(fēng)格檢查三個(gè)完全不同的事塞進(jìn)一個(gè) Skill。拆開(kāi)之后每個(gè) Skill 更專注、更穩(wěn)定、出了問(wèn)題更容易定位。

規(guī)則 5：禁忌要說(shuō)清楚

很多 Skill 花大量篇幅描述"應(yīng)該做什么"，但對(duì)"不應(yīng)該做什么"只字不提。在 Skill 末尾加一個(gè)"邊界情況"或"禁忌"小節(jié)，告訴 Claude 什么紅線不能踩，往往比正向說(shuō)明更有效。

規(guī)則 6：SKILL.md 要精簡(jiǎn)，詳細(xì)內(nèi)容移至 references/

如果一個(gè) Skill 的正文超過(guò) 3000 詞還沒(méi)說(shuō)完，說(shuō)明內(nèi)容放錯(cuò)了位置。把詳細(xì)的模式文檔、API 參考、遷移指南移到 references/ 目錄，SKILL.md 只保留核心流程和快速參考。

規(guī)則 7：與 CLAUDE.md 劃清職責(zé)邊界

CLAUDE.md 回答"這個(gè)項(xiàng)目是什么"，Skill 回答"這類任務(wù)怎么做"。不要把項(xiàng)目規(guī)范復(fù)制進(jìn) Skill——規(guī)范放 CLAUDE.md，Skill 專注于具體任務(wù)執(zhí)行邏輯。

規(guī)則 8：給 Skill 留退出條件

Claude 在 Skill 執(zhí)行過(guò)程中可能遇到權(quán)限不足、外部依賴失敗、用戶中斷等情況。Skill 里要明確什么情況下應(yīng)該停止并報(bào)告，而不是讓 Claude 無(wú)限制地繼續(xù)嘗試直到輸出一個(gè)糟糕的結(jié)果。

Skill vs Commands：怎么選

實(shí)戰(zhàn)經(jīng)驗(yàn)：先用 Command 原型驗(yàn)證一個(gè)需求，確認(rèn)它高頻且流程穩(wěn)定后，再抽取為 Skill。

官方 14 個(gè)插件一覽

總結(jié)

Skills 系統(tǒng)是 Claude Code 最強(qiáng)大的擴(kuò)展機(jī)制，它的價(jià)值在于把團(tuán)隊(duì)的專業(yè)知識(shí)封裝成可自動(dòng)執(zhí)行的格式，讓 AI 在每個(gè)相關(guān)場(chǎng)景都能用團(tuán)隊(duì)最好的標(biāo)準(zhǔn)工作。

三個(gè)核心要點(diǎn)：

觸發(fā)靠 description。 description 寫(xiě)得好不好，決定了 Skill 能不能被正確調(diào)用。觸發(fā)短語(yǔ)要具體，要第三人稱，要覆蓋真實(shí)的用戶表達(dá)方式。

正文靠決策框架，不是步驟清單。 官方源碼展示的設(shè)計(jì)思想是一致的：給 Claude 思考框架，讓它在這個(gè)框架內(nèi)自主判斷，而不是機(jī)械地執(zhí)行步驟。

漸進(jìn)披露是核心架構(gòu)思想。 三層加載機(jī)制讓 Claude Code 能夠在保持上下文高效的同時(shí)，掌握大量的專業(yè)知識(shí)。這是 Skills 系統(tǒng)區(qū)別于簡(jiǎn)單 prompt 模板的根本所在。

本文參考資料：

• [1] GitHub: anthropics/claude-code - plugin-dev/skills/skill-development（官方 Skill 創(chuàng)建方法論）
• [2] GitHub: anthropics/claude-code - plugins/frontend-design/skills（官方 Skill 真實(shí)實(shí)現(xiàn)案例）
• [3] GitHub: anthropics/claude-code - plugins/plugin-dev/skills（7個(gè)官方 Skills 完整源碼）
• [4] DEV.to: "I Built a Diagnostic CLI for Claude Code Skills" by thestack_ai（8條常見(jiàn)錯(cuò)誤規(guī)則）

到此這篇關(guān)于Claude Code專題:Skills 系統(tǒng)完全指南的文章就介紹到這了,更多相關(guān)Claude Code Skills完全指南內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評(píng)論