diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..e25450e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,122 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Purpose
+
+Personal Claude Code configuration vault containing reusable skills, custom agents, and system instructions. Referenced via `systemPromptPath` in Claude Code settings.
+
+## Structure
+
+```
+claude-vault/
+├── skills/           # Modular skills (SKILL.md files)
+│   ├── skill-creator/    # Meta-skill for generating new skills
+│   ├── django-model/     # Django model patterns
+│   ├── drf-api/          # DRF API patterns
+│   ├── celery-task/      # Celery task patterns
+│   ├── query-optimizer/  # N+1 query fixes
+│   ├── permissions/      # Permission system
+│   ├── solver/           # PuLP/Xpress optimization
+│   ├── testing/          # Test patterns
+│   ├── reviewer/         # Code review
+│   ├── doc-gen/          # Documentation generator
+│   ├── vault-janitor/    # Vault maintenance
+│   └── sparring-partner/ # Technical discussions
+├── agents/           # Custom agent configurations
+│   ├── league-planner-architect.md
+│   ├── django-architect.md
+│   ├── mip-optimization-xpress.md
+│   ├── cluster-compute-architect.md
+│   ├── plg-monitoring-architect.md
+│   ├── debugging-specialist.md
+│   └── code-reviewer.md
+├── system/           # Global instructions
+│   └── global-instructions.md
+├── knowledge/        # Context & preferences
+│   ├── preferences.md
+│   └── anti-patterns/
+├── memory/           # Learning & patterns
+│   ├── log/              # Session logs
+│   ├── snapshots/        # Status reports
+│   └── patterns.md       # Distilled best practices
+└── vault-index.md    # Navigation index (German)
+```
+
+## Configuration
+
+Add to `~/.claude/settings.json`:
+```json
+{
+  "global": {
+    "systemPromptPath": "/path/to/claude-vault/system/global-instructions.md"
+  }
+}
+
+# Erstelle einen Symlink für jeden Unterordner in deinem Vault-Skills-Verzeichnis
+ln -s /Absoluter/Pfad/zu/deinem/claude-vault/skills/* ~/.claude/skills/
+ln -s /Absoluter/Pfad/zu/deinem/claude-vault/agents/* ~/.claude/agents/
+claude mcp add vault --scope user -- npx -y @modelcontextprotocol/server-filesystem /Absoluter/Pfad/zu/deinem/claude-vault
+```
+
+## Skills Format
+
+```yaml
+---
+name: skill-name                      # lowercase, hyphens only
+description: Max 200 chars            # CRITICAL for auto-invocation
+argument-hint: <required> [optional]
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+```
+
+- `description` determines when Claude auto-detects skill usage
+- Invocation: `/skill-name`
+- Location: `~/.claude/skills/[name]/SKILL.md`
+
+## Agents Format
+
+```yaml
+---
+name: agent-name
+description: Multi-line description with usage examples
+model: sonnet|opus|haiku
+color: green|orange|blue
+---
+```
+
+## Language Rules
+
+- User interaction: German
+- Code comments: English
+- Style: Direct, no filler phrases, focus on code and facts
+
+## Priority Hierarchy
+
+1. Project-specific `CLAUDE.md` (highest)
+2. Skills from `/skills`
+3. `global-instructions.md`
+4. General training (lowest)
+
+## Key Workflows
+
+### Vault Maintenance (`/vault-janitor`)
+- Memory Distillation: Scan `/memory/log/`, extract patterns to `patterns.md`
+- Skill Audit: Verify YAML frontmatter, check for conflicts
+- Index Update: Keep `vault-index.md` current
+- Integrity Check: Find orphaned files
+
+### Skill Creation (`/skill-creator`)
+```
+/skill-creator [category] [technology] [skill-name]
+```
+Categories: `fullstack` (Django, React, Next.js, PostgreSQL, Celery, Redis) or `devops` (GitLab CI/CD, Docker, K3s, Hetzner, Prometheus, Grafana)
+
+## League-Planner vs Generic Django
+
+| Context | Agent | API Pattern |
+|---------|-------|-------------|
+| league-planner | `league-planner-architect` | `@api_view` function-based |
+| Generic Django | `django-architect` | ViewSets + Routers |
+
+**Important**: For league-planner projects, always use `@api_view` patterns, NOT ViewSets/Routers.
diff --git a/system/global-instructions.md b/system/global-instructions.md
index 4205d4d..d2c86c1 100644
--- a/system/global-instructions.md
+++ b/system/global-instructions.md
@@ -1,7 +1,7 @@
 ---
-name: global-instructions
+
+## name: global-instructions
 type: system
----
 
 # IDENTITÄT & MISSION
 
@@ -10,6 +10,7 @@ Du bist mein primärer KI-Agent. Dein Ziel ist es, unter Nutzung des "Claude-Vau
 # DER VAULT (DEINE QUELLE DER WAHRHEIT)
 
 Du hast permanenten Zugriff auf mein Git-Repository unter `~/Work/claude-vault`. 
+
 1. **Zuerst Prüfen:** Bevor du Code schreibst, scanne `/knowledge/anti-patterns/` und `/memory/patterns.md`.
 2. **Memory:** Schreibe nach jeder signifikanten Entscheidung einen Log in `/memory/log/`.
 3. **Snapshots:** Erstelle am Ende komplexer Sessions einen Status-Bericht in `/memory/snapshots/`.