Claude Code skill: bootstrap the harness for a new project/repo set

SKILL.md

name	project-init
description	Bootstrap Claude's harness for a project or set of repositories — clone them, map them with parallel subagents, then generate only the verified, high-leverage assets (CLAUDE.md, skills, agents, permissions, MCP config, memory). Use when starting work on a new/unfamiliar repo or when the user says "init", "bootstrap", or "set up Claude for this project".

Project Init — bootstrap the Claude harness for a codebase

Arguments: $ARGUMENTS — zero or more git URLs/paths. If empty, operate on the current directory.

Prime directives

1. Context is the scarce resource. Never read broadly yourself. All exploration goes through subagents (default model: haiku) that return conclusions, not file contents. You only Read a file directly when you already know its exact path and need its contents verbatim.
2. Every artifact must earn its context cost. CLAUDE.md and skill descriptions are loaded into every future session. A wrong or bloated artifact is worse than none. Write only what is durable, non-derivable, and verified.
3. Verify before documenting. Never write a command into CLAUDE.md or a skill unless you ran it (or a dry-run of it) and it worked. Subagents don't commit and their DONE is not proof — spot-check their claims.
4. Default to fewer artifacts. Built-in agents and skills cover most needs. Create a custom one only when the recon shows a repeated, project-specific workflow that built-ins handle badly.

Phase 0 — Intake

• Parse $ARGUMENTS. For each git URL, git clone it into the current directory (shallow --depth 50 is fine; full history isn't needed for bootstrap). Local paths are used in place.
• Multiple repos → treat the current directory as a workspace root: one shared CLAUDE.md at the root with per-repo sections, plus per-repo CLAUDE.md only if a repo has substantial unique conventions.
• Note anything already present: existing CLAUDE.md, .claude/, .mcp.json, AGENTS.md, .cursorrules, CONTRIBUTING.md. Existing assets are inputs to update, never blindly overwrite — diff intent, preserve what's still true.

Phase 1 — Recon (parallel subagent fan-out)

Dispatch in a single message (they're independent) one Explore agent per concern, per repo. model: haiku, breadth "medium" unless the repo is large. Each prompt must demand a distilled bullet answer with file paths, and explicitly forbid pasting file contents.

Agent	Question it answers
Toolchain	Languages, package manager, exact build / test / lint / format / run commands (from manifests, Makefile/Justfile, CI config), required env vars / secrets locations, dev-server ports
Architecture	Entry points, top-level layout, the 5–10 directories that matter, data flow in two sentences, where config lives
Conventions	Test layout & naming, CI gates that must pass, commit/PR conventions, codegen or generated dirs that must not be hand-edited, existing docs worth pointing at
Integrations	External services the code actually talks to (DBs, k8s, cloud, observability, APIs) — with evidence (client libs, connection strings, deploy manifests)

For >2 repos, run one combined recon agent per repo instead (all four questions in one prompt) to cap fan-out.

While agents run, do nothing else — wait, then cross-check: if two agents disagree (e.g., different test commands), resolve by reading the specific file they cite, not by re-exploring.

Phase 2 — CLAUDE.md (the foundation)

Write/update CLAUDE.md at the project root. Hard budget: ~60 lines. It is loaded every session — every line is a permanent tax.

Include, in this order:

1. One-paragraph purpose + architecture (pointers to dirs, not prose tours).
2. Verified commands: build, test (whole suite + single test), lint, run. Verbatim, copy-pasteable. Run each one first; mark any that need missing credentials/services as such instead of guessing.
3. Gotchas only: generated dirs, ordering constraints ("regenerate X before committing"), env quirks. No style guides the linter already enforces, no restating what ls reveals.

Exclude: file trees, dependency lists, anything derivable in one glance.

Phase 3 — Permissions & hooks

• Build a permissions.allow list in .claude/settings.json from the verified commands: the read-only and build/test/lint invocations Claude will run constantly (e.g. Bash(just test:*), Bash(cargo check:*)). Never allowlist anything that writes outside the repo, pushes, deploys, or deletes.
• Hooks: add only if recon found a mechanical invariant, e.g. a formatter that CI enforces → PostToolUse hook running it on edited files. If in doubt, skip — the user can ask later. (Complex settings edits: use the update-config skill if available rather than hand-editing.)

Phase 4 — Project skills

Create .claude/skills/<name>/SKILL.md only for workflows that are multi-step, repeated, and verified. Typical earners:

• run / deploy — if launching the app takes more than one obvious command.
• test-one — if running a single test needs non-obvious flags.
• Domain pipelines recon uncovered (codegen, migrations, release).

Rules: ≤50 lines each; exact commands you ran successfully; a one-line description that makes the trigger obvious (it's what future sessions see). Don't create skills that wrap a single command already in CLAUDE.md.

Phase 5 — Custom agents

Default: none — built-in Explore/Plan/general-purpose suffice. Create .claude/agents/<name>.md only when recon shows a recurring role needing baked-in project knowledge (e.g. a reviewer that must know a protocol spec's location, a migration-writer that must follow a template). Frontmatter: name, description (when to use), tools (minimum set), model: haiku unless the role needs deeper reasoning.

Phase 6 — MCP

Only if Phase 1 Integrations found live external services and an MCP server materially beats CLI access (structured queries vs. shelling out): add entries to project .mcp.json with env-var placeholders — never inline secrets. Otherwise document the CLI path in CLAUDE.md and move on. List candidates to the user; don't install speculatively.

Phase 7 — Memory

Save to auto-memory (if available this session) only facts that are non-obvious and don't belong in the repo: environment quirks of this machine, where credentials live, tribal knowledge the user stated. Never duplicate CLAUDE.md content into memory — memory is for what the repo can't record.

Phase 8 — Verify & report

1. Re-run the headline commands from CLAUDE.md one last time from a clean shell state. Fix or annotate anything that fails.
2. If anything in .claude/ was created, confirm valid syntax (JSON parses, skill frontmatter well-formed).
3. Final message to the user — lead with the outcome, then:
   • Assets created/updated (paths) and why each earned its place.
   • Verified command table (command → result).
   • What was deliberately not created, in one line (e.g. "no custom agents — built-ins cover this repo").
   • Open questions that need the user (missing creds, ambiguous deploy target) — as a short list at the end, never blocking mid-run.

Anti-goals

• No speculative "flexibility": no config options, agent roles, or skills for workflows nobody has needed yet.
• No 200-line CLAUDE.md. If you wrote one, cut it to 60.
• No exploring with your own Read/Grep across many files — that's what the fan-out is for.
• No committing. Leave changes in the working tree for the user to review.