claude-init

A Claude Code skill that bootstraps — or audits — the full .claude/ memory architecture of any project.

/init (the built-in slash command) creates a basic CLAUDE.md and stops there. claude-init goes the rest of the way: scaffolds rules, skills, agents, hooks, settings, context log, and validates the result against a strict 7-rule conformance checklist.

---

What it does

This skill operates in two modes, auto-detected from project state:

• Bootstrap mode (no .claude/ present): generates the full architecture from scratch, tailored to the detected project type (Node, Python, Rust, monorepo, etc.). Produces a complete, valid scaffolding the first time the user invokes Claude Code in a fresh repo.
• Audit mode (.claude/ already present): walks the existing scaffolding, flags drift from current best practices, and offers a structured diff of recommended changes — never destructive without confirmation.

The skill enforces seven non-negotiables on every output:

1. Never overwrite a file without explicit AskUserQuestion confirmation.
2. settings.json must validate as JSON (jq .).
3. CLAUDE.md must be ≤ 200 lines (otherwise adherence drops).
4. No content duplication between CLAUDE.md and any .claude/rules/ file.
5. Skill names are kebab-case, ≤ 64 characters.
6. Non-critical hook commands end with || true.
7. Security-critical hooks (PreToolUse blockers) never fail-open.

It also produces a per-project context-log.md so future Claude sessions know what was bootstrapped, when, and why.

---

When to use it

Trigger phrases:

• "set up Claude for this project"
• "bootstrap .claude/"
• "audit claude memory"
• "initialize project best practices"
• "scaffold my Claude Code setup"

Do NOT use when:

• You just want a basic CLAUDE.md — use the built-in /init instead.
• The project already has a hand-crafted, intentionally minimalist scaffold you want to preserve.
• You're working in a monorepo subdirectory; run it from the monorepo root.

---

Install

Via dotclaude (recommended)

claude-init is registered in hashbulla/dotclaude's skills.manifest.toml. Clone dotclaude and run bootstrap.sh — the skill is cloned and symlinked automatically.

Standalone

git clone git@github.com:hashbulla/claude-init-skill.git \
  ~/Desktop/AIEngineering/Skills/claude-init-skill

# Point Claude Code at the skill
ln -sfn ~/Desktop/AIEngineering/Skills/claude-init-skill/skills/claude-init \
  ~/.claude/skills/claude-init

Restart Claude Code (or run /skills reload); confirm with /skills list | grep claude-init.

---

How it works

The skill runs in context: fork mode — a dedicated subagent (project-memory-architect) carries the .claude/ design knowledge in isolated context. That subagent reads the project tree, infers project type, then either:

• Bootstraps: emits each artifact (CLAUDE.md, settings.json, rules/, hooks/, etc.) sequentially, validates each against the 7-rule checklist, and only writes after AskUserQuestion confirmation.
• Audits: produces a structured diff report — what's present, what's missing, what conflicts current best practice. Recommendations are ordered by impact, not alphabetical.

Both modes finish by writing a context-log.md entry documenting the operation, the choices made, and any open follow-ups.

---

Frontmatter reference

The skill's SKILL.md declares:

---
name: bootstrap-project          # slash-command name (called via /claude-init)
description: >                   # used for auto-discovery; lead with semantics
  Bootstraps or audits the full .claude/ memory architecture …
argument-hint: "[bootstrap|audit]"  # autocomplete hint in /-menu
user-invocable: true              # shows up in user's /-menu
context: fork                     # runs in isolated subagent context
agent: project-memory-architect   # subagent type used in fork mode
---

See skills/claude-init/SKILL.md for the full body.

---

Example invocations

Bootstrap a fresh project:

$ cd new-project && claude
> claude-init bootstrap

The skill detects no .claude/ and walks through a guided setup, asking before each artifact.

Audit an existing project:

> claude-init audit

Produces a diff report ranked by impact. You decide which changes to accept.

Explicit mode override:

> /claude-init audit

Forces audit mode even if .claude/ looks fresh.

---

Limitations

• Monorepo nuance: detection works at the root only. If you have per-package .claude/ dirs, the skill audits the root and the per-package ones must be handled separately.
• No automatic migration: when auditing, the skill recommends changes — it doesn't apply them. You stay in control.
• Single language detection: polyglot projects get a "best-fit" detection. If wrong, pass --lang <name> on invocation.
• Doesn't manage MCP server config: that lives in ~/.claude/mcp.json (user scope) and isn't part of the per-project scaffolding.

---

Roadmap

• Per-package monorepo support (audit each packages/*/)
• Recommended-skill suggestions based on project type (e.g., claude-api for Anthropic SDK projects)
• Idempotent re-bootstrap (re-running detects existing scaffolding and skips identical pieces)

---

License

MIT — see LICENSE.

---

Credits

Inspired by the discipline of shanraisshan/claude-code-best-practice and the project-memory-architect subagent pattern. Maintained as part of hashbulla/dotclaude.