/init

description: Bootstraps a project for Claude Code — generates CLAUDE.md and scoped docs from detected structure (single project, monorepo, or multi-repo workspace), installs auto-format hooks and test infrastructure, and reconciles existing docs against the source. Writes under .claude/ and subproject docs/. Replaces /init; safe to re-run.
disable-model-invocation: true

Initialize Project for Claude Code

File semantics

Three classes govern every file this skill writes. Later steps name the class instead of restating the rules.

• **Generated** — `.claude/hooks/*` and `.claude/docs/coding-guidelines.md`: verbatim templates (or fallback hooks), never user-authored. Always overwrite silently, regardless of audit status.
• **Customizable** — all `CLAUDE.md` files, `testing.md`, `styling.md`, `architecture.md`, `skill-writing-guidelines.md`: never silently overwrite. When the file exists, review-and-propose — compare against the template and detected state, apply only user-approved changes, preserve user-added sections.
• **settings.json** — always merge, never overwrite: preserve `permissions` and any other custom sections. Do not create it when no hooks are installed and it doesn't already exist.

New files of any class are written directly — no confirmation prompts. **Preserve when unsure:** content not derivable from the codebase is never discarded, not even to meet size targets. Mark content outdated only when source code directly contradicts it, and confirm with the user before removing user-added items. The same semantics apply to subproject docs in monorepos and to each repo's `.claude/` in multi-repo workspaces.

CLAUDE.md authoring rules

CLAUDE.md is loaded into every conversation, and Claude can already read the repository. So the budget goes to what reading the repository does not give it.

• **Spend it on gotchas.** Invariants a script or CI depends on, a command that must run from a specific directory, a file that looks editable but is generated, a convention the code deliberately breaks in one place, setup that fails in a non-obvious way, why a decision was made. Write fewer real ones rather than padding to a count — an empty Gotchas section is a valid outcome, and better than five lines of restated obviousness.
• **Never restate what the filesystem shows.** No directory listings, no "the stack is TypeScript" when `package.json` says so, no per-file roles. One line of identity and stack at the top is the whole allowance.
• Commands do belong here: which of a dozen scripts is the real build/test/lint entry point, with the detected package-manager prefix, is not inferable.
• Target <= 60 lines. The limit is soft: condense template-generated content first; if user-added content still pushes it over, exceed the limit and note the overage in the Step 7 summary.
• Only universally-applicable content — task-specific material distracts the model and degrades instruction-following.
• Progressive disclosure: the Documentation table routes a kind of change to the one doc that governs it, so a typo fix does not load the architecture doc.
• `file:line` references, not code snippets — snippets go stale.
• No code-style rules — the formatter hooks installed in Step 5 enforce style deterministically.
• Monorepo: root CLAUDE.md is an orchestrator — subproject table, workspace-wide commands, workspace-level gotchas only; each subproject's own CLAUDE.md is auto-discovered when working there and carries that package's gotchas. Shared guidelines stay at root `.claude/docs/`; `testing.md`/`styling.md`/`architecture.md` are scoped per subproject.
• Multi-repo workspace: each repo is fully self-contained (own `.claude/`); the parent CLAUDE.md is a lightweight local-only map — nothing is shared at root.

Step 1: Detect Project Context

Empty-directory check

A directory is **near-empty** when it contains at most `.git/`, `.gitignore`, `LICENSE`, and/or a stub `README.md` (under 5 lines of non-empty content), with no manifest files at any depth and no source directories (`src/`, `lib/`, `app/`, `pkg/`, `cmd/`). If empty or near-empty, use `AskUserQuestion` — header "Empty Project", question "This directory appears to be empty. Would you like to scaffold a new project?":

• **Scaffold new project** — "Set up a new project from scratch, then continue with full init setup"
• **Continue anyway** — "Proceed with init as-is (I'll add code myself later)"

On **Scaffold**: read and execute `$CLAUDE_PLUGIN_ROOT/skills/init/references/new-project-scaffolding.md`. If it returns an unsupported-stack signal, apply `$CLAUDE_PLUGIN_ROOT/skills/init/references/unsupported-stack-fallback.md` (steps 1-4) to find the stack's official scaffolding CLI; if that reaches graceful skip, instead create a minimal project manually (manifest + hello-world entry point + `.gitignore`) with user approval. After scaffolding, discard all prior detection state and restart Step 1's project detection from scratch.

Project detection (agent-assisted)

Read `$CLAUDE_PLUGIN_ROOT/skills/init/agents/project-analyzer.md` and launch 1 `general-purpose` agent with that prompt, prepended with the "Agent Constraints" section of `$CLAUDE_PLUGIN_ROOT/references/shared-agent-constraints.md`. Assemble the prompt per "Prompt assembly at dispatch time" in `$CLAUDE_PLUGIN_ROOT/references/agent-architecture.md` — the agent reads the detection references itself via the absolutized paths its prompt carries.

If the agent reports the structure as **ambiguous**, resolve via `AskUserQuestion`: ask the user to confirm whether this is a monorepo and identify subproject directories.

Checkpoint

Print the agent's results as a **Detection Summary**. If a field of its return format came back empty or absent (project name through Gotchas), fill that specific gap yourself — don't re-run the detection the agent just did. An empty **Gotchas** list is a legitimate answer, not a gap: fill it only if you already know of one this project has