# AI Skills Init

> Use this skill when bootstrapping a target repository to be ai-skills-aware — on the first run of any ai-skills workflow in a fresh repo, when adopting the ai-skills plugin in an existing repo, or after upgrading to a plugin version that adds new memory paths or templates, including when the user does not say "init" but asks to "set up" or "onboard" the repo — to detect codebase type, create CLAUDE.md + AGENTS.md scaffolding, initialize the .ai-skills-memory/ directory tree from L1 templates, and configure .gitignore. Idempotent — safe to re-run. Accepts `--codebase-type <type>` and `--overwrite`. Not for re-initializing only memory — use `/memory-init` instead.

- Skill: `avav25/ai-skills-init` (Agent Skill)
- Install (CLI): `npx skillmds@latest add avav25/ai-skills-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/avav25/ai-skills-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: avav25 (https://skillmd.com/u/avav25)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/avav25/ai-skills-init

---


# /ai-skills-init — Bootstrap a Target Repository

One-time (or re-runnable) setup for a target repo. Detects codebase type, scaffolds `CLAUDE.md` + `AGENTS.md`, creates `.ai-skills-memory/` tree from L1 templates, appends `.gitignore` rules. Idempotent.

## When to use

- First run of any ai-skills workflow on a fresh repo
- Adopting the ai-skills plugin in an existing repo (new for the team)
- After upgrading the plugin to a version that adds new memory paths or templates

## Not for

- Re-initializing only memory (use `/memory-init` for that)
- Modifying an existing `CLAUDE.md` (manual edit — this skill never overwrites without `--overwrite`)

## Invocation

```
/ai-skills-init
/ai-skills-init --codebase-type python-flask
/ai-skills-init --overwrite                  # rare; only when CLAUDE.md is empty/stale
```

## Arguments

| Flag | Default | Effect |
|---|---|---|
| `--codebase-type` | auto-detect | `python-flask`, `python-fastapi`, `nodejs-express`, `nodejs-nextjs`, `astro`, `sveltekit`, `remix`, `nodejs-bun`, `deno`, `java-spring`, `kotlin-spring`, `kotlin-ktor`, `elixir-phoenix`, `go`, `ruby-rails`, `rust`, `dotnet`, `mixed`, `generic` |
| `--overwrite` | false | If `CLAUDE.md` already exists, OVERWRITE with fresh scaffold. Default: skip if exists |

## Output

- `<repo>/CLAUDE.md` — scaffolded with codebase type, empty sections for user
- `<repo>/AGENTS.md` — empty template (optional, for team customization of agents per-repo)
- `<repo>/.ai-skills-memory/` directory tree (per `/memory-init` spec)
- `<repo>/.gitignore` — appended `.ai-skills-memory/` exclusion rule (if not present)

## Agent roster

| Agent | Model | Effort | Tools | Role |
|---|---|---|---|---|
| `scaffolder` (internal — resolves to `software-engineer` with restricted tools) | haiku | low | Write, Read, Glob | Detects codebase type, generates scaffolds |

## Pipeline

```
┌─ Auto-detect codebase type:
│  └─ Check for: Pipfile, pyproject.toml, package.json, pom.xml,
│     build.gradle.kts, go.mod, Cargo.toml, Gemfile, mix.exs,
│     *.csproj, astro.config.mjs, svelte.config.js, remix.config.js,
│     bun.lockb / bunfig.toml, deno.json / deno.jsonc / deps.ts
│     Multiple matches → mixed; none → generic
│
├─ Generate CLAUDE.md scaffold:
│  └─ Sections: Overview, Tech Stack, Directory Layout, Key Decisions,
│     Constraints, Getting Started
│     Pre-fill: tech stack (detected), codebase type
│     Leave blank for user: business context, architectural decisions
│
├─ Generate (optional) AGENTS.md:
│  └─ List all plugin agents enumerated from `plugin/agents/`
│     (count auto-tracks future additions) with brief role descriptions
│     User can override / add per-repo customization
│
├─ Create .ai-skills-memory/ tree (delegate to /memory-init logic):
│  ├─ .gitignore (from plugin/memory/templates/ai-skills-memory.gitignore)
│  ├─ .committed/ subdir with README + allowlist-extensions
│  ├─ config.json (per-repo override stub for token caps + RALF caps)
│  ├─ learnings.md (empty template)
│  ├─ runs.jsonl, errors.log, redactions.log (touch-create)
│  └─ workflow subdirs: designs/, develop/, bugfix/, refactor/,
│     migrate/, spikes/, security-audits/, env-reports/, docs/
│
├─ Update root .gitignore:
│  └─ Add .ai-skills-memory/ rule (if not already present);
│     also add `.committed/` is tracked exception (negation rule)
│
└─ Print scaffold creation summary + next steps
   ("Fill business context in CLAUDE.md, run /feature-design or /develop")
```

No RALF — scaffolding is one-pass; idempotent so safe to re-run.

## Codebase-type detection markers + template deltas

| Type | Markers | CLAUDE.md template deltas |
|---|---|---|
| `astro` | `astro.config.mjs`; `package.json` has `"astro"` dep | Primary role: `frontend-engineer`. Note SSG/SSR/hybrid mode. Likely Tailwind / shadcn-ui. Playwright for E2E |
| `sveltekit` | `svelte.config.js`; `package.json` has `"@sveltejs/kit"` dep | Primary role: `frontend-engineer`. Note SSR/SSG modes. Tailwind / shadcn-ui likely. Playwright for E2E |
| `remix` | `remix.config.js`; `package.json` has `"@remix-run/*"` deps | Primary role: `frontend-engineer`. Note SSR-first full-stack. Tailwind / shadcn-ui likely. Playwright for E2E |
| `nodejs-bun` | `bun.lockb` or `bunfig.toml` | Use `bunx` over `npx`. Native TypeScript (no `tsc` step). Native test runner (`bun test`) |
| `deno` | `deno.json` / `deno.jsonc`; `deps.ts` | Use `deno run` / `deno test`. Built-in TS. Document the permissions model (`--allow-net`, `--allow-read`, …) |
| `elixir-phoenix` | `mix.exs` with `:phoenix` dep | Primary role: `elixir-engineer` (NOT `software-engineer` for stack-specific work). ExUnit for tests. `mix release` for deploy |
| `kotlin-spring` | `build.gradle.kts` + `kotlin` plugin + Spring deps | Primary role: `java-engineer`. Gradle Kotlin DSL. JUnit + Kotlin idioms |
| `kotlin-ktor` | `build.gradle.kts` + `io.ktor` deps | Primary role: `java-engineer`. Ktor coroutines model. H2 + Exposed common stack |

## Hard rules

- **Never overwrite `CLAUDE.md` without `--overwrite`** — refuse with: "CLAUDE.md exists; pass --overwrite to replace"
- **`pre-tool-use-committed-write.py` hook applies** to any `.committed/` writes (committed-allowlist enforcement)
- **Idempotent** — re-running on a fully-set-up repo is a no-op + report

## Eval rubric

Pointer: `plugin/eval/judge-rubrics/ai-skills-init.md` (B10).

Dimensions:
1. **Correctness** — scaffold matches detected codebase type
2. **Completeness** — all expected directories and files present
3. **Clarity** — placeholder comments are helpful
4. **No conflicts** — respects existing `CLAUDE.md` if `--overwrite` not set
5. **Gitignore safety** — no important files accidentally ignored

Pass: avg ≥ 4.0, no dimension < 3.

## Memory writes

| Layer | When | Shape |
|---|---|---|
| L4 | After complete | `.ai-skills-memory/init-summary.md` — timestamp, plugin version, codebase type detected, files created/skipped |

## Failure modes

- **Codebase type ambiguous (multiple stacks detected):** scaffolder defaults to `mixed`; user can specify with `--codebase-type`
- **CLAUDE.md exists and `--overwrite` not set:** skip CLAUDE.md creation; report exists; continue with `/memory-init` portion
- **Write permission denied:** escalate to user with clear path; suggest checking repo writeability or running with elevated permissions
- **Plugin not installed properly (`${CLAUDE_PLUGIN_ROOT}` empty):** error with: "Plugin templates not found. Verify plugin install with `/plugin status ai-skills`"

## Observability events

- `workflow_start` — ai-skills-init
- `codebase_type_detected` — detected type
- `scaffold_created` — files/dirs created (vs skipped)
- `workflow_end` — `COMPLETE`

## Integration

- **Reads templates from**: `${CLAUDE_PLUGIN_ROOT}/memory/templates/` (7 files for memory skeleton). PII pattern file is at `${CLAUDE_PLUGIN_ROOT}/hooks/scripts/pii-patterns.txt` (loaded by hooks, not copied during init); project extension at `.ai-skills-memory/.committed/pii-patterns.txt` (created on demand).
- **Schemas**: `plugin/schemas/spawn-payload.schema.json` (G7 — even though `scaffolder` is internal, payload still embedded for consistency)
- **Sub-workflow**: `/memory-init` (the memory portion of the bootstrap)
- **Companions**: `/plugin-doctor` (verify install before init), `/context-load` (after init, validate context loads correctly)
- **Rules**: `memory-discipline` (write rules per layer), `untrusted-content-wrapping` (G1 wrap on existing CLAUDE.md if `--overwrite` reads it for backup)
- **Hooks**: `pre-tool-use-committed-write.py` (committed-allowlist enforcement on `.committed/` writes), `session-start-context.py` (will read newly-created CLAUDE.md on next session)