• 時間：主線約 6–10 小時；把所有選讀與專案都做完約 15–25 小時。
• 環境：Git、終端機和一個不含私密資料的練習 repo。
• 認證：Claude Code 可使用 Anthropic 帳號／API，也有 Amazon Bedrock、Google Vertex AI 與 Microsoft Foundry 的官方路徑。它不是任意本機模型的通用前端。
• 費用：先做不呼叫模型的檔案與設定檢查；真正執行 Claude Code 前，再看 /cost 或帳戶用量。不要用固定金額猜一次練習會花多少。
• 安全：第一輪只用示範 repo、唯讀 MCP 和最小權限。不要把 production token、SSH key 或真實客戶資料放進練習。

1. 在不含私密資料的練習 repo 根目錄建立 CLAUDE.md。
2. 只寫四區：Purpose、Do not、Verify、Deliver。
3. 先人工讀一遍，再請 Claude 依上面的 prompt 說明它理解到什麼。
4. 成功條件：Claude 沒改檔，且說出的驗證指令跟 CLAUDE.md 一致。

CLAUDE.md 建議低於 200 行。@path import 可以整理檔案，但被 import 的內容仍會進 context；要按路徑延後載入，使用 .claude/rules/ 的 paths frontmatter。

建立 .claude/skills/readme-check/SKILL.md：

---
name: readme-check
description: Check a README for a clear purpose, install steps, one example, and a license link. Use when the user asks to review README onboarding.
disable-model-invocation: true
---

1. Read the README without changing it.
2. Check: purpose, install steps, one runnable example, license link.
3. Return PASS or a short list of missing items with line references.

macOS/Linux：

mkdir -p .claude/skills/readme-check

先人工檢查 YAML frontmatter，再在 Claude Code 輸入 /readme-check。disable-model-invocation: true 表示只有你能主動叫它，適合有副作用或需要控制時機的流程。

本 repo 的完整 meta-example：examples/stage-5/tool-calling-tutor/。

把這段存成 .claude/hooks/log-tool.py：

import json
import sys
from datetime import datetime, timezone
from pathlib import Path


event = json.load(sys.stdin)
record = {
    "checked_at": datetime.now(timezone.utc).isoformat(),
    "hook_event_name": event.get("hook_event_name"),
    "tool_name": event.get("tool_name"),
}
log_path = Path(__file__).with_name("events.jsonl")
with log_path.open("a", encoding="utf-8") as handle:
    handle.write(json.dumps(record, ensure_ascii=False) + "\n")

如果 demo repo 還沒有 .claude/settings.json，直接建立：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python",
            "args": [
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/log-tool.py"
            ]
          }
        ]
      }
    ]
  }
}

如果檔案已存在，只把 PreToolUse 加進原本的 hooks，不要覆蓋其他設定。把 .claude/hooks/events.jsonl 加進 .gitignore，避免把本機操作紀錄提交出去。

先用假資料測試 script：

'{"hook_event_name":"PreToolUse","tool_name":"Write"}' | python .claude/hooks/log-tool.py
Get-Content .claude/hooks/events.jsonl

接著在 Claude Code 輸入 /hooks，確認 PreToolUse 顯示一個 Hook；再請 Claude 在 demo repo 建立 hook-demo.txt。最後一行應包含 "hook_event_name": "PreToolUse" 與 "tool_name": "Write"。

• Hook 可以是 shell command、HTTP endpoint、prompt、agent 或 MCP tool；不是每一種 event 都支援每一種 handler。
• PreToolUse 的 exit code 2 可以擋 tool call；但 exit code 2 對所有 event 的效果並不相同，要查官方 event matrix。
• 這個範例只記錄 event 與 tool 名稱，不保存完整 prompt、tool input、token 或秘密值；exit code 0 代表不阻擋。
• 成功條件：假資料測試與一次真正的 Write 都新增一行，而且紀錄中沒有 prompt 或檔案內容。

1. 建立一個只放假資料的資料夾。
2. 依 Claude Code MCP 文件 加入 filesystem server，scope 只指向該資料夾。
3. 先列 tools，再讀一個假檔案，最後移除 server。
4. 成功條件：讀指定資料夾成功；要求讀外面路徑時失敗。

MCP 的三個核心抽象：Tools 是模型可呼叫的動作，Resources 是可讀資料，Prompts 是 server 提供的 prompt 樣板。多數入門 server 先用 Tools。

2026-07-28 規格把核心改為 stateless request／response，移除 initialize／initialized 與 Mcp-Session-Id，並用 MRTR 處理需要補資料的多回合請求。這是 SDK／server 作者才需要深入的遷移內容；只連現成 server 的讀者先確認 host 與 server 支援同一版即可。

Claude Code 內建的主要 Subagents 是 Explore、Plan 和 general-purpose。其他名稱可能來自 plugin、組織設定或你自己寫的 .claude/agents/<name>.md，不能假設每台機器都有。

---
name: docs-finder
description: Find documentation related to a named feature and return file paths. Use for read-only documentation discovery.
tools: Read, Glob, Grep
model: haiku
---

Search only. Return up to five file paths with one-sentence reasons. Do not edit files or run shell commands.

Subagent 由現行 Agent tool 派遣。它有獨立 context 與權限設定，會收到一份自足任務，最後把摘要交回主對話。小問題、需要頻繁來回或高度共享 context 的工作，留在主對話比較簡單。

Claude Code 可在 CLI、Desktop、VS Code 與 JetBrains 等 surface 使用。它能操作檔案與工具，但仍受 permission、sandbox、Hook 和組織政策限制；不要把「能執行 shell」誤解成「應該給全部權限」。

.claude/rules/*.md 可依 paths 延後載入。.claude/skills/<name>/SKILL.md 則是按需知識或流程。舊 .claude/commands/*.md 仍能產生 slash command，但新內容優先教 Skills。

常用入口以現行 Commands reference 為準。第一次只記 /help、/model、/permissions、/memory、/agents 和 /cost；功能會更新，不把固定「十大指令」當長期標準。

• Tool Use：模型提出結構化呼叫，由你的程式或 host 執行。
• MCP：把工具、資料與 prompt 的交換方式做成跨 host 的協定。
• Skill：教 agent 何時、如何使用能力；它不會憑空建立外部連線。
• Plugin：把 Skill、Hook、Subagent、MCP 設定等打包分享。

官方 modelcontextprotocol/servers 是 reference implementations，不等於 production-ready server。連第三方 server 前要看來源、權限、資料流向與移除方式。Tool result 也是不可信輸入，不能直接當成高權限指令。

2026-07-28 是目前查核到的正式規格版。它採 stateless core、header routing、MRTR 和 extensions framework；舊版功能有至少 12 個月 deprecation window。不要把 2025 的初始化流程直接貼進新 server。

Skill 的 description 像索引卡標題：要寫「什麼時候使用」，不能只寫漂亮的功能介紹。Skill body 預設按需載入；Supporting files 可放 references/、scripts/ 與其他資料夾。

• disable-model-invocation: true：只能由使用者主動叫，適合 deploy、commit 或會產生外部副作用的流程。
• user-invocable: false：不當作使用者 slash command，但 Claude 仍可在相關情境使用。

直接複製的 audit prompt：

請檢查這份 SKILL.md：
1. description 是否寫清楚「何時使用」與「何時不用」？
2. 主檔是否只留必要流程，細節是否移到 references/？
3. 每一步是否有可驗證的成功條件？
4. 有副作用的流程是否禁止 model 自動觸發？
5. 相對連結、腳本和範例是否真的存在？
請逐項回覆 PASS／FAIL、證據位置與最小修正；不要直接覆寫檔案。

現行 Skills 遵循 Agent Skills 開放標準；Claude Code 另加 invocation control、subagent execution 與 dynamic context 等能力。跨工具共用時，內容核心可以相同，但資料夾、frontmatter、權限和工具名稱要分開驗證。

my-plugin/
├── .claude-plugin/plugin.json
├── skills/<name>/SKILL.md
├── agents/<name>.md
├── hooks/hooks.json
└── .mcp.json

實際 schema 以 Plugins reference 為準；現行元件還可包含 LSP servers 與 monitors。不要把教學用的最小樹狀圖當完整 schema。

加 Marketplace 只是在目錄裡看得到 Plugins，不代表全部已安裝。安裝前檢查 repo、publisher、權限、Hook、MCP server、license 與更新方式。Managed／project／local settings 的優先與 consent 規則要以官方設定文件為準。

自訂 Subagent 的 description 是路由提示，不是程式碼層的 if。Prompt 要 self-contained，明寫任務、範圍、工具、輸出和停止條件。現行官方也支援 skills、mcpServers、permissions、hooks 與 isolation: worktree 等設定；只在真的需要時加。

多開 agent 會增加 token、延遲與整合工作。不要宣稱固定倍數；用你的任務、模型和用量記錄實測。

進階 15 個可複製 recipe：resources/subagent-cookbook.md。組合與排錯：resources/subagent-advanced.md。

Dynamic workflows 把「下一步做什麼」寫進 JavaScript 腳本，不綁特定 Claude 型號；用 /workflows 看進度。官方文件列出的可用途徑包含 paid plans、Anthropic API、Amazon Bedrock、Google Cloud Agent Platform 與 Microsoft Foundry；Pro 要從 /config 開啟。

Worktree 解決「不要改到同一份檔案」；Subagent／team 解決「誰做哪件事」。兩者可以一起用，但不是同一功能。Agent teams 不會自動替每個 teammate 建 Worktree，所以仍要切清楚檔案 ownership。

先讀 How the agent loop works，再回答：

1. 哪些資料在送給模型前進入 context？
2. 模型提出 tool call 後，誰檢查 permission？
3. Tool result 如何回到下一輪？
4. Loop 在成功、錯誤、拒絕或達到限制時如何停止？
5. Hook、MCP、Skill 和 Subagent 各插在哪一段？

把答案畫成六格箭頭圖，再用 100–150 字比較 Stage 3 的最小 ReAct loop 多了哪些控制邊界。

anthropics/claude-agent-sdk-python 值得讀，但它是 SDK client／wrapper，不是 Claude Code 完整 runtime source。可以讀 message types、transport、query options 與 error handling；不要在 _internal/client.py 找不到完整 LLM loop 時誤以為自己漏看。

需要 SDK 的情況：

• 使用者不會開終端機，你要把 agent 放進自己的 App。
• 需要程式化輸入輸出、排程、審計、限額或多租戶。
• 需要由服務控制 allowed tools、session 與結果格式。

import asyncio
from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, TextBlock, query


async def main() -> None:
    options = ClaudeAgentOptions(allowed_tools=["Read", "Glob"])
    async for message in query(prompt="Summarize this project without editing files.", options=options):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)


asyncio.run(main())

安裝套件是 claude-agent-sdk／@anthropic-ai/claude-agent-sdk；舊 claude-code-sdk 名稱已遷移。SDK 支援 Anthropic API，也有 Bedrock、Vertex AI 與 Foundry 的官方認證路徑。

SDK 會執行命令並保存 session state，不能把它當成普通 stateless text API。上線前要做容器／sandbox、network control、credential isolation、resource limits、audit log 與人類批准。先讀 Hosting 和 secure deployment 文件。