Initial commit

2025-11-29 18:00:18 +08:00
commit 765529cd13
69 changed files with 18291 additions and 0 deletions
--- a/skills/claude-agent-sdk/assets/sdk-validation-checklist.md
+++ b/skills/claude-agent-sdk/assets/sdk-validation-checklist.md
@@ -0,0 +1,362 @@
+# Claude Agent SDK Validation Checklist
+
+This checklist helps validate SDK applications against official patterns and best practices from the claude-agent-sdk skill documentation.
+
+## Quick Validation
+
+Use this checklist when:
+
+- Creating new SDK applications
+- Reviewing SDK code
+- Debugging SDK issues
+- Ensuring alignment with best practices
+
+---
+
+## 1. Imports & Dependencies
+
+### Required Checks
+
+- [ ] **Async runtime import**
+  - Uses `import anyio` (official SDK examples use anyio)
+  - Comment reflects official preference: `# Official SDK examples use anyio`
+  - **Reference:** Official examples consistently use anyio
+
+- [ ] **Claude SDK imports are accurate**
+  - `ClaudeAgentOptions` for configuration
+  - `ClaudeSDKClient` for continuous conversations OR `query` for one-shot tasks
+  - `AgentDefinition` if using programmatic agents
+  - Message types: `AssistantMessage`, `ResultMessage`, `TextBlock`
+  - Permission types if using callbacks: `PermissionResultAllow`, `PermissionResultDeny`
+  - **Reference:** `references/api-reference.md`
+
+- [ ] **UV script headers (if applicable)**
+  - Uses `#!/usr/bin/env -S uv run --script --quiet`
+  - Has PEP 723 dependencies block with `claude-agent-sdk>=0.1.6`
+  - **Reference:** `assets/sdk-template.py` lines 1-7
+
+---
+
+## 2. Async Runtime
+
+### Required Checks
+
+- [ ] **Runtime execution is correct**
+  - Uses `anyio.run(main)` (official SDK examples use anyio.run())
+  - Comment reflects official preference: `# Official SDK examples use anyio.run()`
+  - **Reference:** Official examples consistently use anyio.run()
+
+- [ ] **Async/await patterns are correct**
+  - Functions marked as `async def`
+  - Uses `await` for SDK calls
+  - Uses `async for` for message streaming
+  - Uses `async with` for ClaudeSDKClient context manager
+  - **Reference:** `references/best-practices.md` lines 82-94
+
+---
+
+## 3. Choosing query() vs ClaudeSDKClient
+
+### Required Checks
+
+- [ ] **Correct approach for use case**
+  - `query()`: One-shot tasks, no conversation memory
+  - `ClaudeSDKClient`: Multi-turn conversations, context retention
+  - **Reference:** SKILL.md lines 29-44
+
+- [ ] **Hooks/Custom tools only with ClaudeSDKClient**
+  - NOT using hooks with `query()` (not supported)
+  - NOT using custom tools with `query()` (not supported)
+  - **Reference:** SKILL.md line 45 (important warning)
+
+---
+
+## 4. Orchestrator Configuration
+
+### Required Checks
+
+- [ ] **System prompt is set correctly**
+  - Uses `system_prompt={"type": "preset", "preset": "claude_code"}` for orchestrators
+    (official examples use dict format)
+  - OR uses `system_prompt="claude_code"` (string shorthand, equivalent but less explicit)
+  - Custom prompts only for non-orchestrators
+  - **Reference:** Official examples use dict format, SKILL.md lines 226-242,
+    `references/system-prompts.md`
+
+- [ ] **Task tool is included**
+  - `allowed_tools` includes `"Task"` for orchestrators
+  - Orchestrators cannot delegate without Task tool
+  - **Reference:** SKILL.md line 39, `references/best-practices.md` lines 72-80
+
+- [ ] **Agent definitions are programmatic**
+  - Agents defined in `agents={}` parameter (preferred)
+  - Clear `description` (when to use agent)
+  - Specific `prompt` (agent instructions)
+  - Minimal `tools` list (principle of least privilege)
+  - **Reference:** SKILL.md lines 195-217, `references/agent-patterns.md`
+
+---
+
+## 5. Agent Definitions
+
+### Required Checks
+
+- [ ] **Agent definition structure is correct**
+
+  ```python
+  AgentDefinition(
+      description="...",  # When to use this agent
+      prompt="...",       # Agent instructions
+      tools=[...],        # Minimal tool set
+      model="sonnet"      # or "opus", "haiku", "inherit"
+  )
+  ```
+
+  - **Reference:** SKILL.md lines 195-217
+
+- [ ] **Agent names match references**
+  - Names in `agents={}` match Task tool usage
+  - No naming mismatches between definition and invocation
+  - **Reference:** `references/best-practices.md` lines 43-52
+
+- [ ] **Tools are restricted to minimum needed**
+  - Read-only agents: `["Read", "Grep", "Glob"]`
+  - Code modifiers: `["Read", "Edit", "Bash"]`
+  - No excessive tool permissions
+  - **Reference:** SKILL.md lines 248-256, `references/best-practices.md` lines 54-71
+
+---
+
+## 6. Permission Control
+
+### Required Checks
+
+- [ ] **Permission strategy is appropriate**
+  - Simple use case → `permission_mode` only
+  - Complex logic → `can_use_tool` callback
+  - **Reference:** `references/tool-permissions.md` lines 13-114
+
+- [ ] **Permission mode is valid**
+  - One of: `"acceptEdits"`, `"rejectEdits"`, `"plan"`, `"bypassPermissions"`, `"default"`
+  - Appropriate for use case (e.g., CI/CD uses `"acceptEdits"`)
+  - **Reference:** `references/tool-permissions.md` lines 64-70
+
+- [ ] **Permission callback (if used) is correct**
+  - Signature: `async def(tool_name, input_data, context) -> PermissionResultAllow | PermissionResultDeny`
+  - Returns early for unmatched tools
+  - Uses `.get()` for safe input_data access
+  - Clear denial messages
+  - **Reference:** `references/tool-permissions.md` lines 120-344, `examples/tool_permission_callback.py`
+
+---
+
+## 7. Hooks (if used)
+
+### Required Checks
+
+- [ ] **Hooks ONLY used with ClaudeSDKClient**
+  - NOT using hooks with `query()` function
+  - **Reference:** SKILL.md line 45 (critical warning)
+
+- [ ] **Hook types are supported**
+  - Using ONLY: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PreCompact`
+  - NOT using unsupported: `SessionStart`, `SessionEnd`, `Notification`
+  - **Reference:** `references/hooks-guide.md` line 14 (important warning)
+
+- [ ] **Hook signature is correct**
+  - `async def(input_data, tool_use_id, context) -> HookJSONOutput`
+  - Returns empty `{}` when hook doesn't apply
+  - Uses `HookMatcher` for tool filtering
+  - **Reference:** `references/hooks-guide.md` lines 46-68, `examples/hooks.py`
+
+- [ ] **Hook output structure is valid**
+  - Includes `hookEventName` in `hookSpecificOutput`
+  - PreToolUse: includes `permissionDecision` ("allow" or "deny")
+  - Includes clear `reason` and `systemMessage` fields
+  - **Reference:** `references/hooks-guide.md` lines 70-144
+
+---
+
+## 8. ClaudeSDKClient Usage
+
+### Required Checks
+
+- [ ] **Context manager pattern is used**
+
+  ```python
+  async with ClaudeSDKClient(options=options) as client:
+      await client.query(...)
+      async for message in client.receive_response():
+          ...
+  ```
+
+  - **Reference:** SKILL.md lines 88-124
+
+- [ ] **Query → receive_response flow**
+  - Calls `await client.query(prompt)` first
+  - Then iterates `async for message in client.receive_response()`
+  - Does NOT interleave queries and receives incorrectly
+  - **Reference:** `examples/streaming_mode.py`
+
+- [ ] **Interrupts (if used) are correct**
+  - Uses `await client.interrupt()` to stop execution
+  - Only available with ClaudeSDKClient (not query())
+  - **Reference:** SKILL.md lines 139-162
+
+---
+
+## 9. Message Handling
+
+### Required Checks
+
+- [ ] **Message types are checked correctly**
+
+  ```python
+  if isinstance(message, AssistantMessage):
+      for block in message.content:
+          if isinstance(block, TextBlock):
+              print(block.text)
+  elif isinstance(message, ResultMessage):
+      # Handle completion
+  ```
+
+  - **Reference:** SKILL.md lines 77-91, `examples/streaming_mode.py`
+
+- [ ] **TextBlock extraction is correct**
+  - Iterates through `message.content`
+  - Checks `isinstance(block, TextBlock)` before accessing `.text`
+  - **Reference:** `references/best-practices.md` lines 95-113
+
+- [ ] **ResultMessage handling**
+  - Checks for `message.duration_ms`, `message.total_cost_usd`
+  - Uses optional access (fields may be None)
+  - **Reference:** `assets/sdk-template.py` lines 86-93
+
+---
+
+## 10. Error Handling
+
+### Required Checks
+
+- [ ] **API key validation**
+  - Checks `os.getenv("ANTHROPIC_API_KEY")` before SDK calls
+  - Provides clear error message if missing
+  - **Reference:** `assets/sdk-template.py` lines 58-63
+
+- [ ] **Safe dictionary access**
+  - Uses `.get()` for input_data, tool_response fields
+  - Handles missing/None values gracefully
+  - **Reference:** `references/tool-permissions.md` lines 297-344
+
+- [ ] **Async exception handling**
+  - Try/except blocks for critical sections
+  - Proper cleanup in exception cases
+  - **Reference:** `references/best-practices.md`
+
+---
+
+## 11. Settings & Configuration
+
+### Required Checks
+
+- [ ] **setting_sources is configured (if needed)**
+  - Default behavior: NO settings loaded (isolated environment)
+  - Explicitly set to load: `["user"]`, `["project"]`, `["local"]`, or combinations like `["user", "project"]`
+  - Understands isolation vs loading tradeoff
+  - **Reference:** `examples/setting_sources.py` (official example shows user, project, local options)
+
+- [ ] **Model selection is appropriate**
+  - Orchestrator: `"claude-sonnet-4-5"` (simplified, official examples prefer this)
+    or `"claude-sonnet-4-5-20250929"` (dated version)
+  - Subagents: `"sonnet"`, `"opus"`, `"haiku"`, or `"inherit"`
+  - **Reference:** Official examples use `claude-sonnet-4-5`, SKILL.md line 51,
+    `references/agent-patterns.md`
+
+- [ ] **Budget limits (if needed)**
+  - Uses `max_budget_usd` for cost control
+  - Appropriate for CI/CD and automated workflows
+  - **Reference:** `examples/max_budget_usd.py`
+
+---
+
+## 12. Best Practices Compliance
+
+### Required Checks
+
+- [ ] **Follows DRY principle**
+  - Options extracted to function (e.g., `get_sdk_options()`)
+  - Reusable patterns not duplicated
+  - **Reference:** `assets/sdk-template.py` lines 33-55
+
+- [ ] **Clear comments and documentation**
+  - Docstrings for functions
+  - Inline comments for complex logic
+  - Usage notes in module docstring
+  - **Reference:** `assets/sdk-template.py` lines 8-17
+
+- [ ] **Type hints are used**
+  - Function return types specified
+  - Parameter types for clarity
+  - **Reference:** `assets/sdk-template.py` line 36
+
+- [ ] **No anti-patterns**
+  - Not using agents for simple tasks (use query() instead)
+  - Not giving excessive tool permissions
+  - Not bypassing permissions without reason
+  - **Reference:** `references/best-practices.md`, skill SKILL.md
+
+---
+
+## Validation Summary Template
+
+After reviewing, fill out this summary:
+
+### ✅ Passed Checks
+
+- [ ] Imports & Dependencies
+- [ ] Async Runtime
+- [ ] Orchestrator Configuration
+- [ ] Agent Definitions
+- [ ] Permission Control
+- [ ] Message Handling
+- [ ] Best Practices
+
+### ❌ Issues Found
+
+- Issue 1: [Description]
+- Issue 2: [Description]
+
+### 🔧 Fixes Required
+
+1. [Specific fix with line reference]
+2. [Specific fix with line reference]
+
+### 📊 Overall Assessment
+
+- **Accuracy:** [%]
+- **Alignment with docs:** [High/Medium/Low]
+- **Production ready:** [Yes/No]
+
+---
+
+## Quick Reference Links
+
+**Core Documentation:**
+
+- Main skill: `SKILL.md`
+- API reference: `references/api-reference.md`
+- Best practices: `references/best-practices.md`
+
+**Pattern Guides:**
+
+- Agent patterns: `references/agent-patterns.md`
+- Hooks: `references/hooks-guide.md`
+- Permissions: `references/tool-permissions.md`
+- System prompts: `references/system-prompts.md`
+- Subagents: `references/subagents.md`
+
+**Examples:**
+
+- Quick start: `examples/quick_start.py`
+- Template: `assets/sdk-template.py`
+- Complete examples: `examples/*.py`