diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..f5d67630
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,43 @@
+# swe-skills
+
+This is the swe-skills project — a collection of production-grade engineering skills for AI coding agents.
+
+## Project Structure
+
+```
+skills/       → Core skills (SKILL.md per directory)
+agents/       → Reusable agent personas (code-reviewer, test-engineer, security-auditor)
+hooks/        → Session lifecycle hooks
+.claude/commands/ → Slash commands (/spec, /plan, /build, /test, /review, /ship)
+references/   → Supplementary checklists (testing, performance, security, accessibility)
+docs/         → Setup guides for different tools
+```
+
+## Skills by Phase
+
+**Define:** spec-driven-development
+**Plan:** planning-and-task-breakdown
+**Build:** incremental-implementation, context-engineering, frontend-ui-engineering, api-and-interface-design
+**Verify:** test-driven-development, browser-testing-with-devtools, debugging-and-error-recovery
+**Review:** code-review-and-quality, security-and-hardening, performance-optimization
+**Ship:** git-workflow-and-versioning, ci-cd-and-automation, documentation-and-adrs, shipping-and-launch
+
+## Conventions
+
+- Every skill lives in `skills/<name>/SKILL.md`
+- YAML frontmatter with `name` and `description` fields
+- Description starts with "Use when" and describes triggering conditions only
+- Every skill has: Overview, When to Use, Process, Common Rationalizations, Red Flags, Verification
+- References are in `references/`, not inside skill directories
+- Supporting files only created when content exceeds 100 lines
+
+## Commands
+
+- `npm test` — Not applicable (this is a documentation project)
+- Validate: Check that all SKILL.md files have valid YAML frontmatter with name and description
+
+## Boundaries
+
+- Always: Follow the skill-anatomy.md format for new skills
+- Never: Add skills that are vague advice instead of actionable processes
+- Never: Duplicate content between skills — reference other skills instead
diff --git a/hooks/hooks.json b/hooks/hooks.json
new file mode 100644
index 00000000..06af3150
--- /dev/null
+++ b/hooks/hooks.json
@@ -0,0 +1,8 @@
+{
+  "hooks": [
+    {
+      "type": "SessionStart",
+      "command": "bash hooks/session-start.sh"
+    }
+  ]
+}