給 Claude/Codex 構建 Skills 的完整指南
整理版優先睇
Skills 係專業化 AI 智能體嘅標準，教你由零開始構建 Skill，將通用 AI 變成真正嘅數字員工。
呢篇文章係 Rohit 喺 X 上分享嘅指南，由淺墨翻譯整理。佢背景係一位關注 AI 智能體發展嘅開發者，想解決嘅問題係：點樣由普通 prompt 過渡到真正可重用、可部署嘅 Skill。文章以 Anthropic 推出嘅 Skills 開放標準為核心，詳細拆解咗 Skill 嘅定義、結構、運作原理，仲有實戰步驟同真實案例。
整體結論好明確：Skill 係下一代 AI 協作方式嘅分水嶺。唔再係逐次寫 prompt，而係將最佳實踐、領域知識同工作流編碼成動態能力包，讓 AI 瞬間變成專業助手。無論係個人開發者定係企業，都應該盡快開始構建自己嘅 Skill 庫。文章由理論到底層機制，再到動手教學同進階模式，層層遞進，係一份高質素嘅實戰地圖。
- 結論：Skills 係專業化 AI 智能體嘅核心，將專家知識同工作流程編碼成可重用嘅動態能力包。
- 方法：三層漸進式披露系統（YAML frontmatter、SKILL.md、關聯資源）配合雙消息模式，實現高效上下文加載。
- 差異：傳統 prompt 係一次性指令，Skill 係結構化、可迭代、可分享嘅「數字員工說明書」。
- 啟發：先拆解重複任務，再定義成功標準；用 skill-creator 快速原型，然後迭代打磨。
- 可行動點：用 skills.sh CLI 安裝管理 Skill，從一個簡單任務開始，逐步建立內部 Skill 倉庫。
原文 X 帖子
Rohit 關於構建 Skills 嘅完整指南
開啟全新 AI 協作時代
以前我哋同 AI 互動，每次都要寫 prompt，好似次次都由頭開始。但而家前 1% 嘅人已經用緊另一種方式—— Skills。佢唔係一組單純嘅指令，而係一種動態、結構化嘅能力包。
動態、結構化嘅能力包
Skill
Anthropic 喺 2025 年 10 月推出呢個標準，OpenAI 同 Microsoft 都採用緊，Vercel 嘅 skills.sh CLI 令全球開發者更容易管理同分發 Skill。
Skills 底層運作原理
Skill 嘅核心係三層漸進式披露系統，確保唔會浪費 token。
- 1 第 1 層：YAML frontmatter（始終加載）——名稱同描述注入 system prompt，快速判斷關聯性。
- 2 第 2 層：SKILL.md 正文（相關時加載）——包含詳細步驟、示例同最佳實踐。
- 3 第 3 層：關聯資源（按需加載）——scripts、references、assets 目錄下嘅文件，只有需要先存取。
三層漸進式披露系統
另外仲有聰明嘅雙消息模式：用戶可見消息（isMeta: false）同元消息（isMeta: true）。用戶知道啓用咗邊啲 Skill，但唔使睇曬幾千字技術細節。
雙消息模式
元消息
構建你嘅第一個 Skill
唔好急住寫代碼，先做以下步驟：
- 確定 2-3 個具體使用場景：文檔生成、工作流自動化、MCP 增強都係常見方向。
- 定義成功標準：例如觸發準確率 >90%、工具調用次數減少、誤差為零。
- 寫好 description：結構係「[做咩] + [幾時用] + [關鍵能力]」，要包含真實觸發短語。
- 寫清楚指令結構：用 YAML frontmatter + Markdown 正文，包含 Instructions、Examples、Troubleshooting。
- 迭代測試：圍繞一個有挑戰嘅任務不斷試，直到輸出穩定再提煉成 Skill。
description 係關鍵觸發門檻
迭代測試
---
name: project-workspace-setup
description: 自動化完成項目工作區嘅創建，包括頁面、數據庫同模板。Use when user asks to "set up a new project", "create a workspace", or "initialize a project structure".
---
# Project Workspace Setup
## Instructions
[Claude 需要跟隨嘅分步指導]
## Examples
[具體使用場景]
## Troubleshooting
[常見問題與解決方案]真實案例與高階模式
一個前端設計 Skill 可以令 Claude Code 產出專業網頁，而唔係嗰啲一眼就睇出 AI 味嘅頁面。企業級文檔 Skill（PowerPoint、Excel）將 30 分鐘任務壓縮到 3 分鐘內。
前端設計 Skill
多 MCP 編排
高階模式包括：根據上下文選擇工具（Decision Tree）、嵌入領域知識（金融合規）、迭代式打磨（Initial Draft → Quality Check → Refinement Loop）。
根據上下文選擇工具
嵌入領域知識
迭代式打磨
安全方面要用信任模型，限制 allowed-tools。未來 Skill 會成為競爭差異化因素，合規型 Skill 會變得關鍵。
大家好，我係淺墨。
今日喺X見到一篇好好嘅文章，係講點樣創建Skills嘅，寫得非常有參考價值。
文章嘅作者係Rohit，原文連結如下：
https://x.com/rohit4verse/status/2021622526112358663
以下係呢篇文章嘅翻譯。
將AI當成通用聊天機械人嚟用嘅時代，已經正式結束咗。
99%嘅用戶仲喺度寫最基礎嘅prompt，前1%嘅人已經喺度構建skill。呢兩者嘅差別，就好似你手上面拎住嘅係個玩具，定係一個全天候、專業化嘅數字員工。
但如果你想做到後者，就要停低「寫prompt」呢件事，開始真正用skill將能力做出嚟。
下面呢篇，就係關於新一代skill標準嘅完整技術指南。
Anthropic喺2025年10月推出咗skills。佢唔係一組單純嘅指令，而係一種動態、結構化嘅能力包，令智能體可以按需要加載上下文。
佢最早仲係一項獨佔特性，而家已經演化成開放標準。OpenAI同Microsoft呢啲大平台都喺度採用呢套規範，Vercel嘅 skills.sh CLI呢類嘅工具，都令全球開發者更容易管理同分發skill。
智能體skills拆解
同傳統嘅函數調用或代碼執行唔同，skill嘅工作方式係更複雜嘅prompt擴展同上下文改寫。佢唔係簡單咁去執行某個預定義函數，而係喺度教智能體應該點樣理解問題、點樣落手。
一個skill嘅結構睇落非常簡單：
your-skill-name/
├── SKILL.md # 必需：主 skill 文件
├── scripts/ # 可選：可執行代碼
│ ├── process_data.py
│ └── validate.sh
├── references/ # 可選：文檔資料
│ ├── api-guide.md
│ └── examples/
└── assets/ # 可選：模板、字體、圖標
└── report-template.md
每個skill嘅核心都係 SKILL.md 文件。佢用 YAML frontmatter 存元數據，用 markdown 正文寫指令：
---
name: project-workspace-setup
description: 自動化完成項目工作區的創建，包括頁面、數據庫和模板。
Use when user asks to "set up a new project", "create a workspace", or "initialize a project structure".
---
# Project Workspace Setup
## Instructions
[Claude 需要遵循的分步指導]
## Examples
[具體使用場景]
## Troubleshooting
[常見問題與解決方案]
skill嘅設計好簡單，亦都好剋制。正因為咁，非開發者都可以上手；亦因為佢夠規範，佢又可以支撐企業級部署。
skills實際上係點樣運作嘅
如果你想將skill做好，先理解佢底層點樣運作，非常關鍵。
按照一份更深入嘅技術分析，skill本質上係一種基於prompt嘅元工具架構，同傳統AI工具嘅工作方式完全唔同。
三層漸進式披露系統
第1層：YAML frontmatter（始終加載）
skill嘅名稱同描述會被注入Claude嘅 system prompt。咁樣Claude就可以喺唔浪費太多token嘅前提下，先判斷自己係咪應該加載完整skill。
第2層：SKILL.md 正文（相關時加載）
當Claude判斷某個skill確實相關時，佢會再加載markdown正文入面嘅完整指令。呢度通常包含詳細步驟、示例同最佳實踐。
第3層：關聯資源（按需要加載）
scripts/、references/ 和 assets/ 目錄下面嘅附加文件，只有喺明確需要嗰陣先會俾人訪問，從而繼續節省上下文。
呢種漸進式披露嘅好處係：skill可以寫得非常詳細，但唔會一嚟就將上下文窗口塞滿。Claude只加載當下需要嗰部分內容。
雙消息模式與元通信
skill最巧妙嘅地方之一，係佢處理「可見性」嘅方式。
當Claude激活某個skill嗰陣，系統會發送兩類消息：
• 用戶可見消息（isMeta: false）：呢啲會直接出現喺對話記錄入面 • 元消息（isMeta: true）：呢啲包含完整嘅skill指令，會發俾Claude嘅API，但用戶睇唔到
呢套分離機制解決咗一個好關鍵嘅體驗問題：用戶需要知道當前啓用咗邊啲skill，但並唔需要見到嗰幾千字嘅技術說明將聊天窗口塞滿。
點樣構建你嘅第一個skill
第1步：先確定你嘅使用場景
喺你寫任何代碼之前，先明確2到3個你嘅skill應該處理嘅具體場景。
最常見嘅幾類係：
第1類：文檔與資產生成
適合生成風格統一、質量穩定嘅輸出，例如文檔、演示文稿或設計稿。例子：frontend-design skill，可以產出專業嘅網頁界面，而唔係嗰種一眼就睇得出係AI拼出嚟嘅通用頁面。
第2類：工作流自動化
適合嗰啲包含多個步驟、又好依賴一致流程嘅方法論型任務。例子：skill-creator skill，會引導用戶一步步創建新嘅skill。
第3類：MCP增強
它是在 Model Context Protocol（MCP）服務集成之上，再補上一層工作流指導。例子：Sentry嘅代碼評審skill，可以結合錯誤監控數據，自動分析並修復GitHub Pull Request入面嘅問題。
第2步：定義成功標準
你點樣判斷一個skill係咪真係有效？需要有可衡量嘅目標：
• 觸發準確率：喺90%嘅相關請求入面都能正確加載 • 工具效率：相比基線，喺X次工具調用內完成整套流程 • 錯誤率：每次工作流中API調用失敗次數為0 • 一致性：同一任務喺唔同會話入面能得到相近結果
第3步：寫好description
description字段非常關鍵。Claude就係靠佢嚟判斷要唔要加載某個skill。
推薦用咁嘅結構：
[它做什麼] + [什麼時候該用] + [關鍵能力]
好嘅例子：
description: 分析 Figma 設計文件，並生成開發交接文檔。
Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".
壞嘅例子：
description: Helps with projects.
要將用戶真實會講嘅觸發語句寫入去，提到相關文件類型，並且明確點出呢個skill解決嘅到底係乜嘢問題。
第4步：將指令結構寫清楚
---
name: your-skill
description: [清楚、具體的描述]
---
# Your Skill Name
## Instructions
Step 1: [第一步，清楚說明要做什麼]
Step 2: [第二步]
...
## Examples
Example 1: [常見場景]
User says: "Set up a new marketing campaign"
Actions:
1. Fetch existing campaigns via MCP
2. Create new campaign with provided parameters
Result: Campaign created with confirmation link
## Troubleshooting
Error: [常見錯誤信息]
Cause: [為什麼發生]
Solution: [怎麼解決]
第5步：迭代測試
最有效嘅方式，係先圍繞一個有挑戰嘅任務不斷迭代，直到Claude真正做啱，然後再將呢個過程提煉成你嘅skill。
測試重點包括：
• 觸發：應該觸發嗰陣會唔會觸發？會唔會誤觸發？ • 功能：輸出係咪穩定且正確？ • 性能：相比冇skill嘅基線，係咪真係好啲？
skills.sh CLI
2026年初，Vercel發佈咗 skills.sh，一個命令行工具。佢幾乎成為咗AI智能體世界入面嘅npm。
呢個CLI可以幫助你喺唔同AI平台之間安裝同管理skill。
基礎安裝方式如下：
# 從 GitHub 安裝一個 skill
npx skills add vercel-labs/agent-skills
# 從倉庫裏安裝某個指定 skill
npx skills add vercel-labs/agent-skills@vercel-react-best-practices
# 從直接路徑安裝
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
# 列出已安裝的 skills
npx skills list
# 檢查更新
npx skills check
# 更新所有 skills
npx skills update
skills.sh CLI 會自動識別你本機安裝咗邊啲AI編碼智能體，並做相應配置。
佢目前支援35種以上嘅智能體，包括Claude Code、Cursor、Codex、Open Code、Windsurf等等。
呢個平台仲提供咗基於安裝遙測嘅流行度排行、按場景分類瀏覽、搜索功能，以及一鍵安裝嘅直接連結。
真實世界入面嘅使用場景
案例1：前端設計能力嘅躍遷
如果你叫Claude Code去做一個落地頁，而冇加載 frontend-design skill，最後出嚟嘅嘢通常只係「用得」，但幾乎一眼就睇得出嗰股AI味。
但一旦加載咗呢個skill，同樣嘅任務就可能產出一個更專業、更現代嘅網站，設計模式更成熟，間距更講究，UI細節都更符合當代產品習慣。
呢個說明咗一個關鍵點：skill編碼嘅係超出Claude訓練數據之外嘅專家知識。frontend-design skill入面裝嘅係職業設計師沉澱落嚟嘅經驗，例如色彩理論、佈局原則同無障礙規範，而且佢哋被打包成咗可執行嘅方法知識。
案例2：企業級文檔生成
Anthropic預置嘅PowerPoint、Excel、Word同PDF skills，展示咗企業級能力應該係點樣。
呢啲skill可以做到：
• 品牌一致性：自動套用企業風格指南 • 模板一致性：遵循組織內部嘅文檔結構 • 公式智能：正確生成複雜嘅Excel公式 • PDF表單填寫：以編程方式完成可填寫PDF表單
使用呢啲skill嘅組織反饋係，原本要花30幾分鐘嘅任務，而家3分鐘以內就可以做完。
案例3：多MCP編排
設想一個橫跨多項服務嘅設計到開發交接流程：
Phase 1: Design Export (Figma MCP)
- Export design assets from Figma
- Generate design specifications
- Create asset manifest
Phase 2: Asset Storage (Google Drive MCP)
- Create project folder
- Upload all assets
- Generate shareable links
Phase 3: Task Creation (Linear MCP)
- Create development tasks
- Attach asset links to tasks
- Assign to engineering team
Phase 4: Notification (Slack MCP)
- Post handoff summary
- Include asset links and task references
如果有一個skill嚟編排呢整套流程，就唔再需要人工手動協調，步驟順序都唔會亂，錯誤恢復都可以自動處理。
高階模式與最佳實踐
模式1：根據上下文揀工具
聰明嘅skill會根據具體上下文做調整。
例如喺文件存儲場景入面：
Decision Tree:
1. Check file type and size
2. Determine best storage:
- Large files (>10MB): Cloud storage MCP
- Collaborative docs: Notion/Docs MCP
- Code files: GitHub MCP
- Temporary files: Local storage
3. Execute with appropriate tool
4. Explain choice to user
呢種模式既保留咗透明度，亦針對實際場景做咗更優選擇。
模式2：嵌入領域知識
skill可以內嵌高度專業化嘅知識。
例如一個金融合規skill可能會咁樣做：
B
efore Processing (Compliance Check):
1. Fetch transaction details via MCP
2. Apply compliance rules:
- Check sanctions lists
- Verify jurisdiction allowances
- Assess risk level
3. Document compliance decision
Processing:
IF compliance passed:
- Process transaction
- Apply fraud checks
ELSE:
- Flag for review
- Create compliance case
呢類skill實際上係喺度將Claude本來唔具備嘅監管知識編碼入去。
模式3：對高質量輸出做迭代式打磨
Initial Draft:
- Generate first version
- Save to temporary file
Quality Check:
- Run validation script
- Identify issues
Refinement Loop:
- Address each issue
- Regenerate affected sections
- Re-validate
- Repeat until quality threshold met
呢種模式對文檔生成、代碼評審同數據分析尤其有效。
安全與信任
skill嘅威力好大。佢可以執行代碼，亦可以調用工具。
正因為咁，安全問題必須認真考慮。
信任模型
Anthropic強烈建議只使用來自可信來源嘅skill：
• Anthropic官方skill：專業維護，經過驗證 • 自己創建嘅skill：代碼可控 • 合作伙伴skill：來自經過驗證嘅商業夥伴
社區skill喺安裝前應該先審查，因為惡意skill可能會誘導Claude執行唔係你本意嘅操作。
受限能力
skill運行喺受控環境入面：
• claude.ai：只能使用預裝包，網絡訪問受限 • claude code：擁有完整網絡訪問能力，但運行範圍侷限在用戶本機 • api：運行在代碼執行容器裏，權限可配置
YAML frontmatter仲可以用 allowed-tools 嚟限制skill可以訪問邊啲API：
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"
skills嘅未來
AI行業嘅關注點，正在從單純嘅模型能力，轉向真正嘅實用價值。
skill正代表住呢種變化：從炫目嘅demo，走向可以交付可衡量商業價值嘅生產級工作流。
按照當前趨勢嚟睇：
1. skill會成為競爭差異化因素
2. 擁有強大skill library嘅公司，會獲得明顯嘅生產力優勢。更早行動嘅團隊，已經開始將內部skill倉庫當成戰略資產。
3. skill市場會興起
4. 我哋已經開始見到類似應用商店嘅商業skill市場出現，面向唔同行業同場景出售專業skill。
5. AI輔助創建skill
6. skill-creator skill已經展示咗「AI構建AI能力」呢件事。呢個遞歸提升只會越來越快。未來版本甚至可能直接從自然語言描述生成複雜skill。
7. skill會演化成多智能體編排層
8. 隨住多智能體系統越來越常見，skill會進一步承擔協調多個AI智能體協同工作嘅角色。
9. 合規型skill會變得關鍵
10. 喺金融、醫療、法律等強監管行業入面，能編碼合規規則同審計軌跡嘅skill會成為剛需。
實操建議
俾個人開發者嘅建議
• 由細處開始：先為你反覆會做嘅嘢做一個skill。慳返重複勞動之後，前期投入好快就可以回本。 • 用好skill-creator：Anthropic嘅skill-creator skill（Claude.ai同Claude Code都有）可以喺15到30分鐘內幫你搭好第一個skill。 • 加入社區：去skills.sh嘅目錄入面睇下，安裝一啲熱門skill，從真實案例入面學習。
俾團隊同組織嘅建議
• 揾高價值工作流：邊啲流程團隊成員成日要反覆向AI解釋？呢啲就係最適合做成skill嘅候選項。 • 建立skill倉庫：將組織內部嘅skill放進Git入面做版本管理，喺團隊之間共享，並根據反饋持續迭代。 • 基於開放規範嚟做：按開放標準構建skill，咁樣未來AI生態繼續變化嗰陣，你嘅資產仍然可遷移。 • 認真維護skill：skill同其他代碼一樣，都需要更新。要有人負責，都要有評審流程。
俾企業嘅建議
• 利用組織級部署：用管理員控制能力，將skill分發到整個工作區，保證操作一致性。 • 同廠商合作：好多SaaS工具而家都提供官方skill，例如Atlassian、Notion、Figma等，佢哋可以直接接入你現有嘅工作流。 • 開發合規skill：將監管要求編碼入skill，確保AI輔助工作符合標準。 • 衡量ROI：跟蹤節省咗嘅時間、降低咗嘅錯誤率同一致性提升。skill應該拎得出明確嘅商業價值。
常見問題排查
skill唔識觸發？
• 問題：skill從來唔會自動加載 • 解決方案：修改description，將用戶真實會講嘅觸發短語寫入去，同時測試唔同表達方式
skill觸發得太頻繁
• 問題：skill會對冇關嘅請求都觸發 • 解決方案：加入負向觸發條件，將範圍寫得更具體。例如：唔好用於簡單數據探索（改用data-viz skill）
指令冇被遵守
• 問題：skill雖然加載咗，但Claude冇按要求執行 • 解決方案：指令盡量短，盡量用bullet point。關鍵規則放到最前面，並用## CRITICAL呢類標題標出。若果想做確定性驗證，優先考慮附帶可執行腳本，而唔係完全依賴自然語言。
MCP連接失敗
• 問題：skill加載咗，但MCP調用失敗 • 解決方案：確認MCP服務已經連接好（settings > extensions），檢查API key同鑑權，脱離skill單獨測試MCP，並核對工具名係咪同MCP文檔完全一致，包括大小寫。
結語
skill代表住我哋同AI協作方式嘅一次根本性演進。
佢唔再將每一輪對話都當成一張白紙，而係令我哋可以逐步積累組織知識、編碼最佳實踐，並構建真正理解我哋業務領域嘅專用AI助手。
開放標準意味住呢個唔係將你鎖死喺某家廠商入面嘅封閉體系。佢係一個可以令創新持續發生嘅生態。
無論你係獨立開發者，想做提升效率嘅工具；定係一個團隊，想將工作流標準化；又或者係一家企業，想大規模部署AI，skill都提供咗一套框架，可以將通用AI變成真正專業嘅合作伙伴。
而家嘅門檻已經前所未有咁低咗。有咗 skills.sh CLI同skill市場，創建並部署一個skill只需要幾分鐘，而唔係幾日。
學習曲線都唔陡峭。先從一個你成日要做嘅簡單任務開始，做出第一個skill，然後再慢慢向上長。
當我哋走向一個AI智能體承擔越來越複雜工作嘅未來嗰陣，skill會成為嗰條分水嶺：有些組織只係「在用AI」，而另一些組織，已經真正將AI變成了戰略優勢。
問題已經唔係你要唔要投資skill，而係你可以幾快開始構建佢。
歡迎嚟到專業化AI智能體嘅時代，亦歡迎嚟到skills嘅時代。
以上，就係呢篇文章所有內容，歡迎點讚、推薦、轉發三連，亦歡迎關注我，一個普通嘅創業者。
特別推薦
1. 兩個系列文章
系統咁記錄咗我嘅創業週報，以及喺Shopify App開發過程中嘅一啲知識點，歡迎大家查看。
2. Shopify開發交流社羣
目前國內Shopify開發資料稀缺，基本冇交流社區，所以我創建咗一個專注討論Shopify開發相關嘅各種技術問題嘅交流圈子。喺呢度你可以獲得：
• 學習Shopify App開發從入門到上架嘅流程。 • 學習Shopify主題開發。 • 同其他Shopify開發者諮詢開發遇到嘅問題，交流經驗。 • 同大家一齊交流副業、創業嘅經驗同心得。 • 星主會不定期分享Shopify開發&建站、web開發、移動端開發相關嘅私活，有需要嘅同學可以接。
歡迎你嚟加入，我哋知識星球見 🤝
大家好，我是淺墨。
今天在 X 上看到一篇非常好的文章，是講如何創建 Skills 的，寫的非常有參考價值。
文章的作者是 Rohit，原文連結如下：
https://x.com/rohit4verse/status/2021622526112358663
以下是這篇文章的翻譯。
把 AI 當成通用聊天機器人來用的時代，已經正式結束了。
99% 的用戶還在寫最基礎的 prompt，前 1% 的人已經在構建 skill。這兩者的差別，就像你手裏拿的是個玩具，還是一個全天候、專業化的數字員工。
但如果你想走到後者，就得停下“寫 prompt”這件事，開始真正用 skill 把能力做出來。
下面這篇，就是關於新一代 skill 標準的完整技術指南。
Anthropic 在 2025 年 10 月推出了 skills。它不是一組單純的指令，而是一種動態、結構化的能力包，讓智能體可以按需加載上下文。
它最早還是一項獨佔特性，現在已經演化成開放標準。OpenAI 和 Microsoft 這樣的大平台都在採用這套規範，Vercel 的 skills.sh CLI 之類的工具，也讓全球開發者更容易管理和分發 skill。
智能體 skills 拆解
和傳統的函數調用或代碼執行不同，skill 的工作方式是更復雜的 prompt 擴展和上下文改寫。它不是簡單去執行某個預定義函數，而是在教智能體該怎麼理解問題、怎麼下手。
一個 skill 的結構看上去非常簡單：
your-skill-name/
├── SKILL.md # 必需：主 skill 文件
├── scripts/ # 可選：可執行代碼
│ ├── process_data.py
│ └── validate.sh
├── references/ # 可選：文檔資料
│ ├── api-guide.md
│ └── examples/
└── assets/ # 可選：模板、字體、圖標
└── report-template.md
每個 skill 的核心都是 SKILL.md 文件。它用 YAML frontmatter 存元數據，用 markdown 正文寫指令：
---
name: project-workspace-setup
description: 自動化完成項目工作區的創建，包括頁面、數據庫和模板。
Use when user asks to "set up a new project", "create a workspace", or "initialize a project structure".
---
# Project Workspace Setup
## Instructions
[Claude 需要遵循的分步指導]
## Examples
[具體使用場景]
## Troubleshooting
[常見問題與解決方案]
skill 的設計很簡單，也很剋制。正因為如此，非開發者也能上手；也正因為它足夠規範，它又能支撐企業級部署。
skills 實際上是怎麼工作的
如果你想把 skill 做好，先理解它底層怎麼運作，非常關鍵。
按照一份更深入的技術分析，skill 本質上是一種基於 prompt 的元工具架構，和傳統 AI 工具的工作方式完全不同。
三層漸進式披露系統
第 1 層：YAML frontmatter（始終加載）
skill 的名稱和描述會被注入 Claude 的 system prompt。這樣 Claude 能在不浪費太多 token 的前提下，先判斷自己是否該加載完整 skill。
第 2 層：SKILL.md 正文（相關時加載）
當 Claude 判斷某個 skill 確實相關時，它會再加載 markdown 正文裏的完整指令。這裏通常包含詳細步驟、示例和最佳實踐。
第 3 層：關聯資源（按需加載）
scripts/、references/ 和 assets/ 目錄下的附加文件，只有在明確需要時才會被訪問，從而繼續節省上下文。
這種漸進式披露的好處是：skill 可以寫得非常細，但不會一上來就把上下文窗口塞滿。Claude 只加載當下需要的那部分內容。
雙消息模式與元通信
skill 最巧妙的地方之一，是它處理“可見性”的方式。
當 Claude 激活某個 skill 時，系統會發送兩類消息：
• 用戶可見消息（isMeta: false）：這些會直接出現在對話記錄裏 • 元消息（isMeta: true）：這些包含完整的 skill 指令，會發給 Claude 的 API，但用戶看不到
這套分離機制解決了一個很關鍵的體驗問題：用戶需要知道當前啓用了哪些 skill，但並不需要看到那幾千字的技術說明把聊天窗口塞滿。
如何構建你的第一個 skill
第 1 步：先確定你的使用場景
在你寫任何代碼之前，先明確 2 到 3 個你的 skill 應該處理的具體場景。
最常見的幾類是：
第 1 類：文檔與資產生成
適合生成風格統一、質量穩定的輸出，比如文檔、演示文稿或設計稿。 例子：frontend-design skill，可以產出專業的網頁界面，而不是那種一眼就能看出是 AI 拼出來的通用頁面。
第 2 類：工作流自動化
適合那些包含多個步驟、又很依賴一致流程的方法論型任務。 例子：skill-creator skill，會引導用戶一步步創建新的 skill。
第 3 類：MCP 增強
它是在 Model Context Protocol（MCP）服務集成之上，再補上一層工作流指導。例子：Sentry 的代碼評審 skill，可以結合錯誤監控數據，自動分析並修復 GitHub Pull Request 裏的問題。
第 2 步：定義成功標準
你怎麼判斷一個 skill 是否真的有效？需要有可衡量的目標：
• 觸發準確率：在 90% 的相關請求裏都能正確加載 • 工具效率：相比基線，在 X 次工具調用內完成整套流程 • 錯誤率：每次工作流中 API 調用失敗次數為 0 • 一致性：同一任務在不同會話裏能得到相近結果
第 3 步：寫好 description
description 字段非常關鍵。Claude 就是靠它來判斷要不要加載某個 skill。
推薦用這樣的結構：
[它做什麼] + [什麼時候該用] + [關鍵能力]
好的例子：
description: 分析 Figma 設計文件，並生成開發交接文檔。
Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".
壞的例子：
description: Helps with projects.
要把用戶真實會說的觸發語句寫進去，提到相關文件類型，並且明確點出這個 skill 解決的到底是什麼問題。
第 4 步：把指令結構寫清楚
---
name: your-skill
description: [清楚、具體的描述]
---
# Your Skill Name
## Instructions
Step 1: [第一步，清楚說明要做什麼]
Step 2: [第二步]
...
## Examples
Example 1: [常見場景]
User says: "Set up a new marketing campaign"
Actions:
1. Fetch existing campaigns via MCP
2. Create new campaign with provided parameters
Result: Campaign created with confirmation link
## Troubleshooting
Error: [常見錯誤信息]
Cause: [為什麼發生]
Solution: [怎麼解決]
第 5 步：迭代測試
最有效的方式，是先圍繞一個有挑戰的任務不斷迭代，直到 Claude 真正做對，然後再把這個過程提煉成你的 skill。
測試重點包括：
• 觸發：該觸發時會不會觸發？會不會誤觸發？ • 功能：輸出是否穩定且正確？ • 性能：相比沒有 skill 的基線，是不是真的更好？
skills.sh CLI
2026 年初，Vercel 發佈了 skills.sh，一個命令行工具。它幾乎成了 AI 智能體世界裏的 npm。
這個 CLI 可以幫助你在不同 AI 平台之間安裝和管理 skill。
基礎安裝方式如下：
# 從 GitHub 安裝一個 skill
npx skills add vercel-labs/agent-skills
# 從倉庫裏安裝某個指定 skill
npx skills add vercel-labs/agent-skills@vercel-react-best-practices
# 從直接路徑安裝
npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
# 列出已安裝的 skills
npx skills list
# 檢查更新
npx skills check
# 更新所有 skills
npx skills update
skills.sh CLI 會自動識別你本機安裝了哪些 AI 編碼智能體，並做相應配置。
它目前支持 35 種以上的智能體，包括 Claude Code、Cursor、Codex、Open Code、Windsurf 等等。
這個平台還提供了基於安裝遙測的流行度排行、按場景分類瀏覽、搜索功能，以及一鍵安裝的直接連結。
真實世界裏的使用場景
案例 1：前端設計能力的躍遷
如果你讓 Claude Code 去做一個落地頁，而沒有加載 frontend-design skill，最後出來的東西通常只是“能用”，但幾乎一眼就能看出那股 AI 味。
但一旦加載這個 skill，同樣的任務就可能產出一個更專業、更現代的網站，設計模式更成熟，間距更講究，UI 細節也更符合當代產品習慣。
這說明了一個關鍵點：skill 編碼的是超出 Claude 訓練數據之外的專家知識。frontend-design skill 裏裝的是職業設計師沉澱下來的經驗，比如色彩理論、佈局原則和無障礙規範，而且它們被打包成了可執行的方法知識。
案例 2：企業級文檔生成
Anthropic 預置的 PowerPoint、Excel、Word 和 PDF skills，展示了企業級能力該是什麼樣。
這些 skill 可以做到：
• 品牌一致性：自動套用企業風格指南 • 模板一致性：遵循組織內部的文檔結構 • 公式智能：正確生成複雜的 Excel 公式 • PDF 表單填寫：以編程方式完成可填寫 PDF 表單
使用這些 skill 的組織反饋是，原本要花 30 多分鐘的任務，現在 3 分鐘以內就能做完。
案例 3：多 MCP 編排
設想一個橫跨多項服務的設計到開發交接流程：
Phase 1: Design Export (Figma MCP)
- Export design assets from Figma
- Generate design specifications
- Create asset manifest
Phase 2: Asset Storage (Google Drive MCP)
- Create project folder
- Upload all assets
- Generate shareable links
Phase 3: Task Creation (Linear MCP)
- Create development tasks
- Attach asset links to tasks
- Assign to engineering team
Phase 4: Notification (Slack MCP)
- Post handoff summary
- Include asset links and task references
如果有一個 skill 來編排這整套流程，就不再需要人工手動協調，步驟順序也不會亂，錯誤恢復也能自動處理。
高階模式與最佳實踐
模式 1：根據上下文選工具
聰明的 skill 會根據具體上下文做調整。
比如在文件存儲場景裏：
Decision Tree:
1. Check file type and size
2. Determine best storage:
- Large files (>10MB): Cloud storage MCP
- Collaborative docs: Notion/Docs MCP
- Code files: GitHub MCP
- Temporary files: Local storage
3. Execute with appropriate tool
4. Explain choice to user
這種模式既保留了透明度，也針對實際場景做了更優選擇。
模式 2：嵌入領域知識
skill 可以內嵌高度專業化的知識。
比如一個金融合規 skill 可能會這樣做：
B
efore Processing (Compliance Check):
1. Fetch transaction details via MCP
2. Apply compliance rules:
- Check sanctions lists
- Verify jurisdiction allowances
- Assess risk level
3. Document compliance decision
Processing:
IF compliance passed:
- Process transaction
- Apply fraud checks
ELSE:
- Flag for review
- Create compliance case
這類 skill 實際上是在把 Claude 本來不具備的監管知識編碼進去。
模式 3：對高質量輸出做迭代式打磨
Initial Draft:
- Generate first version
- Save to temporary file
Quality Check:
- Run validation script
- Identify issues
Refinement Loop:
- Address each issue
- Regenerate affected sections
- Re-validate
- Repeat until quality threshold met
這種模式對文檔生成、代碼評審和數據分析尤其有效。
安全與信任
skill 的威力很大。它可以執行代碼，也可以調用工具。
正因為如此，安全問題必須認真考慮。
信任模型
Anthropic 強烈建議只使用來自可信來源的 skill：
• Anthropic 官方 skill：專業維護，經過驗證 • 自己創建的 skill：代碼可控 • 合作伙伴 skill：來自經過驗證的商業夥伴
社區 skill 在安裝前應該先審查，因為惡意 skill 可能會誘導 Claude 執行並非你本意的操作。
受限能力
skill 運行在受控環境裏：
• claude.ai：只能使用預裝包，網絡訪問受限 • claude code：擁有完整網絡訪問能力，但運行範圍侷限在用戶本機 • api：運行在代碼執行容器裏，權限可配置
YAML frontmatter 還可以用 allowed-tools 來限制 skill 能訪問哪些 API：
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"
skills 的未來
AI 行業的關注點，正在從單純的模型能力，轉向真正的實用價值。
skill 正代表着這種變化：從炫目的 demo，走向可以交付可衡量商業價值的生產級工作流。
按照當前趨勢來看：
1. skill 會成為競爭差異化因素
2. 擁有強大 skill library 的公司，會獲得明顯的生產力優勢。更早行動的團隊，已經開始把內部 skill 倉庫當成戰略資產。
3. skill 市場會興起
4. 我們已經開始看到類似應用商店的商業 skill 市場出現，面向不同行業和場景出售專業 skill。
5. AI 輔助創建 skill
6. skill-creator skill 已經展示了“AI 構建 AI 能力”這件事。這個遞歸提升只會越來越快。未來版本甚至可能直接從自然語言描述生成複雜 skill。
7. skill 會演化成多智能體編排層
8. 隨着多智能體系統越來越常見，skill 會進一步承擔協調多個 AI 智能體協同工作的角色。
9. 合規型 skill 會變得關鍵
10. 在金融、醫療、法律等強監管行業裏，能編碼合規規則和審計軌跡的 skill 會成為剛需。
實操建議
給個人開發者的建議
• 從小處開始：先為你反覆會做的事情做一個 skill。省掉重複勞動之後，前期投入很快就能回本。 • 用好 skill-creator：Anthropic 的 skill-creator skill（Claude.ai 和 Claude Code 都有）可以在 15 到 30 分鐘內幫你搭好第一個 skill。 • 加入社區：去 skills.sh 的目錄裏看看，裝一些熱門 skill，從真實案例裏學習。
給團隊和組織的建議
• 找高價值工作流：哪些流程團隊成員總要反覆向 AI 解釋？這些就是最適合做成 skill 的候選項。 • 建 skill 倉庫：把組織內部的 skill 放進 Git 裏做版本管理，在團隊間共享，並根據反饋持續迭代。 • 基於開放規範來做：按開放標準構建 skill，這樣未來 AI 生態繼續變化時，你的資產仍然可遷移。 • 認真維護 skill：skill 和其他代碼一樣，都需要更新。要有人負責，也要有評審流程。
給企業的建議
• 利用組織級部署：用管理員控制能力，把 skill 分發到整個工作區，保證操作一致性。 • 和廠商合作：很多 SaaS 工具現在都提供官方 skill，比如 Atlassian、Notion、Figma 等，它們能直接接入你現有的工作流。 • 開發合規 skill：把監管要求編碼進 skill，確保 AI 輔助工作符合標準。 • 衡量 ROI：跟蹤節省的時間、降低的錯誤率和一致性提升。skill 應該拿得出明確的商業價值。
常見問題排查
skill 不觸發
• 問題：skill 從來不會自動加載 • 解決方案：修改 description，把用戶真實會說的觸發短語寫進去，同時測試不同表達方式
skill 觸發得太頻繁
• 問題：skill 會對無關請求也觸發 • 解決方案：加入負向觸發條件，把範圍寫得更具體。比如：不要用於簡單數據探索（改用 data-viz skill）
指令沒有被遵守
• 問題：skill 雖然加載了，但 Claude 沒按要求執行 • 解決方案：指令儘量短，儘量用 bullet point。關鍵規則放到最前面，並用 ## CRITICAL 這類標題標出。若想做確定性驗證，優先考慮附帶可執行腳本，而不是完全依賴自然語言。
MCP 連接失敗
• 問題：skill 加載了，但 MCP 調用失敗 • 解決方案：確認 MCP 服務已經連接好（settings > extensions），檢查 API key 和鑑權，脱離 skill 單獨測試 MCP，並核對工具名是否與 MCP 文檔完全一致，包括大小寫。
結語
skill 代表着我們與 AI 協作方式的一次根本性演進。
它不再把每一輪對話都當成一張白紙，而是讓我們可以逐步積累組織知識、編碼最佳實踐，並構建真正理解我們業務領域的專用 AI 助手。
開放標準意味着這不是把你鎖死在某家廠商裏的封閉體系。它是一個能讓創新持續發生的生態。
無論你是獨立開發者，想做提升效率的工具；還是一個團隊，想把工作流標準化；又或者是一家企業，想大規模部署 AI，skill 都提供了一套框架，能把通用 AI 變成真正專業的合作伙伴。
現在的門檻已經前所未有地低了。有了 skills.sh CLI 和 skill 市場，創建並部署一個 skill 只需要幾分鐘，而不是幾天。
學習曲線也並不陡。先從一個你經常要做的簡單任務開始，做出第一個 skill，然後再慢慢往上長。
當我們走向一個 AI 智能體承擔越來越複雜工作的未來時，skill 會成為那條分水嶺：有些組織只是“在用 AI”，而另一些組織，已經真正把 AI 變成了戰略優勢。
問題已經不是你要不要投資 skill，而是你能多快開始構建它。
歡迎來到專業化 AI 智能體的時代，也歡迎來到 skills 的時代。
以上，就是本篇文章所有內容，歡迎點個贊、推薦、轉發三連，也歡迎關注我，一個普通的創業者。
特別推薦
1. 兩個系列文章
系統地記錄了我的創業週報，以及在Shopify App開發過程中的一些知識點，歡迎大家查看。
2. Shopify 開發交流社羣
目前國內Shopify開發資料稀缺，基本沒有交流社區，所以我創建了一個專注討論Shopify開發相關的各種技術問題的交流圈子。在這裏你可以獲得：
• 學習Shopify App開發從入門到上架的流程。 • 學習 Shopify 主題開發。 • 和其他Shopify開發者諮詢開發遇到的問題，交流經驗。 • 和大家一起交流副業、創業的經驗和心得。 • 星主會不定期分享Shopify開發&建站、web開發、移動端開發相關的私活，有需要的同學可以接。
歡迎你來加入，我們知識星球見 🤝