sync-docs

---
name: sync-docs
description: This skill should be used when the user asks to "sync docs", "update guides", "check docs against official", "refresh documentation", "compare guides to official docs", "update docs from upstream", or mentions syncing the SDK documentation guides with the official Claude Agent SDK documentation.
license: MIT
---

# Sync Documentation Guides

Synchronize the Elixir SDK documentation guides in `docs/guides/` with the official Claude Agent SDK documentation.

## Overview

Each guide in `docs/guides/` mirrors an official Agent SDK documentation page. The guides show **Elixir SDK equivalents** of the official examples — never Python or TypeScript. This skill provides a systematic workflow to detect content drift and update guides when the official docs change.

## Guide Conventions

All guides follow rules defined in `docs/guides/CLAUDE.md`. Key rules:

- Use full module names in prose (e.g., `ClaudeCode.Stream.final_result/1`)
- Use `ClaudeCode.query/2` for one-off examples; reserve `ClaudeCode.start_link/1` + `ClaudeCode.stream/3` for streaming/multi-turn
- Pattern match directly in `fn` clauses
- Follow official structure closely but prioritize idiomatic Elixir/OTP
- Include Elixir-only guidance where it applies
- Mark incomplete sections with callouts

Guide titles must be concise (1-3 words) for sidebar navigation. Prefer "File Checkpointing" over "Rewind file changes with checkpointing". Do NOT adopt verbose titles from the official docs — keep titles short even if the official page uses a longer name.

Each guide starts with:

```markdown
# Concise Title

Subtitle describing the guide.

> **Official Documentation:** This guide is based on the [official Claude Agent SDK documentation](https://platform.claude.com/docs/en/agent-sdk/PAGE). Examples are adapted for Elixir.
```

## Guide Inventory

Each guide maps to an official page at `https://platform.claude.com/docs/en/agent-sdk/{slug}`:

| Guide File | Official Slug |
|------------|--------------|
| `cost-tracking.md` | `cost-tracking` |
| `custom-tools.md` | `custom-tools` |
| `file-checkpointing.md` | `file-checkpointing` |
| `hooks.md` | `hooks` |
| `hosting.md` | `hosting` |
| `mcp.md` | `mcp` |
| `modifying-system-prompts.md` | `modifying-system-prompts` |
| `permissions.md` | `permissions` |
| `plugins.md` | `plugins` |
| `secure-deployment.md` | `secure-deployment` |
| `sessions.md` | `sessions` |
| `skills.md` | `skills` |
| `slash-commands.md` | `slash-commands` |
| `stop-reasons.md` | `stop-reasons` |
| `streaming-output.md` | `streaming-output` |
| `streaming-vs-single-mode.md` | `streaming-vs-single-mode` |
| `structured-outputs.md` | `structured-outputs` |
| `subagents.md` | `subagents` |
| `user-input.md` | `user-input` |

**Note:** `CLAUDE.md` is NOT a guide — it contains guide-writing rules. Do not replace it.

## Official Docs Cache

Fetched official docs are saved to `docs/guides/.official/{slug}.md` with metadata headers (source URL and fetch date). These files are checked into git so upstream changes are visible in diffs.

### Fetching Official Docs

Use the fetch script to download official docs as markdown:

```bash
# Fetch all official docs
./scripts/fetch-official-docs.sh

# Fetch specific docs
./scripts/fetch-official-docs.sh permissions sessions hooks

# List cached docs with fetch dates
./scripts/fetch-official-docs.sh --list

# Quick diff summary of cached vs local guides
./scripts/fetch-official-docs.sh --diff-all
```

The official site serves markdown when the URL ends with `.md`:
```
https://platform.claude.com/docs/en/agent-sdk/{slug}.md
```

**Always run the fetch script first** before comparing or updating guides. This ensures the `.official/` cache is current and creates a git-trackable record of what changed upstream.

## Workflow

### Step 1: Refresh Official Docs Cache

Run the fetch script to update the `.official/` cache:

```bash
./scripts/fetch-official-docs.sh           # all guides
./scripts/fetch-official-docs.sh {slug}    # specific guide(s)
```

Then check what changed since the last fetch:
```bash
git diff docs/guides/.official/
```

### Step 2: Compare Against Local Guide

Read both the cached official doc (`docs/guides/.official/{slug}.md`) and the local guide (`docs/guides/{slug}.md`). Compare:

1. **Structural differences** — New/removed/renamed sections
2. **Prose changes** — Updated descriptions, new paragraphs, changed wording
3. **New content** — Sections or subsections that don't exist locally
4. **Removed content** — Sections in local guide no longer in official (unless Elixir-specific)
5. **Link changes** — URLs that redirect to new locations
6. **Table updates** — New rows, columns, or changed values

### Step 3: Classify Changes

For each difference found, classify it:

- **Update** — Prose or structure changed in official; update local to match
- **Add** — New section in official; add Elixir-adapted version locally
- **Remove** — Section removed from official AND not Elixir-specific; remove locally
- **Keep** — Content only in local guide but is Elixir-specific (OTP patterns, LiveView examples, Elixir options); preserve it
- **Skip** — Python/TypeScript-specific content in official; do not add

### Step 4: Apply Changes

When applying changes:

- **Prose**: Mirror official wording but keep Elixir terminology (`:option_name` not `optionName`, module references not class references)
- **Code examples**: Translate to idiomatic Elixir following `docs/guides/CLAUDE.md` rules. Never copy Python/TypeScript examples directly.
- **Tables**: Match official structure, adapting values for Elixir (atoms instead of strings, Elixir types instead of Python/TypeScript types)
- **Links**: Use `platform.claude.com` URLs (final redirect destination). For cross-references between guides, use relative markdown links (`sessions.md`, `permissions.md`)
- **Elixir-specific sections**: Keep sections that provide Elixir/OTP value (e.g., LiveView integration, OTP supervision, GenServer patterns) even if not in official

### Step 5: Verify

After changes, verify:

- **Titles are concise** — 1-3 words for sidebar navigation (see conventions above)
- No Python/TypeScript code examples were introduced
- No references to non-existent modules or functions
- Internal cross-references between guides still resolve
- Guide still starts with the standard header format
- Elixir-specific sections are preserved

## Parallelization

For bulk syncs, first run `./scripts/fetch-official-docs.sh` to update all cached docs in one pass. Then dispatch parallel subagents — one per guide (or group). Each agent:

1. Reads the cached official doc from `docs/guides/.official/{slug}.md`
2. Reads the local guide from `docs/guides/{slug}.md`
3. Compares and applies changes directly
4. Reports a summary of changes made

## What NOT to Change

- `docs/guides/.official/*.md` — These are fetched upstream snapshots; only the fetch script should write them
- `docs/guides/CLAUDE.md` — This is the guide-writing rules file, not a guide
- Elixir-specific sections that add value (OTP patterns, LiveView, supervision trees, GenServer examples)
- Elixir code examples — never replace with Python/TypeScript
- Module references using full names (e.g., `ClaudeCode.Stream.final_result/1`)

## Common Mistakes to Avoid

These are recurring issues found during past syncs. Check for them before finalizing changes.

### Code examples must use real SDK APIs

Every function, struct, and option referenced in code examples must exist in the actual SDK. Do not invent APIs based on what the official docs describe — verify against the source code.

Common errors caught previously:

- `ClaudeCode.get_session_id/1` was moved to `ClaudeCode.Session.session_id/1`
- `:hooks` is a session-only option — it cannot be passed to `ClaudeCode.query/2`
- `ClaudeCode.Agent` fields `description` and `prompt` are optional (only `:name` is enforced)
- `setting_sources` accepts strings (`["user", "project"]`), not atoms (`[:user, :project]`)

### Do not remove SDK features to match official docs

The official docs may not list all permission modes, options, or features that the Elixir SDK supports. Do not remove documented SDK features just because they are absent from the official guide. For example, `:delegate` and `:dont_ask` permission modes are valid even if the official guide does not list them.

### Follow the IO.puts/IO.inspect rule strictly

The guide-writing rules say: "Don't add unnecessary `IO.puts`/`IO.inspect` calls just to prove the example works." When translating official examples that use `print()` or `console.log()`, do NOT add equivalent `IO.puts`/`IO.inspect` calls. Instead:

- Use `ClaudeCode.Stream` helpers (`final_text/1`, `final_result/1`, `collect/1`) to show results
- Show return values via comments or variable bindings
- `IO.write/1` is acceptable in streaming examples where it writes text deltas as they arrive
- `Logger.info/1` is acceptable in hook/audit examples where logging is the point

### Pattern match on structs, not bare maps

Use `%ClaudeCode.Message.ResultMessage{}` instead of `%{type: :result}`. Bare map matches are imprecise and can match unintended data.

### Include event type in streaming pattern matches

When matching partial message events, always include the event type:

```elixir
# Correct — explicit event type
%{event: %{type: :content_block_delta, delta: %{type: :text_delta, text: text}}}

# Wrong — missing event type check
%{event: %{delta: %{type: :text_delta, text: text}}}
```

### Test examples must reference modules defined in the guide

If a guide defines `MyApp.Tools` with a `get_weather` tool, test examples must test `get_weather`, not a different tool like `add` that was never defined.

### Struct fields must match actual defstruct

Before documenting struct fields in tables, verify them against the actual module's `defstruct`. Fields like `total_cost_usd` may be top-level struct fields, not nested inside a `usage` map.

### Adapter status atoms

The session lifecycle uses `:provisioning` (not `:initializing`) as the initial adapter status.