using-claude

What this skill does

# Using Claude Code

## Overview

This skill provides guidance for working with Claude Code programmatically and understanding its features.

**What you'll learn:**

- **Model selection** - When to use Opus, Sonnet, or Haiku
- **Documentation access** - How to fetch latest Claude Code docs
- **Headless automation** - CI/CD, batch processing, scripted workflows
- **Agent SDK** - Building custom agents in Python and TypeScript
- **Debugging** - Testing hooks, plugins, and configurations
- **MCP servers** - Configuring and managing external tools
- **Snippet verification** - Ensuring snippets inject correctly

---

# Model Selection: Opus vs Sonnet vs Haiku

**Quick decision guide:**

| Use Case                                              | Model      | Why                                             |
| ----------------------------------------------------- | ---------- | ----------------------------------------------- |
| Complex reasoning, architecture design, code reviews  | **Opus**   | Highest intelligence, best at nuanced decisions |
| General coding, refactoring, debugging, documentation | **Sonnet** | Best balance of capability and speed            |
| Simple tasks, formatting, quick edits, explanations   | **Haiku**  | Fastest and most cost-effective                 |

## Detailed Guidance

### Use Opus When:
_Highest intelligence • Slower • Most expensive_

- **Architectural decisions** - Designing system architecture, evaluating trade-offs
- **Complex refactoring** - Large-scale code restructuring requiring deep understanding
- **Security audits** - Thorough security analysis and vulnerability detection
- **Code reviews** - Comprehensive review requiring contextual understanding
- **Research and exploration** - Open-ended investigation of unfamiliar codebases

**Example:**

```python
options = ClaudeAgentOptions(
    model="opus",  # Use highest intelligence
    max_turns=10
)
```

### Use Sonnet When (Default):
_Best balance • Fast • Moderate cost_

- **General development** - Day-to-day coding tasks
- **Debugging** - Finding and fixing bugs
- **Writing tests** - Creating test suites
- **Documentation** - Generating API docs, READMEs
- **Refactoring** - Standard code improvements
- **Feature implementation** - Building new functionality

**Example:**

```python
options = ClaudeAgentOptions(
    model="sonnet",  # Default choice for most tasks
    max_turns=5
)
```

### Use Haiku When:
_Fast • Cheapest • Good for simple tasks_

- **Simple edits** - Formatting, typo fixes, minor changes
- **Explanations** - Explaining code or concepts
- **Quick queries** - Simple questions that don't require deep analysis
- **Batch processing** - Processing many simple tasks where speed matters
- **Cost optimization** - When budget is a primary concern

**Example:**

```python
options = ClaudeAgentOptions(
    model="haiku",  # Fast and economical
    max_turns=3
)
```

---

# Documentation Access

**ALWAYS fetch the latest Claude Code documentation directly** when you need to implement any of the features.

## Available Documentation

```bash
# Core Features
curl -s https://docs.claude.com/en/docs/claude-code/hooks.md
curl -s https://docs.claude.com/en/docs/claude-code/memory.md
curl -s https://docs.claude.com/en/docs/claude-code/statusline.md
curl -s https://docs.claude.com/en/docs/claude-code/snippets.md
curl -s https://docs.claude.com/en/docs/claude-code/commands.md
curl -s https://docs.claude.com/en/docs/claude-code/configuration.md

# Agent SDK
curl -s https://docs.claude.com/en/api/agent-sdk/python.md
curl -s https://docs.claude.com/en/api/agent-sdk/typescript.md
curl -s https://docs.claude.com/en/api/agent-sdk/overview.md
```

## Usage Pattern

When user asks about Claude Code features:

1. **Identify relevant documentation** from the list above
2. **Fetch using curl** via the Bash tool
3. **Read and apply** the fetched content to answer accurately

---

# Quick Start Guides

## Headless Automation

**For CI/CD, batch processing, and scripted workflows.**

### Basic One-Shot Command

```bash
# Simple task
claude -p "analyze this code"

# With automation settings
claude --permission-mode bypassPermissions --max-turns 5 -p "run tests and fix failures"

# Read-only analysis
claude --allowed-tools "Read,Grep,Glob" -p "review codebase structure"
```

### Structured Output for Parsing

```bash
# JSON output for scripts
claude --output-format "stream-json" -p "task" | jq .

# Extract specific fields
claude --output-format "stream-json" -p "task" | \
  jq -r 'select(.type == "result") | .total_cost_usd'
```

### Session Continuation

```bash
# Capture session ID
SESSION=$(claude --debug -p "first task" 2>&1 | grep -o '"session_id":"[^"]*"' | cut -d'"' -f4)

# Continue conversation
claude -c "$SESSION" -p "follow-up task"
```

**📖 Complete guide:** See [reference/headless-patterns.md](reference/headless-patterns.md)
**💻 Working example:** See `scripts/headless-example.sh`

---

## Agent SDK (Python)

**For building custom agents programmatically.**

### Installation

```bash
pip install claude-agent-sdk
```

### Simple Query

```python
from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="What is 2+2?",
    options=ClaudeAgentOptions(
        model="sonnet",  # Choose model based on task complexity
        permission_mode="bypassPermissions",
        allowed_tools=[]
    )
):
    if message.type == "result":
        print(message.result)
```

### Continuous Conversation

```python
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async with ClaudeSDKClient(options=ClaudeAgentOptions(model="sonnet")) as client:
    await client.query("Remember: my name is Alice")
    async for msg in client.receive_response():
        if msg.type == "result": break

    await client.query("What's my name?")  # Remembers context
    async for msg in client.receive_response():
        if msg.type == "result": break
```

### Custom Tools

```python
from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("add", "Add two numbers", {"a": float, "b": float})
async def add(args):
    return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}

server = create_sdk_mcp_server(name="calc", tools=[add])
options = ClaudeAgentOptions(
    mcp_servers={"calc": server},
    allowed_tools=["mcp__calc__add"]
)
```

**📖 Complete guide:** See [reference/agent-sdk-patterns.md](reference/agent-sdk-patterns.md)
**💻 Working example:** See `scripts/sdk-python-example.py`

---

## Agent SDK (TypeScript)

**For building custom agents in Node.js/TypeScript.**

### Installation

```bash
npm install @anthropic-ai/claude-agent-sdk
```

### Simple Query

```typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const msg of query({
  prompt: "What is 2+2?",
  options: {
    model: "sonnet",
    permissionMode: "bypassPermissions",
  },
})) {
  if (msg.type === "result") console.log(msg.result);
}
```

### Custom Tools with Zod

```typescript
import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const addTool = tool(
  "add",
  "Add two numbers",
  z.object({ a: z.number(), b: z.number() }),
  async (args) => ({
    content: [{ type: "text", text: `Sum: ${args.a + args.b}` }],
  }),
);

const server = createSdkMcpServer({ name: "calc", tools: [addTool] });
```

**📖 Complete guide:** See [reference/agent-sdk-patterns.md](reference/agent-sdk-patterns.md)
**💻 Working example:** See `scripts/sdk-typescript-example.ts`

---

## Debugging Claude Code

**Testing hooks, plugins, snippets, and configurations.**

### Debug Mode

```bash
# Always use --debug when testing modifications
claude --debug -p "test prompt"

# Structured output with debug info
claude --debug --verbose --output-format "stream-json" -p "test" | jq .

# Debug logs saved to ~/.claude/debug/{session_id}/
ls ~/.claude/debug/
```

### Testing Hooks

```bash
# 1. Check hooks are registered