claudekit/skills/init/SKILL.md

---
name: init
description: >
  Interactive setup wizard for claudekit. Scaffolds rules, modes, hooks, and MCP
  server configs into the user's project. Run /claudekit:init to configure.
  Use when setting up a new project with claudekit or reconfiguring an existing one.
user-invocable: true
argument-hint: "[--all] to skip prompts and install everything"
---

# Claudekit Init

Interactive setup wizard that scaffolds project-level configuration files into the user's `.claude/` directory.

## What It Generates

| Category | Files | Location |
|----------|-------|----------|
| Rules | api.md, frontend.md, migrations.md, security.md, testing.md | `.claude/rules/` |
| Modes | brainstorm.md, deep-research.md, default.md, implementation.md, orchestration.md, review.md, token-efficient.md | `.claude/modes/` |
| Hooks | auto-format, block-dangerous-commands, notify | `.claude/hooks/` + `settings.local.json` |
| MCP Servers | context7, sequential, playwright, memory, filesystem | `.mcp.json` |

---

## Wizard Flow

When invoked, ask the user **ONE question at a time**:

### Step 1: Rules

"Which rules do you want to install?"
- a) All rules (api, frontend, migrations, security, testing)
- b) Let me pick individually
- c) Skip rules

If (b), list each rule with a one-line description and let user select:
- **api.md** — REST API design conventions (naming, versioning, error responses)
- **frontend.md** — React/Next.js component patterns and file organization
- **migrations.md** — Database migration safety rules (backward compatibility, rollback)
- **security.md** — OWASP-aligned security rules (no hardcoded secrets, parameterized queries)
- **testing.md** — Test naming, coverage thresholds, mocking conventions

For each selected rule, read the template from `${CLAUDE_PLUGIN_ROOT}/skills/init/templates/rules/<name>.md` and write it to `.claude/rules/<name>.md`.

### Step 2: Modes

"Which behavioral modes do you want to install?"
- a) All modes (brainstorm, deep-research, default, implementation, orchestration, review, token-efficient)
- b) Let me pick individually
- c) Skip modes

If (b), list each mode with a one-line description:
- **brainstorm.md** — Creative exploration, divergent thinking, pro/con comparisons
- **deep-research.md** — Thorough analysis with citations and evidence
- **default.md** — Balanced standard behavior
- **implementation.md** — Code-focused, minimal prose, maximum productivity
- **orchestration.md** — Multi-task coordination and parallel work
- **review.md** — Critical analysis, finding issues, security focus
- **token-efficient.md** — Compressed output for cost savings (30-70%)

For each selected mode, read the template from `${CLAUDE_PLUGIN_ROOT}/skills/init/templates/modes/<name>.md` and write it to `.claude/modes/<name>.md`.

### Step 3: Hooks

"Which hooks do you want to install?"
- a) Auto-format (runs linter after Write/Edit)
- b) Block dangerous commands (prevents rm -rf /, force push main, etc.)
- c) Notifications (desktop notifications on completion)
- d) All of the above
- e) Skip hooks

For each selected hook:

1. Read the hook metadata from `${CLAUDE_PLUGIN_ROOT}/skills/init/templates/hooks.json`
2. Copy the hook script from `${CLAUDE_PLUGIN_ROOT}/scripts/<script>.cjs` to `.claude/hooks/<script>.cjs`
3. Merge the hook entry into `.claude/settings.local.json` (create if it doesn't exist)

Hook entry format for `settings.local.json`:
```json
{
  "hooks": {
    "<event>": [
      {
        "matcher": "<matcher>",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/<script>.cjs"
          }
        ]
      }
    ]
  }
}
```

If `settings.local.json` already has a `hooks` key, merge new entries into the existing structure — do not overwrite.

### Step 4: MCP Servers

"Which MCP servers do you want to configure?"
- a) Context7 (library documentation lookup)
- b) Sequential Thinking (multi-step reasoning)
- c) Playwright (browser automation)
- d) Memory (persistent knowledge graph)
- e) Filesystem (secure file operations)
- f) All of the above
- g) Skip MCP setup

For each selected server:

1. Read the server config from `${CLAUDE_PLUGIN_ROOT}/skills/init/templates/mcp-servers.json`
2. Detect platform: check if `process.platform === "win32"` or use Bash `uname` to determine OS
3. Select the correct config (`win32` or `posix` key)
4. Merge into the project's `.mcp.json` (create with `{"mcpServers": {}}` if it doesn't exist)

### Step 5: Summary

Print a summary table of everything installed:

```
Claudekit setup complete!

  Rules:   5 installed → .claude/rules/
  Modes:   7 installed → .claude/modes/
  Hooks:   3 installed → .claude/hooks/ + settings.local.json
  MCP:     5 configured → .mcp.json

Next steps:
  - Skills are available as /claudekit:<name> (13 user-invocable spine + 22 auto-trigger supporting = 35 total)
  - Agents are available as claudekit:<name> (24 agents)
  - Switch modes: "switch to brainstorm mode"
```

---

## --all Flag

If `$ARGUMENTS` contains `--all`, skip all prompts and install everything:
- All 5 rules
- All 7 modes
- All 3 hooks
- All 5 MCP servers

---

## Important Rules

- **NEVER overwrite existing files without asking.** If a target file already exists, ask: "[filename] already exists. Overwrite? (y/n)"
- **Create directories as needed.** If `.claude/rules/` doesn't exist, create it before writing files.
- **For hooks, always use `settings.local.json`** (not `settings.json`) — local is gitignored so hook config stays personal.
- **Use `${CLAUDE_PLUGIN_ROOT}`** to reference template files within the plugin.
- **Platform detection for MCP**: Windows uses `cmd /c npx`, macOS/Linux uses `npx` directly.

---

## Related Skills

- `writing-skills` — for creating custom skills after init
- `mode-switching` — for using the installed modes