opencode-skills-antigravity 1.0.4 → 1.0.6

package/bundled-skills/claude-api/python/agent-sdk/patterns.md

@@ -0,0 +1,319 @@
+# Agent SDK Patterns — Python
+
+## Basic Agent
+
+```python
+import anyio
+from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
+
+async def main():
+    async for message in query(
+        prompt="Explain what this repository does",
+        options=ClaudeAgentOptions(
+            cwd="/path/to/project",
+            allowed_tools=["Read", "Glob", "Grep"]
+        )
+    ):
+        if isinstance(message, ResultMessage):
+            print(message.result)
+
+anyio.run(main)
+```
+
+---
+
+## Custom Tools
+
+Custom tools require an MCP server. Use `ClaudeSDKClient` for full control, or pass the server to `query()` via `mcp_servers`.
+
+```python
+import anyio
+from claude_agent_sdk import (
+    tool,
+    create_sdk_mcp_server,
+    ClaudeSDKClient,
+    ClaudeAgentOptions,
+    AssistantMessage,
+    TextBlock,
+)
+
+@tool("get_weather", "Get the current weather for a location", {"location": str})
+async def get_weather(args):
+    location = args["location"]
+    return {"content": [{"type": "text", "text": f"The weather in {location} is sunny and 72°F."}]}
+
+server = create_sdk_mcp_server("weather-tools", tools=[get_weather])
+
+async def main():
+    options = ClaudeAgentOptions(mcp_servers={"weather": server})
+    async with ClaudeSDKClient(options=options) as client:
+        await client.query("What's the weather in Paris?")
+        async for message in client.receive_response():
+            if isinstance(message, AssistantMessage):
+                for block in message.content:
+                    if isinstance(block, TextBlock):
+                        print(block.text)
+
+anyio.run(main)
+```
+
+---
+
+## Hooks
+
+### After Tool Use Hook
+
+Log file changes after any edit:
+
+```python
+import anyio
+from datetime import datetime
+from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage
+
+async def log_file_change(input_data, tool_use_id, context):
+    file_path = input_data.get('tool_input', {}).get('file_path', 'unknown')
+    with open('./audit.log', 'a') as f:
+        f.write(f"{datetime.now()}: modified {file_path}\n")
+    return {}
+
+async def main():
+    async for message in query(
+        prompt="Refactor utils.py to improve readability",
+        options=ClaudeAgentOptions(
+            allowed_tools=["Read", "Edit", "Write"],
+            permission_mode="acceptEdits",
+            hooks={
+                "PostToolUse": [HookMatcher(matcher="Edit|Write", hooks=[log_file_change])]
+            }
+        )
+    ):
+        if isinstance(message, ResultMessage):
+            print(message.result)
+
+anyio.run(main)
+```
+
+---
+
+## Subagents
+
+```python
+import anyio
+from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage
+
+async def main():
+    async for message in query(
+        prompt="Use the code-reviewer agent to review this codebase",
+        options=ClaudeAgentOptions(
+            allowed_tools=["Read", "Glob", "Grep", "Agent"],
+            agents={
+                "code-reviewer": AgentDefinition(
+                    description="Expert code reviewer for quality and security reviews.",
+                    prompt="Analyze code quality and suggest improvements.",
+                    tools=["Read", "Glob", "Grep"]
+                )
+            }
+        )
+    ):
+        if isinstance(message, ResultMessage):
+            print(message.result)
+
+anyio.run(main)
+```
+
+---
+
+## MCP Server Integration
+
+### Browser Automation (Playwright)
+
+```python
+import anyio
+from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
+
+async def main():
+    async for message in query(
+        prompt="Open example.com and describe what you see",
+        options=ClaudeAgentOptions(
+            mcp_servers={
+                "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
+            }
+        )
+    ):
+        if isinstance(message, ResultMessage):
+            print(message.result)
+
+anyio.run(main)
+```
+
+### Database Access (PostgreSQL)
+
+```python
+import os
+import anyio
+from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
+
+async def main():
+    async for message in query(
+        prompt="Show me the top 10 users by order count",
+        options=ClaudeAgentOptions(
+            mcp_servers={
+                "postgres": {
+                    "command": "npx",
+                    "args": ["-y", "@modelcontextprotocol/server-postgres"],
+                    "env": {"DATABASE_URL": os.environ["DATABASE_URL"]}
+                }
+            }
+        )
+    ):
+        if isinstance(message, ResultMessage):
+            print(message.result)
+
+anyio.run(main)
+```
+
+---
+
+## Permission Modes
+
+```python
+import anyio
+from claude_agent_sdk import query, ClaudeAgentOptions
+
+async def main():
+    # Default: prompt for dangerous operations
+    async for message in query(
+        prompt="Delete all test files",
+        options=ClaudeAgentOptions(
+            allowed_tools=["Bash"],
+            permission_mode="default"  # Will prompt before deleting
+        )
+    ):
+        pass
+
+    # Plan: agent creates a plan before making changes
+    async for message in query(
+        prompt="Refactor the auth system",
+        options=ClaudeAgentOptions(
+            allowed_tools=["Read", "Edit"],
+            permission_mode="plan"
+        )
+    ):
+        pass
+
+    # Accept edits: auto-accept file edits
+    async for message in query(
+        prompt="Refactor this module",
+        options=ClaudeAgentOptions(
+            allowed_tools=["Read", "Edit"],
+            permission_mode="acceptEdits"
+        )
+    ):
+        pass
+
+    # Bypass: skip all prompts (use with caution)
+    async for message in query(
+        prompt="Set up the development environment",
+        options=ClaudeAgentOptions(
+            allowed_tools=["Bash", "Write"],
+            permission_mode="bypassPermissions",
+            allow_dangerously_skip_permissions=True
+        )
+    ):
+        pass
+
+anyio.run(main)
+```
+
+---
+
+## Error Recovery
+
+```python
+import anyio
+from claude_agent_sdk import (
+    query,
+    ClaudeAgentOptions,
+    CLINotFoundError,
+    CLIConnectionError,
+    ProcessError,
+    ResultMessage,
+)
+
+async def run_with_recovery():
+    try:
+        async for message in query(
+            prompt="Fix the failing tests",
+            options=ClaudeAgentOptions(
+                allowed_tools=["Read", "Edit", "Bash"],
+                max_turns=10
+            )
+        ):
+            if isinstance(message, ResultMessage):
+                print(message.result)
+    except CLINotFoundError:
+        print("Claude Code CLI not found. Install with: pip install claude-agent-sdk")
+    except CLIConnectionError as e:
+        print(f"Connection error: {e}")
+    except ProcessError as e:
+        print(f"Process error: {e}")
+
+anyio.run(run_with_recovery)
+```
+
+---
+
+## Session Resumption
+
+```python
+import anyio
+from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage
+
+async def main():
+    session_id = None
+
+    # First query: capture the session ID
+    async for message in query(
+        prompt="Read the authentication module",
+        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"])
+    ):
+        if isinstance(message, SystemMessage) and message.subtype == "init":
+            session_id = message.session_id
+
+    # Resume with full context from the first query
+    async for message in query(
+        prompt="Now find all places that call it",  # "it" = auth module
+        options=ClaudeAgentOptions(resume=session_id)
+    ):
+        if isinstance(message, ResultMessage):
+            print(message.result)
+
+anyio.run(main)
+```
+
+---
+
+## Custom System Prompt
+
+```python
+import anyio
+from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
+
+async def main():
+    async for message in query(
+        prompt="Review this code",
+        options=ClaudeAgentOptions(
+            allowed_tools=["Read", "Glob", "Grep"],
+            system_prompt="""You are a senior code reviewer focused on:
+1. Security vulnerabilities
+2. Performance issues
+3. Code maintainability
+
+Always provide specific line numbers and suggestions for improvement."""
+        )
+    ):
+        if isinstance(message, ResultMessage):
+            print(message.result)
+
+anyio.run(main)
+```

package/bundled-skills/claude-api/python/claude-api/README.md

@@ -0,0 +1,404 @@
+# Claude API — Python
+
+## Installation
+
+```bash
+pip install anthropic
+```
+
+## Client Initialization
+
+```python
+import anthropic
+
+# Default (uses ANTHROPIC_API_KEY env var)
+client = anthropic.Anthropic()
+
+# Explicit API key
+client = anthropic.Anthropic(api_key="your-api-key")
+
+# Async client
+async_client = anthropic.AsyncAnthropic()
+```
+
+---
+
+## Basic Message Request
+
+```python
+response = client.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=1024,
+    messages=[
+        {"role": "user", "content": "What is the capital of France?"}
+    ]
+)
+print(response.content[0].text)
+```
+
+---
+
+## System Prompts
+
+```python
+response = client.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=1024,
+    system="You are a helpful coding assistant. Always provide examples in Python.",
+    messages=[{"role": "user", "content": "How do I read a JSON file?"}]
+)
+```
+
+---
+
+## Vision (Images)
+
+### Base64
+
+```python
+import base64
+
+with open("image.png", "rb") as f:
+    image_data = base64.standard_b64encode(f.read()).decode("utf-8")
+
+response = client.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=1024,
+    messages=[{
+        "role": "user",
+        "content": [
+            {
+                "type": "image",
+                "source": {
+                    "type": "base64",
+                    "media_type": "image/png",
+                    "data": image_data
+                }
+            },
+            {"type": "text", "text": "What's in this image?"}
+        ]
+    }]
+)
+```
+
+### URL
+
+```python
+response = client.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=1024,
+    messages=[{
+        "role": "user",
+        "content": [
+            {
+                "type": "image",
+                "source": {
+                    "type": "url",
+                    "url": "https://example.com/image.png"
+                }
+            },
+            {"type": "text", "text": "Describe this image"}
+        ]
+    }]
+)
+```
+
+---
+
+## Prompt Caching
+
+Cache large context to reduce costs (up to 90% savings).
+
+### Automatic Caching (Recommended)
+
+Use top-level `cache_control` to automatically cache the last cacheable block in the request — no need to annotate individual content blocks:
+
+```python
+response = client.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=1024,
+    cache_control={"type": "ephemeral"},  # auto-caches the last cacheable block
+    system="You are an expert on this large document...",
+    messages=[{"role": "user", "content": "Summarize the key points"}]
+)
+```
+
+### Manual Cache Control
+
+For fine-grained control, add `cache_control` to specific content blocks:
+
+```python
+response = client.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=1024,
+    system=[{
+        "type": "text",
+        "text": "You are an expert on this large document...",
+        "cache_control": {"type": "ephemeral"}  # default TTL is 5 minutes
+    }],
+    messages=[{"role": "user", "content": "Summarize the key points"}]
+)
+
+# With explicit TTL (time-to-live)
+response = client.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=1024,
+    system=[{
+        "type": "text",
+        "text": "You are an expert on this large document...",
+        "cache_control": {"type": "ephemeral", "ttl": "1h"}  # 1 hour TTL
+    }],
+    messages=[{"role": "user", "content": "Summarize the key points"}]
+)
+```
+
+---
+
+## Extended Thinking
+
+> **Opus 4.6 and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is deprecated on both Opus 4.6 and Sonnet 4.6.
+> **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024).
+
+```python
+# Opus 4.6: adaptive thinking (recommended)
+response = client.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=16000,
+    thinking={"type": "adaptive"},
+    output_config={"effort": "high"},  # low | medium | high | max
+    messages=[{"role": "user", "content": "Solve this step by step..."}]
+)
+
+# Access thinking and response
+for block in response.content:
+    if block.type == "thinking":
+        print(f"Thinking: {block.thinking}")
+    elif block.type == "text":
+        print(f"Response: {block.text}")
+```
+
+---
+
+## Error Handling
+
+```python
+import anthropic
+
+try:
+    response = client.messages.create(...)
+except anthropic.BadRequestError as e:
+    print(f"Bad request: {e.message}")
+except anthropic.AuthenticationError:
+    print("Invalid API key")
+except anthropic.PermissionDeniedError:
+    print("API key lacks required permissions")
+except anthropic.NotFoundError:
+    print("Invalid model or endpoint")
+except anthropic.RateLimitError as e:
+    retry_after = int(e.response.headers.get("retry-after", "60"))
+    print(f"Rate limited. Retry after {retry_after}s.")
+except anthropic.APIStatusError as e:
+    if e.status_code >= 500:
+        print(f"Server error ({e.status_code}). Retry later.")
+    else:
+        print(f"API error: {e.message}")
+except anthropic.APIConnectionError:
+    print("Network error. Check internet connection.")
+```
+
+---
+
+## Multi-Turn Conversations
+
+The API is stateless — send the full conversation history each time.
+
+```python
+class ConversationManager:
+    """Manage multi-turn conversations with the Claude API."""
+
+    def __init__(self, client: anthropic.Anthropic, model: str, system: str = None):
+        self.client = client
+        self.model = model
+        self.system = system
+        self.messages = []
+
+    def send(self, user_message: str, **kwargs) -> str:
+        """Send a message and get a response."""
+        self.messages.append({"role": "user", "content": user_message})
+
+        response = self.client.messages.create(
+            model=self.model,
+            max_tokens=kwargs.get("max_tokens", 1024),
+            system=self.system,
+            messages=self.messages,
+            **kwargs
+        )
+
+        assistant_message = response.content[0].text
+        self.messages.append({"role": "assistant", "content": assistant_message})
+
+        return assistant_message
+
+# Usage
+conversation = ConversationManager(
+    client=anthropic.Anthropic(),
+    model="claude-opus-4-6",
+    system="You are a helpful assistant."
+)
+
+response1 = conversation.send("My name is Alice.")
+response2 = conversation.send("What's my name?")  # Claude remembers "Alice"
+```
+
+**Rules:**
+
+- Messages must alternate between `user` and `assistant`
+- First message must be `user`
+
+---
+
+### Compaction (long conversations)
+
+> **Beta, Opus 4.6 only.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text.
+
+```python
+import anthropic
+
+client = anthropic.Anthropic()
+messages = []
+
+def chat(user_message: str) -> str:
+    messages.append({"role": "user", "content": user_message})
+
+    response = client.beta.messages.create(
+        betas=["compact-2026-01-12"],
+        model="claude-opus-4-6",
+        max_tokens=4096,
+        messages=messages,
+        context_management={
+            "edits": [{"type": "compact_20260112"}]
+        }
+    )
+
+    # Append full content — compaction blocks must be preserved
+    messages.append({"role": "assistant", "content": response.content})
+
+    return next(block.text for block in response.content if block.type == "text")
+
+# Compaction triggers automatically when context grows large
+print(chat("Help me build a Python web scraper"))
+print(chat("Add support for JavaScript-rendered pages"))
+print(chat("Now add rate limiting and error handling"))
+```
+
+---
+
+## Stop Reasons
+
+The `stop_reason` field in the response indicates why the model stopped generating:
+
+| Value | Meaning |
+|-------|---------|
+| `end_turn` | Claude finished its response naturally |
+| `max_tokens` | Hit the `max_tokens` limit — increase it or use streaming |
+| `stop_sequence` | Hit a custom stop sequence |
+| `tool_use` | Claude wants to call a tool — execute it and continue |
+| `pause_turn` | Model paused and can be resumed (agentic flows) |
+| `refusal` | Claude refused for safety reasons — output may not match your schema |
+
+---
+
+## Cost Optimization Strategies
+
+### 1. Use Prompt Caching for Repeated Context
+
+```python
+# Automatic caching (simplest — caches the last cacheable block)
+response = client.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=1024,
+    cache_control={"type": "ephemeral"},
+    system=large_document_text,  # e.g., 50KB of context
+    messages=[{"role": "user", "content": "Summarize the key points"}]
+)
+
+# First request: full cost
+# Subsequent requests: ~90% cheaper for cached portion
+```
+
+### 2. Choose the Right Model
+
+```python
+# Default to Opus for most tasks
+response = client.messages.create(
+    model="claude-opus-4-6",  # $5.00/$25.00 per 1M tokens
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Explain quantum computing"}]
+)
+
+# Use Sonnet for high-volume production workloads
+standard_response = client.messages.create(
+    model="claude-sonnet-4-6",  # $3.00/$15.00 per 1M tokens
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Summarize this document"}]
+)
+
+# Use Haiku only for simple, speed-critical tasks
+simple_response = client.messages.create(
+    model="claude-haiku-4-5",  # $1.00/$5.00 per 1M tokens
+    max_tokens=256,
+    messages=[{"role": "user", "content": "Classify this as positive or negative"}]
+)
+```
+
+### 3. Use Token Counting Before Requests
+
+```python
+count_response = client.messages.count_tokens(
+    model="claude-opus-4-6",
+    messages=messages,
+    system=system
+)
+
+estimated_input_cost = count_response.input_tokens * 0.000005  # $5/1M tokens
+print(f"Estimated input cost: ${estimated_input_cost:.4f}")
+```
+
+---
+
+## Retry with Exponential Backoff
+
+> **Note:** The Anthropic SDK automatically retries rate limit (429) and server errors (5xx) with exponential backoff. You can configure this with `max_retries` (default: 2). Only implement custom retry logic if you need behavior beyond what the SDK provides.
+
+```python
+import time
+import random
+import anthropic
+
+def call_with_retry(
+    client: anthropic.Anthropic,
+    max_retries: int = 5,
+    base_delay: float = 1.0,
+    max_delay: float = 60.0,
+    **kwargs
+):
+    """Call the API with exponential backoff retry."""
+    last_exception = None
+
+    for attempt in range(max_retries):
+        try:
+            return client.messages.create(**kwargs)
+        except anthropic.RateLimitError as e:
+            last_exception = e
+        except anthropic.APIStatusError as e:
+            if e.status_code >= 500:
+                last_exception = e
+            else:
+                raise  # Client errors (4xx except 429) should not be retried
+
+        delay = min(base_delay * (2 ** attempt) + random.uniform(0, 1), max_delay)
+        print(f"Retry {attempt + 1}/{max_retries} after {delay:.1f}s")
+        time.sleep(delay)
+
+    raise last_exception
+```