Skill Design Guide

基於 Anthropic 官方平台文件和 Claude Code 團隊實踐經驗的 Skill 設計規範。

官方資源:

• Agent Skills Overview: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
• Skill Authoring Best Practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
• Claude Code Skills Docs: https://code.claude.com/docs/en/skills
• Skills Cookbook: https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction
• Engineering Blog: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
• Lessons from Building Claude Code: https://x.com/trq212/status/2027463795355095314

1. 核心設計原則

Concise is Key（精簡至上）

預設假設：Claude 已經非常聰明。只加入 Claude 不知道的資訊。

對每條指令自問：「Claude 真的需要這個解釋嗎？」「這段文字值得它的 token 成本嗎？」

Progressive Disclosure（漸進式揭露）

Skill 使用三層載入系統，最小化 token 使用：

Degrees of Freedom（自由度設計）

根據任務脆弱性和變異性，設定適當的指令精確度：

Composability（可組合性）

Claude 可同時載入多個 Skill。設計時不要假設自己是唯一的 Skill。

Portability（可攜性）

Skill 可跨 Claude.ai、Claude Code、API 使用。但自訂 Skill 不會跨平台同步，需分別上傳。

2. 技術規範

檔案結構

your-skill-name/
├── SKILL.md           # 必要 - 主要指令檔
├── scripts/           # 選填 - 可執行腳本（Python, Bash 等）
├── references/        # 選填 - 按需載入的詳細文件
└── assets/            # 選填 - 範本、字型、圖示等

命名與檔案規則

官方推薦：Gerund 命名（動詞 + ing 形式）：

• processing-pdfs, analyzing-spreadsheets, managing-databases
• 也可接受名詞片語：pdf-processing, spreadsheet-analysis
• 避免模糊名稱：helper, utils, tools, documents

大小限制

• SKILL.md body: 建議低於 500 行。超過時拆分到 references/
• description: 最長 1,024 字元
• compatibility: 最長 500 字元

3. YAML Frontmatter 規格

3.1 Agent Skills 標準欄位

3.2 Claude Code 擴展欄位

以下欄位為 Claude Code 特有，在 Claude.ai/API 上不一定支援：

3.3 allowed-tools 語法

# Agent Skills 標準格式
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"

# Claude Code 格式（也可接受）
allowed-tools: Bash(ticket *), Read, Grep, Glob

# 安全建議：使用命令模式限制，優於裸 Bash
allowed-tools: Bash(gh *)  # 只允許 gh 命令

3.4 metadata 範例

metadata:
  author: Company Name
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]

3.5 安全限制

4. Description 寫作規範（最重要）

description 是 Skill 觸發的唯一機制（除手動 /name）。寫好 description 是 Skill 成敗的關鍵。

強制：長度限制（最重要的規則）

description 超過 250 字會被截斷，導致自動觸發完全失敗。

關鍵詞位置策略：最重要的觸發詞放在 description 最前面。截斷時後面的先丟失。

實際案例：/parallel-evaluation 的 description 超過 250 字，「多視角審核」「code review」等觸發詞在 Use for: 段落中被截斷，Claude 完全無法自動觸發，PM 被迫手動派發 Agent 繞過標準流程。

強制：第三人稱

description 注入 system prompt，人稱不一致會導致觸發問題。

• 正確："Processes Excel files and generates reports"
• 錯誤："I can help you process Excel files"
• 錯誤："You can use this to process Excel files"

結構公式

[做什麼] + [何時使用（觸發條件）] + [關鍵能力]

Undertrigger 防護（官方建議）

Claude 傾向 undertrigger（有用時不觸發）。Description 應稍微積極，主動列出觸發情境，包括用戶沒有明說但明顯需要的場景。

對比：

# 太被動（undertrigger 風險）
description: "Processes PDF files to extract text and tables."

# 積極版（防止 undertrigger）
description: "Processes PDF files to extract text and tables. Use whenever the user mentions PDFs, wants to read a document, asks to summarize a file, or uploads any document — even if they don't explicitly say 'PDF'."

加強觸發的技巧：

• 列出用戶可能說的同義詞和近似詞（e.g., "document", "file", "report" 不只是 "PDF"）
• 加上 "even if they don't explicitly ask for..." 涵蓋隱性需求
• 加上 "Make sure to use this skill whenever..." 作為明確的觸發指引

正確範例

# 具體且可操作
description: "Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for 'design specs', 'component documentation', or 'design-to-code handoff'."

# 包含觸發短語
description: "Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions 'sprint', 'Linear tasks', 'project planning', or asks to 'create tickets'."

# 明確的價值主張
description: "End-to-end customer onboarding workflow for PayFlow. Handles account creation, payment setup, and subscription management. Use when user says 'onboard new customer', 'set up subscription', or 'create PayFlow account'."

# 包含負面觸發（防止過度觸發）
description: "Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration (use data-viz skill instead)."

錯誤範例

# 太籠統
description: "Helps with projects."

# 缺少觸發條件
description: "Creates sophisticated multi-page documentation systems."

# 太技術，無使用者觸發
description: "Implements the Project entity model with hierarchical relationships."

# 描述內部架構而非使用場景
description: "統一 Ticket 系統 v1.0 - 整合 create/track/handoff/resume/migrate/generate 六大功能。"

專案內格式（也可接受）

# 中文 + "Use for:" 列舉式
description: "認知負擔評估工具。Use for: (1) 任務複雜度評估, (2) 代理人升級判斷, (3) 任務拆分建議"

觸發問題診斷

Skill 未觸發：description 太籠統或缺少使用者常用詞彙。加入更多關鍵字和觸發短語。

Skill 過度觸發：加入負面觸發（"Do NOT use for..."）或限縮描述範圍。

驗證方法：問 Claude「When would you use the [skill name] skill?」。Claude 會引用 description，根據回答調整。

5. 指令撰寫最佳實踐

建議的 SKILL.md 結構

---
name: your-skill
description: [...]
---

# Your Skill Name

## Instructions

### Step 1: [First Major Step]
Clear explanation of what happens.

### Step 2: [Next Step]
...

## Examples

### Example 1: [common scenario]
User says: "..."
Actions:
1. ...
2. ...
Result: ...

## Troubleshooting

### Error: [Common error message]
**Cause:** [Why it happens]
**Solution:** [How to fix]

指令品質原則

具體且可操作：

# 好
Run `python scripts/validate.py --input {filename}` to check data format.
If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)

# 壞
Validate the data before proceeding.

包含錯誤處理：

## Common Issues

### MCP Connection Failed
If you see "Connection refused":
1. Verify MCP server is running
2. Confirm API key is valid
3. Try reconnecting

清楚引用 references/ 中的資源：

Before writing queries, consult `references/api-patterns.md` for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handling

引用只能一層深（官方強制）：所有 reference 檔案從 SKILL.md 直接連結，禁止 A→B→C 巢狀引用。

長 reference 檔（100+ 行）加 TOC：確保 Claude preview 時能看到完整範圍。

重要指令放最上面：使用 ## Important 或 ## Critical 標題。關鍵指令需要時可重複。

避免時間敏感資訊：不要寫「2025 年 8 月前用舊 API」。用 "old patterns" 區段處理。

一致性術語：選定一個詞彙，全 Skill 統一使用（不要混用 "endpoint"/"URL"/"route"）。

MCP 工具用完整限定名稱：ServerName:tool_name 格式，避免 "tool not found"。

避免模糊語言：

# 壞
Make sure to validate things properly

# 好
CRITICAL: Before calling create_project, verify:
- Project name is non-empty
- At least one team member assigned
- Start date is not in the past

6. Claude Code 特有功能

字串替換

Skill 內容支援動態變數替換：

若 SKILL.md 內容中沒有 $ARGUMENTS，參數會自動附加為 ARGUMENTS: <value>。

動態 Context 注入

!`command` 語法在 Skill 內容送出前執行 shell 命令：

## Pull request context
- PR diff: !`gh pr diff`
- Changed files: !`gh pr diff --name-only`

這是預處理，Claude 只看到展開後的結果。

觸發控制矩陣

Description 預算

• 預算: context window 的 2%（fallback: 16,000 字元）
• 超出時: 部分 Skill 會被排除
• 單一 description 上限: 250 字（超過被截斷，觸發詞丟失）
• 建議: description 保持 1-3 句（< 100 字），focus on 觸發條件

7. YAML 格式陷阱

禁止：多行語法

# 錯誤：| 和 > block scalar 會導致解析失敗
description: |
  第一行會被解析為 description
  第二行會被誤判為獨立屬性名稱

# 正確：雙引號單行字串
description: "第一行內容。第二行內容。第三行內容。"

禁止：缺少分隔符

# 錯誤：缺少 --- 分隔符
name: my-skill
description: Does things

# 正確
---
name: my-skill
description: Does things
---

禁止：未閉合引號

# 錯誤
description: "Does things

# 正確
description: "Does things"

8. 快速檢查清單

開始前

• 已確定 2-3 個具體使用案例
• 已識別需要的工具（內建或 MCP）
• 已規劃資料夾結構

開發中

• 資料夾使用 kebab-case 命名（推薦 gerund 形式）
• SKILL.md 檔名完全正確（大小寫敏感）
• YAML frontmatter 有 --- 分隔符
• name 欄位：kebab-case，無空格，無大寫
• description 使用第三人稱，包含「做什麼」和「何時使用」
• 無 XML 角括號（< >）
• 無自訂屬性（triggers, type, category 等）
• 無 YAML 多行語法（| >）
• 指令具體可操作
• 包含錯誤處理
• 包含範例
• references/ 連結只有一層深
• 長 reference 檔（100+ 行）有 TOC
• 資料夾內無 README.md
• SKILL.md body 低於 500 行
• 無時間敏感資訊
• 術語一致

上線後

• 測試觸發：相關查詢能觸發
• 測試觸發：改述查詢也能觸發
• 測試觸發：無關主題不會觸發
• 功能測試通過
• 多模型測試（Haiku/Sonnet/Opus 行為可能不同）
• 收集回饋並迭代

9. 常見 Skill 類型

設計建議：

• Reference 型 Skill 保持預設（Claude 自動載入）
• Task 型 Skill 設 disable-model-invocation: true，防止 Claude 擅自執行副作用操作

10. 安全考量

強烈建議只使用來自信任來源的 Skill（自己建立或 Anthropic 提供）。

審查清單：檢查所有 SKILL.md、腳本、資源檔案。留意異常的網路呼叫、檔案存取模式。

11. 延伸閱讀

• 詳細的 Patterns、Troubleshooting 和 Testing 指引：references/patterns-and-troubleshooting.md
• 工具設計哲學和演進洞見：references/seeing-like-an-agent.md

Last Updated: 2026-03-08 Source: Anthropic Official Platform Docs + "Lessons from Building Claude Code" + anthropics/skills skill-creator + Project Experience