diff --git a/docs/index.md b/docs/index.md
index b1b86c84..6a33e80d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -114,10 +114,12 @@ Core uses `.core/` directory for project configuration:
 - [Configuration](configuration.md) - All config options
 - [Examples](examples/) - Sample configurations
 
-## Framework
+## Claude Code Skill
 
-Core also provides a Go framework for building desktop applications:
+Install the skill to teach Claude Code how to use the Core CLI:
 
-- [Framework Overview](framework/overview.md)
-- [Services](framework/services.md)
-- [Lifecycle](framework/lifecycle.md)
+```bash
+curl -fsSL https://raw.githubusercontent.com/host-uk/core/main/.claude/skills/core/install.sh | bash
+```
+
+See [skill/](skill/) for details.
diff --git a/docs/skill/index.md b/docs/skill/index.md
new file mode 100644
index 00000000..40ae3ad2
--- /dev/null
+++ b/docs/skill/index.md
@@ -0,0 +1,35 @@
+# Claude Code Skill
+
+The `core` skill teaches Claude Code how to use the Core CLI effectively.
+
+## Installation
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/host-uk/core/main/.claude/skills/core/install.sh | bash
+```
+
+Or if you have the repo cloned:
+
+```bash
+./.claude/skills/core/install.sh
+```
+
+## What it does
+
+Once installed, Claude Code will:
+
+- Auto-invoke when working in host-uk repositories
+- Use `core` commands instead of raw `go`/`php`/`git` commands
+- Follow the correct patterns for testing, building, and releasing
+
+## Manual invocation
+
+Type `/core` in Claude Code to invoke the skill manually.
+
+## Updating
+
+Re-run the install command to update to the latest version.
+
+## Location
+
+Skills are installed to `~/.claude/skills/core/SKILL.md`.