@clawnet/template-minimal 0.0.1

package/.agents/skills/claude-agent-sdk/references/top-errors.md

@@ -0,0 +1,503 @@
+# Top Errors & Solutions
+
+Complete reference for common Claude Agent SDK errors and how to fix them.
+
+---
+
+## Error #1: CLI Not Found
+
+### Error Message
+```
+"Claude Code CLI not installed"
+```
+
+### Why It Happens
+The SDK requires Claude Code CLI to be installed globally, but it's not found in PATH.
+
+### Solution
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+Verify installation:
+```bash
+which claude-code
+# Should output: /usr/local/bin/claude-code or similar
+```
+
+### Prevention
+- Install CLI before using SDK
+- Add to project setup documentation
+- Check CLI availability in CI/CD
+
+---
+
+## Error #2: Authentication Failed
+
+### Error Message
+```
+"Invalid API key"
+"Authentication failed"
+```
+
+### Why It Happens
+- ANTHROPIC_API_KEY environment variable not set
+- API key is invalid or expired
+- API key has wrong format
+
+### Solution
+```bash
+# Set API key
+export ANTHROPIC_API_KEY="sk-ant-..."
+
+# Verify it's set
+echo $ANTHROPIC_API_KEY
+```
+
+Get API key:
+1. Visit https://console.anthropic.com/
+2. Navigate to API Keys section
+3. Create new key
+4. Copy and save securely
+
+### Prevention
+- Use environment variables (never hardcode)
+- Check key before running
+- Add to .env.example template
+- Document setup process
+
+---
+
+## Error #3: Permission Denied
+
+### Error Message
+```
+"Tool use blocked"
+"Permission denied for tool: Bash"
+```
+
+### Why It Happens
+- Tool not in `allowedTools` array
+- `permissionMode` is too restrictive
+- Custom `canUseTool` callback denied execution
+
+### Solution
+```typescript
+// Add tool to allowedTools
+options: {
+  allowedTools: ["Read", "Write", "Edit", "Bash"]  // Add needed tools
+}
+
+// Or use less restrictive permission mode
+options: {
+  permissionMode: "acceptEdits"  // Auto-approve edits
+}
+
+// Or check canUseTool logic
+options: {
+  canUseTool: async (toolName, input) => {
+    console.log("Tool requested:", toolName);  // Debug
+    return { behavior: "allow" };
+  }
+}
+```
+
+### Prevention
+- Set appropriate `allowedTools` from start
+- Test permission logic thoroughly
+- Use `permissionMode: "bypassPermissions"` in CI/CD
+
+---
+
+## Error #4: Context Length Exceeded
+
+### Error Message
+```
+"Prompt too long"
+"Context length exceeded"
+"Too many tokens"
+```
+
+### Why It Happens
+- Input prompt exceeds model's context window (200k tokens)
+- Long conversation without pruning
+- Large files in context
+
+### Solution
+SDK auto-compacts context, but you can:
+
+```typescript
+// Fork session to start fresh from a point
+const forked = query({
+  prompt: "Continue with fresh context",
+  options: {
+    resume: sessionId,
+    forkSession: true  // Start fresh
+  }
+});
+
+// Or reduce context
+options: {
+  allowedTools: ["Read", "Grep"],  // Limit tools
+  systemPrompt: "Keep responses concise."
+}
+```
+
+### Prevention
+- Use session forking for long tasks
+- Keep prompts focused
+- Don't load unnecessary files
+- Monitor context usage
+
+---
+
+## Error #5: Tool Execution Timeout
+
+### Error Message
+```
+"Tool did not respond"
+"Tool execution timeout"
+```
+
+### Why It Happens
+- Tool takes too long (>5 minutes default)
+- Infinite loop in tool implementation
+- Network timeout for external tools
+
+### Solution
+
+For custom tools:
+```typescript
+tool("long_task", "Description", schema, async (args) => {
+  // Add timeout
+  const timeout = 60000; // 1 minute
+  const promise = performLongTask(args);
+  const result = await Promise.race([
+    promise,
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('Timeout')), timeout)
+    )
+  ]);
+  return { content: [{ type: "text", text: result }] };
+})
+```
+
+For bash commands:
+```typescript
+// Add timeout to bash command
+command: "timeout 60s long-running-command"
+```
+
+### Prevention
+- Set reasonable timeouts
+- Optimize tool implementations
+- Use background jobs for long tasks
+- Test tools independently
+
+---
+
+## Error #6: Session Not Found
+
+### Error Message
+```
+"Invalid session ID"
+"Session not found"
+```
+
+### Why It Happens
+- Session ID is incorrect
+- Session expired (old)
+- Session from different CLI instance
+
+### Solution
+```typescript
+// Ensure session ID captured correctly
+let sessionId: string | undefined;
+for await (const message of response) {
+  if (message.type === 'system' && message.subtype === 'init') {
+    sessionId = message.session_id;  // Capture here
+    console.log("Session:", sessionId);  // Verify
+  }
+}
+
+// Use correct session ID
+query({
+  prompt: "...",
+  options: { resume: sessionId }  // Must match exactly
+});
+```
+
+### Prevention
+- Always capture session_id from system init
+- Store session IDs reliably
+- Don't rely on sessions lasting indefinitely
+- Handle session errors gracefully
+
+---
+
+## Error #7: MCP Server Connection Failed
+
+### Error Message
+```
+"Server connection error"
+"MCP server not responding"
+"Failed to connect to MCP server"
+```
+
+### Why It Happens
+- Server command/URL incorrect
+- Server crashed or not running
+- Network issues (HTTP/SSE servers)
+- Missing dependencies
+
+### Solution
+
+For stdio servers:
+```typescript
+// Verify command works independently
+// Test: npx @modelcontextprotocol/server-filesystem
+options: {
+  mcpServers: {
+    "filesystem": {
+      command: "npx",  // Verify npx is available
+      args: ["@modelcontextprotocol/server-filesystem"],
+      env: {
+        ALLOWED_PATHS: "/path"  // Verify path exists
+      }
+    }
+  }
+}
+```
+
+For HTTP servers:
+```typescript
+// Test URL separately
+const testResponse = await fetch("https://api.example.com/mcp");
+console.log(testResponse.status);  // Should be 200
+```
+
+### Prevention
+- Test MCP servers independently before integration
+- Verify command/URL works
+- Add error handling for server failures
+- Use health checks
+
+---
+
+## Error #8: Subagent Definition Error
+
+### Error Message
+```
+"Invalid AgentDefinition"
+"Agent configuration error"
+```
+
+### Why It Happens
+- Missing required fields (`description` or `prompt`)
+- Invalid `model` value
+- Invalid `tools` array
+
+### Solution
+```typescript
+agents: {
+  "my-agent": {
+    description: "Clear description of when to use",  // Required
+    prompt: "Detailed system prompt",                  // Required
+    tools: ["Read", "Write"],                          // Optional
+    model: "sonnet"                                    // Optional
+  }
+}
+```
+
+### Prevention
+- Always include `description` and `prompt`
+- Use TypeScript types
+- Test agent definitions
+- Follow examples in templates
+
+---
+
+## Error #9: Settings File Not Found
+
+### Error Message
+```
+"Cannot read settings"
+"Settings file not found"
+```
+
+### Why It Happens
+- `settingSources` includes non-existent file
+- File path incorrect
+- File permissions deny read
+
+### Solution
+```typescript
+// Check file exists before loading
+import fs from 'fs';
+
+const projectSettingsPath = '.claude/settings.json';
+const settingSources = [];
+
+if (fs.existsSync(projectSettingsPath)) {
+  settingSources.push('project');
+}
+
+options: {
+  settingSources  // Only existing files
+}
+```
+
+### Prevention
+- Check file exists before including in sources
+- Use empty array for isolated execution
+- Handle missing files gracefully
+
+---
+
+## Error #10: Tool Name Collision
+
+### Error Message
+```
+"Duplicate tool name"
+"Tool already defined"
+```
+
+### Why It Happens
+- Two MCP servers define same tool name
+- Tool name conflicts with built-in tool
+
+### Solution
+```typescript
+// Use unique tool names
+const server1 = createSdkMcpServer({
+  name: "service-a",
+  tools: [
+    tool("service_a_process", ...)  // Prefix with server name
+  ]
+});
+
+const server2 = createSdkMcpServer({
+  name: "service-b",
+  tools: [
+    tool("service_b_process", ...)  // Different name
+  ]
+});
+```
+
+### Prevention
+- Use unique tool names
+- Prefix tools with server name
+- Test integration before deployment
+
+---
+
+## Error #11: Zod Schema Validation Error
+
+### Error Message
+```
+"Invalid tool input"
+"Schema validation failed"
+```
+
+### Why It Happens
+- Agent provided data that doesn't match Zod schema
+- Schema too restrictive
+- Missing `.describe()` on fields
+
+### Solution
+```typescript
+// Add descriptive schemas
+{
+  email: z.string().email().describe("User email address"),
+  age: z.number().int().min(0).max(120).describe("Age in years"),
+  role: z.enum(["admin", "user"]).describe("User role")
+}
+
+// Make fields optional if appropriate
+{
+  email: z.string().email(),
+  phoneOptional: z.string().optional()  // Not required
+}
+```
+
+### Prevention
+- Use `.describe()` on all fields
+- Add validation constraints
+- Test with various inputs
+- Make optional fields explicit
+
+---
+
+## Error #12: Filesystem Permission Denied
+
+### Error Message
+```
+"Access denied"
+"Cannot access path"
+"EACCES: permission denied"
+```
+
+### Why It Happens
+- Path outside `workingDirectory`
+- No read/write permissions
+- Protected system directory
+
+### Solution
+```typescript
+// Set correct working directory
+options: {
+  workingDirectory: "/path/to/accessible/dir"
+}
+
+// Or fix permissions
+// chmod +r file.txt  (add read)
+// chmod +w file.txt  (add write)
+```
+
+### Prevention
+- Set appropriate `workingDirectory`
+- Verify file permissions
+- Don't access system directories
+- Use dedicated project directories
+
+---
+
+## General Error Handling Pattern
+
+```typescript
+try {
+  const response = query({ prompt: "...", options: { ... } });
+
+  for await (const message of response) {
+    if (message.type === 'error') {
+      console.error('Agent error:', message.error);
+      // Handle non-fatal errors
+    }
+  }
+} catch (error) {
+  console.error('Fatal error:', error);
+
+  // Handle specific errors
+  switch (error.code) {
+    case 'CLI_NOT_FOUND':
+      console.error('Install: npm install -g @anthropic-ai/claude-code');
+      break;
+    case 'AUTHENTICATION_FAILED':
+      console.error('Check ANTHROPIC_API_KEY');
+      break;
+    case 'RATE_LIMIT_EXCEEDED':
+      console.error('Rate limited. Retry with backoff.');
+      break;
+    case 'CONTEXT_LENGTH_EXCEEDED':
+      console.error('Reduce context or fork session');
+      break;
+    default:
+      console.error('Unexpected error:', error);
+  }
+}
+```
+
+---
+
+**For more details**: See SKILL.md
+**Template**: templates/error-handling.ts

package/.agents/skills/claude-agent-sdk/rules/claude-agent-sdk.md

@@ -0,0 +1,96 @@
+---
+paths: "**/*agent*.ts", "**/*.ts"
+---
+
+# Claude Agent SDK Corrections
+
+This uses **@anthropic-ai/claude-agent-sdk v0.1.50**.
+
+## MCP Tool Naming Convention
+
+```typescript
+/* ❌ Wrong naming */
+const tool = 'mcp_server_tool'
+
+/* ✅ Double underscores required */
+const tool = 'mcp__server-name__tool-name'
+// Format: mcp__<server-name>__<tool-name>
+```
+
+## No Default System Prompt
+
+```typescript
+/* ❌ Assuming default instructions */
+const agent = new Agent({
+  model: 'claude-sonnet-4-5-20250929',
+  // No system prompt...
+})
+
+/* ✅ Always provide custom system instruction */
+const agent = new Agent({
+  model: 'claude-sonnet-4-5-20250929',
+  system: 'You are a helpful assistant that...',
+})
+```
+
+## Permission Control
+
+```typescript
+/* ✅ Implement canUseTool for security */
+const agent = new Agent({
+  model: 'claude-sonnet-4-5-20250929',
+  canUseTool: async (tool) => {
+    if (tool.name.startsWith('dangerous_')) return 'deny'
+    if (tool.name === 'file_write') return 'ask'
+    return 'allow'
+  },
+})
+
+// Permission modes:
+// 'default' - Normal permissions
+// 'acceptEdits' - Auto-accept file edits
+// 'bypassPermissions' - CI/CD only!
+// 'plan' - Planning mode
+```
+
+## Session Forking (Unique Feature)
+
+```typescript
+/* ✅ Create branch without modifying original */
+const forkedSession = await session.fork()
+// Original session unchanged
+// Forked session can diverge
+```
+
+## Subagent Definitions
+
+```typescript
+/* ❌ Missing required fields */
+const subagent = { prompt: 'Do task' }
+
+/* ✅ Include description and prompt */
+const subagent = {
+  description: 'Handles data processing tasks',
+  prompt: 'Process the provided data and return results',
+}
+```
+
+## Settings Priority
+
+```
+Highest → Lowest:
+1. Programmatic (code)
+2. Local (.claude/settings.local.json)
+3. Project (.claude/settings.json)
+4. User (~/.claude/settings.json)
+```
+
+## Quick Fixes
+
+| If Claude suggests... | Use instead... |
+|----------------------|----------------|
+| `mcp_server_tool` | `mcp__server__tool` (double underscores) |
+| No system prompt | Always provide `system` instruction |
+| Missing canUseTool | Implement permission control |
+| Subagent without description | Include `description` and `prompt` |
+| Tool timeout issues | >5 minutes raises error, handle long tasks |

package/.agents/skills/claude-agent-sdk/scripts/check-versions.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+
+# Check package versions for Claude Agent SDK skill
+# Usage: ./scripts/check-versions.sh
+
+set -e
+
+echo "🔍 Checking Claude Agent SDK package versions..."
+echo ""
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Check if npm is available
+if ! command -v npm &> /dev/null; then
+    echo -e "${RED}❌ npm not found. Please install Node.js.${NC}"
+    exit 1
+fi
+
+# Function to check package version
+check_package() {
+    local package=$1
+    local current_version=$2
+
+    echo -n "Checking $package... "
+
+    # Get latest version from npm
+    latest_version=$(npm view $package version 2>/dev/null)
+
+    if [ $? -ne 0 ]; then
+        echo -e "${RED}❌ Not found in npm registry${NC}"
+        return 1
+    fi
+
+    if [ "$current_version" = "$latest_version" ]; then
+        echo -e "${GREEN}✅ Up to date ($current_version)${NC}"
+    else
+        echo -e "${YELLOW}⚠️  Update available: $current_version → $latest_version${NC}"
+    fi
+}
+
+echo "📦 Dependencies:"
+check_package "@anthropic-ai/claude-agent-sdk" "0.1.0"
+check_package "zod" "3.23.0"
+
+echo ""
+echo "🛠️  Dev Dependencies:"
+check_package "@types/node" "20.0.0"
+check_package "typescript" "5.3.0"
+
+echo ""
+echo "✨ Check complete!"

package/.agents/skills/claude-agent-sdk/templates/basic-query.ts

@@ -0,0 +1,55 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+/**
+ * Basic Query Template
+ *
+ * Demonstrates:
+ * - Simple query execution
+ * - Model selection
+ * - Working directory
+ * - Basic message handling
+ */
+
+async function basicQuery() {
+  const response = query({
+    prompt: "Analyze the codebase and suggest improvements",
+    options: {
+      model: "claude-sonnet-4-5",  // or "haiku", "opus"
+      workingDirectory: process.cwd(),
+      allowedTools: ["Read", "Grep", "Glob"]
+    }
+  });
+
+  // Process streaming messages
+  for await (const message of response) {
+    switch (message.type) {
+      case 'system':
+        if (message.subtype === 'init') {
+          console.log(`Session ID: ${message.session_id}`);
+          console.log(`Model: ${message.model}`);
+        }
+        break;
+
+      case 'assistant':
+        if (typeof message.content === 'string') {
+          console.log('Assistant:', message.content);
+        }
+        break;
+
+      case 'tool_call':
+        console.log(`Executing tool: ${message.tool_name}`);
+        break;
+
+      case 'tool_result':
+        console.log(`Tool ${message.tool_name} completed`);
+        break;
+
+      case 'error':
+        console.error('Error:', message.error.message);
+        break;
+    }
+  }
+}
+
+// Run
+basicQuery().catch(console.error);