diff --git a/CLAUDE.md b/CLAUDE.md
index 601a1b7..03eec0a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Purpose
 
-UnrealDocGenerator is a tool (in development) for generating documentation from Unreal Engine C++ header files. The `samples/` directory contains representative Unreal Engine headers used as test inputs:
+UnrealDocGenerator is a tool for generating documentation from Unreal Engine C++ header files. The `samples/` directory contains representative Unreal Engine headers used as test inputs:
 
 - `samples/GeomUtils.h` — Small utility header (~6 KB): geometry/math helpers in `UE::AI` namespace
 - `samples/AIController.h` — Medium header (~22 KB): `AAIController` class with movement, behavior tree, perception, and blackboard integration
@@ -14,10 +14,11 @@ These samples cover a range of complexity (free functions, large classes, deeply
 
 ## Current State
 
-Implementation complete. Three Python files:
+Implementation complete. Three Python files + a Claude Code skill:
 - `ue_parser.py` — Parses UE headers into dataclasses
 - `ue_markdown.py` — Renders parsed data as Markdown (ultra-compact format, documented items only)
 - `generate.py` — CLI entry point; two-pass pipeline (parse-all → build type index → render-all)
+- `.claude/skills/ue-api/SKILL.md` — Claude Code skill; queries docs via `$UE_DOCS_PATH`, falls back to `$UE_ENGINE_ROOT` source headers
 
 ## Usage
 
diff --git a/README.md b/README.md
index f55edf9..8d0a991 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,57 @@
-# ue-ai-skill
+# UnrealDocGenerator
 
+Generates compact, agent-readable Markdown documentation from Unreal Engine C++ header files, plus a Claude Code skill for querying it.
+
+## How it works
+
+1. **Parse** — `ue_parser.py` scans UE headers into dataclasses using a position-based scanner (handles nested braces, macros, delegates, namespaces).
+2. **Render** — `ue_markdown.py` emits one `.md` per header: only items with C++ doc comments, no deprecated functions, compact enum format.
+3. **Index** — `generate.py` produces `type-index.txt`: a flat `TypeName: path/to/File.md` lookup for instant type resolution.
+
+## Usage
+
+```bash
+python generate.py <input> <output_dir>
+
+# Examples
+python generate.py /path/to/UnrealEngine/Engine/Source/ docs/
+python generate.py samples/AIController.h docs/
+```
+
+Output: one `.md` per `.h` + `docs/type-index.txt`.
+
+## Querying the docs (Claude Code skill)
+
+The repo includes a Claude Code skill at `.claude/skills/ue-api/` that answers Unreal Engine API questions using the generated docs, falling back to source headers when needed.
+
+Set two environment variables before starting Claude Code:
+
+```bash
+export UE_DOCS_PATH=/path/to/your/generated/docs
+export UE_ENGINE_ROOT=/path/to/UnrealEngine   # optional, for source fallback
+```
+
+The skill triggers automatically on UE-related questions. It resolves types via `$UE_DOCS_PATH/type-index.txt` in a single grep, reads the relevant `.md` files, and escalates to source headers for undocumented members, macros, or implementation details.
+
+**Example lookup:**
+```bash
+grep "^AController:" "$UE_DOCS_PATH/type-index.txt"
+# → AController: Engine/Classes/GameFramework/Controller.md
+```
+
+## Samples
+
+Three representative UE headers in `samples/` for testing:
+
+| File | Size | Contents |
+|---|---|---|
+| `GeomUtils.h` | ~6 KB | Free functions in `UE::AI` namespace |
+| `AIController.h` | ~22 KB | `AAIController` with movement, BT, perception |
+| `GameplayTagsManager.h` | ~43 KB | `UGameplayTagsManager` singleton, delegates, enums |
+
+## Output format
+
+- Functions: `` ##### `Name(params)` → `ReturnType` *(flags)* ``
+- Properties: `- \`name\` \`type\` *(flags)* — description`
+- Enums: table when values have descriptions, inline `Values: A, B, C` otherwise
+- Inheritance: `*Inherits*: [BaseClass](relative/path.md)` with corpus links