diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..598e9d0
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,71 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Repo Is
+
+Taste Skill is a collection of portable **Agent Skills** — instruction files (SKILL.md) that AI coding agents load to produce premium, anti-generic frontend UIs. It is not a code library or npm package; it is a content repository of prompts and design directives.
+
+Each skill in `skills/<folder>/SKILL.md` is a standalone instruction file. They install via:
+
+```bash
+npx skills add https://github.com/Leonxlnx/taste-skill
+npx skills add https://github.com/Leonxlnx/taste-skill --skill "design-taste-frontend"
+```
+
+There is no build step, test suite, or package.json. The primary deliverables are the SKILL.md files themselves.
+
+## Repo Structure
+
+- **`skills/`** — One subfolder per skill, each containing a `SKILL.md`. This is the core content of the repo.
+- **`skills/llms.txt`** — One-line descriptions of all skills; used as a discovery manifest.
+- **`skill.sh`** — Local registry mapping short names (e.g. `taste-skill`) to their SKILL.md paths. Run with `source ./skill.sh <skill-name>` to print the path.
+- **`research/`** — Background research (LLM laziness, output truncation) that shaped the skills. Markdown only.
+- **`.github/copilot-instructions.md`** — GitHub Copilot global behavior rules for this repo.
+
+## Skill Inventory
+
+| Folder | Install name | Kind |
+|--------|-------------|------|
+| `taste-skill` | `design-taste-frontend` | Implementation (v2 experimental, current default) |
+| `taste-skill-v1` | `design-taste-frontend-v1` | Implementation (v1, preserved for backward compat) |
+| `gpt-tasteskill` | `gpt-taste` | Implementation (stricter, GPT/Codex-oriented) |
+| `image-to-code-skill` | `image-to-code` | Implementation (image → analyze → code pipeline) |
+| `redesign-skill` | `redesign-existing-projects` | Implementation (audit-first redesign of existing codebases) |
+| `soft-skill` | `high-end-visual-design` | Implementation (polished, calm, premium aesthetic) |
+| `output-skill` | `full-output-enforcement` | Implementation (prevents AI output truncation) |
+| `minimalist-skill` | `minimalist-ui` | Implementation (editorial/Notion-style) |
+| `brutalist-skill` | `industrial-brutalist-ui` | Implementation (Swiss type, mechanical aesthetic) |
+| `stitch-skill` | `stitch-design-taste` | Implementation (generates DESIGN.md for Google Stitch) |
+| `imagegen-frontend-web` | `imagegen-frontend-web` | Image-generation only (website section comps) |
+| `imagegen-frontend-mobile` | `imagegen-frontend-mobile` | Image-generation only (mobile screen concepts) |
+| `brandkit` | `brandkit` | Image-generation only (brand identity boards) |
+
+## Key Design Conventions (Enforced Across Skills)
+
+These conventions appear across multiple skills and must be preserved when editing SKILL.md files:
+
+- **Dial system**: `DESIGN_VARIANCE`, `MOTION_INTENSITY`, `VISUAL_DENSITY` (1–10 each). The taste-skill v2 default is 8 / 6 / 4.
+- **No em-dashes** (`—`) anywhere on generated pages — this is the most-banned AI "tell". Use hyphens or restructure.
+- **No generic fonts**: Inter, Roboto, Arial, Open Sans are banned across all skills.
+- **No placeholder code**: `output-skill` enforces complete generation. The manifesto in `.github/copilot-instructions.md` applies repo-wide.
+- **Motion standard**: Spring physics (not linear easing). Motion library (`motion/react`, Framer Motion rebrand) preferred; GSAP for scroll pinning/scrubbing.
+- **Section numbering eyebrows** (`00 / INDEX`, `001 · Capabilities`) are banned in v2.
+- **Tailwind v4** is the default for taste-skill v2; v3 only for existing projects that require it.
+
+## Adding or Modifying a Skill
+
+1. Create or edit `skills/<folder>/SKILL.md` with YAML frontmatter at the top:
+   ```yaml
+   ---
+   name: install-name-here
+   description: One-sentence description shown in discovery.
+   ---
+   ```
+2. Update `skills/llms.txt` with a matching one-line entry (`install-name: description`).
+3. If the skill is new, add it to the `SKILLS` map in `skill.sh`.
+4. Update the skills table in `README.md` and add a `CHANGELOG.md` entry.
+
+## Copilot / AI Behavior in This Repo
+
+The `.github/copilot-instructions.md` sets repo-wide behavior: no generic UI, proportional `clamp()` spacing, spring physics for all animations, complete implementations (no TODOs), and read localized `SKILL.md` files for deep style configuration.