Help us improve
Share bugs, ideas, or general feedback.
From ai-project-init
Initialize any project (new or existing) for Claude Code. The skill spawns three subagents — project-analyzer reads the project and emits a structured analysis JSON; rules-author writes AGENTS.md, MANIFEST.md, .claude/rules/*, .claude/commands/*, .claude/agents/* from scratch using only what the analyzer surfaced; realism-verifier gates promotion by checking every staged file against real paths, real aliases, real packages, and a contamination blocklist. Atomic install via staging; idempotent upgrades. Works on UI design systems, backend APIs, libraries, mobile apps, CLIs, ML pipelines, and anything in between — the skill ships no opinion about what kind of project it lands on. Use when the user says "init this project for AI", "ai-project-init", "namesti claude rules", "init agents", "setup AGENTS.md", "scaffold backend rules", "init library project", "port my agent system", "/init ali u AGENTS.md", or otherwise wants Claude to be faster on this codebase.
npx claudepluginhub ivanmeda993/ai-project-init --plugin ai-project-initHow this skill is triggered — by the user, by Claude, or both
Slash command
/ai-project-init:ai-project-initThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Thin orchestrator. Three subagents do the substantive work; this file wires them together with the staging/marker/promote infrastructure.
assets/shared/AGENTS-root.mdassets/shared/CLAUDE.mdassets/shared/claude/agents/project-analyzer.mdassets/shared/claude/agents/realism-verifier.mdassets/shared/claude/agents/rules-author.mdassets/shared/claude/scripts/statusline.shassets/shared/claude/settings.jsonassets/shared/gitignore-patches.txtassets/shared/mcp.jsonevals/evals.jsonreferences/idempotency-and-rollback.mdreferences/manifest-seeding.mdreferences/manifest-shape-example.mdreferences/research-best-practices.mdreferences/research-fallback-urls.mdscripts/seed_manifest.pyscripts/substitute.pyscripts/upgrade.pyscripts/validate.pyFetches up-to-date library and framework documentation via Context7 MCP for setup questions, API references, and code examples.
Share bugs, ideas, or general feedback.
Thin orchestrator. Three subagents do the substantive work; this file wires them together with the staging/marker/promote infrastructure.
The skill ships no project opinions. There are no pre-built packs, no atomic-design vocabulary, no template variables that pretend a project's organization. Whatever rules, slash commands, agents, and MANIFEST schema land in the user's project, the rules-author wrote from scratch on top of evidence the project-analyzer surfaced from this specific codebase.
Phase 0 Mode + marker check (orchestrator only)
Phase 1 project-analyzer subagent → analysis JSON
Phase 2 Plan review with user (orchestrator only)
Phase 3 Copy generic shared assets (orchestrator + substitute.py)
Phase 4 rules-author subagent → staging tree
Phase 5 realism-verifier subagent → pass / fail report
↓ fail → Phase 4 again with corrections (max 2 retries)
Phase 6 validate.py structural gate (orchestrator)
Phase 7 Atomic promote to project (orchestrator)
The subagents live as installed agent definitions under .claude/agents/ once the skill itself is on the user's machine; before that, the orchestrator can locate them under <this-skill>/assets/shared/claude/agents/{project-analyzer,rules-author,realism-verifier}.md and invoke them with the Agent tool.
Before invoking the analyzer, gather:
| Input | How to get it |
|---|---|
| Target project root | Folder must be mounted. Use request_cowork_directory if not yet mounted. |
| Mode | Auto-detected in Phase 0; user confirms. |
| Language preference | If the user spoke Serbian, the rules-author writes descriptive prose in Serbian. If English, English. Pull from this conversation. |
| Existing AI configs | Listed by the analyzer — surfaced to the user before promote. |
Never guess paths, package names, or stack details. Those come from the analyzer.
Confirm the workspace is mounted. If not, request_cowork_directory.
Marker check. If <root>/.claude/.installed exists, the skill has run before. Read the marker JSON (version, installed_at, mode, analysis_summary, files_written) and offer upgrade / reinstall / verify-only / abort via AskUserQuestion. Default: upgrade. See references/idempotency-and-rollback.md.
Mode detection.
package.json (or equivalent) has only framework deps, no source folders, no existing .claude/, no AGENTS.md → likely new..claude/, OR existing AGENTS.md/MANIFEST.md → retrofit.Collision check on un-marked files. If AGENTS.md, CLAUDE.md, MANIFEST.md, or .mcp.json exist outside any marker's files_written list (or there's no marker), stop and ask per file. The user may have hand-edited.
Confirm the detected mode + outline the next phases. Match the user's language.
Spawn the project-analyzer subagent. Pass:
target_root = absolute project pathoutput_path = /tmp/ai-init-<random>/analysis.json (or any temp path outside the project)The analyzer is read-only. It walks manifests, configs, README, sample sources, existing AI configs, and emits a single JSON describing the project + its recommendations. See assets/shared/claude/agents/project-analyzer.md for the full contract.
When the analyzer finishes:
analysis.warnings includes a hard problem (no manifest at all, unparseable configs, no source code), surface to user and ask how to proceed.analysis.open_questions is non-empty, ask the user the most load-bearing 1–3 questions before continuing. Patch the analysis JSON with the answers.Optional research patch. When analysis.open_questions involves an unfamiliar framework version or library convention, run the 4-tier fallback chain in references/research-best-practices.md (Tavily MCP → Context7 → curated WebFetch allow-list → WebSearch → skip + record gap). Distill any findings into 2–5 bullets and append them to the analysis JSON under external_research. The skill never blocks waiting for research.
Show the user a concise digest:
analysis.summary).AskUserQuestion with options:
Repeat until approve or abort.
All writes go to <root>/.claude/.staging/ first. See references/idempotency-and-rollback.md.
The shared assets (assets/shared/) are truly generic — no atomic-design vocabulary, no UI-specific framing, no project-specific paths. They are:
| Source | Target | Purpose |
|---|---|---|
assets/shared/CLAUDE.md | <root>/CLAUDE.md | Re-export pointing at AGENTS.md |
assets/shared/mcp.json | <root>/.mcp.json | MCP servers (Context7 + optional research servers) |
assets/shared/claude/settings.json | <root>/.claude/settings.json | Minimal generic baseline — model, env, neutral permissions, statusline. No project-specific Bash/WebFetch entries; rules-author appends per-project allow-list entries derived from analysis.project.scripts and analysis.stack. |
assets/shared/gitignore-patches.txt | appended to <root>/.gitignore | Adds .claude/plans/, .claude/.cache/, .claude/.staging/, .claude/.staging-old/ |
assets/shared/claude/scripts/statusline.sh | <root>/.claude/scripts/statusline.sh | Status line script (chmod +x) |
These are the only files the orchestrator copies directly. Everything else (rules, commands, agents, AGENTS.md, MANIFEST.md) is authored by the rules-author.
The shared assets contain a small number of generic placeholders that substitute.py fills:
{{PROJECT_NAME}} — from analysis.project.name{{PACKAGE_MANAGER}} — from analysis.project.package_manager{{CLAUDE_MODEL}} — defaults to claude-sonnet-4-6 unless the user overridesAfter substitute, grep -r '{{[A-Z_]\+}}' over staging must return empty for the shared subset.
Spawn the rules-author subagent. Pass:
analysis_path — the analysis JSON from Phase 1 (with any user refinements + research notes)staging_root — <root>/.claude/.staging/target_root — the project root (read-only access for sample re-reads)The rules-author writes AGENTS.md, MANIFEST.md, .claude/rules/<topic>.md per recommended rule, .claude/commands/<name>.md per recommended command, .claude/agents/<name>.md per recommended agent. Every file is written from scratch with real paths, aliases, and packages — no template substitution. See assets/shared/claude/agents/rules-author.md for the full contract.
When rules-author finishes:
Spawn the realism-verifier subagent. Pass:
staging_root — <root>/.claude/.staging/target_root — the project rootanalysis_path — same JSON from Phase 1output_path — /tmp/ai-init-<random>/verification.jsonThe verifier is read-only. It walks every staged file and checks: paths exist (test -e), aliases resolve (against tsconfig.json or equivalent), packages exist in the project's manifest, command targets are realistic, no contamination vocabulary (literal blocklist + allowlist diff), no {{VAR}} leftovers, no broken cross-refs. See assets/shared/claude/agents/realism-verifier.md for the full contract.
Verdict handling:
verdict: "pass" — proceed to Phase 6.verdict: "fail" — re-spawn rules-author with the verifier's report attached as corrections_path. Allow up to 2 retries. After the second failure, abort the install and surface the remaining issues to the user; staging stays in .claude/.staging/ for inspection but nothing is promoted.The verifier may also surface warn-severity issues. Show those to the user before promote and let them choose proceed / re-author / abort.
Run scripts/validate.py against the staging directory:
python <skill>/scripts/validate.py --root <project-root> --staging --json
The script handles mechanical checks the verifier doesn't:
settings.json and .mcp.json are valid JSON{{VAR}} placeholders remaining anywhere (including subagent-authored files)CLAUDE.md references @AGENTS.mdIf exit code is non-zero, surface failing checks. If reparable (e.g. forgot chmod +x), fix in place; otherwise re-author.
Only after Phase 5 + Phase 6 both pass:
<root>/.claude/.staging/, compute its final destination.files_written, the user has hand-edited; ask before clobbering.<root>/.claude/.staging-old/<rel-path> and move the staged file into place.<root>/.gitignore if not already patched (idempotent — only add lines not already present).<root>/.claude/.installed with version, installed_at, mode, analysis_summary (a short slice of the analysis), files_written, template_hashes. See references/idempotency-and-rollback.md..claude/.staging-old/ for one run cycle so the user can compare; clean up on the next successful run.Final reply to the user: a short summary of what landed (rule count, command count, agent count, MANIFEST schema), the marker contents, and a ready-to-use trigger phrase from one of the slash commands.
For projects with existing source, scripts/seed_manifest.py can scan the layers the rules-author chose and propose entries to populate MANIFEST.md. This is after promote and opt-in — ask the user.
python <skill>/scripts/seed_manifest.py --root <project> --layers <layer-paths-from-analysis> --output /tmp/manifest-seed.json
The script is regex-based (TS/TSX export scanner; safe defaults for other languages). Surface entries in batches of ~10 via AskUserQuestion; the user approves/edits/skips per entry; the orchestrator appends approved entries under the right layer in MANIFEST.md. See references/manifest-seeding.md.
If the project's MANIFEST schema is non-TypeScript (Python, Go, Rust, etc.), seed_manifest.py reports it can't help and the user populates the manifest manually or via a future seed-script.
When Phase 0 finds an existing .installed marker and the user picked upgrade:
analysis_summary. Surface what changed to the user (new layers, new dependencies, new sample patterns).scripts/upgrade.py to compute three-way diff:
unchanged — skip.user_edited_only — preserve user copy; report.template_changed_only — propose overwrite.three_way — show diff and ask.added (new recommendation) — write to staging, run verifier on it.removed (no longer recommended) — propose deletion.See references/idempotency-and-rollback.md for the full upgrade contract.
Match the user's language. Serbian (Latin) and English mix freely; both are fine. Keep technical terms and identifiers in English (MANIFEST.md, staging, analyzer, verifier, tsconfig.json).
Match the user's brevity. The substantive content is in the rule files the rules-author wrote; the orchestrator's job is to install them, not re-explain them.
references/idempotency-and-rollback.md — install marker, staging directory, rollback contract, upgrade three-way diff.references/manifest-seeding.md — auto-scan algorithm + seed_manifest.py contract.references/research-best-practices.md — 4-tier fallback chain (Tavily → Context7 → WebFetch → WebSearch → skip).references/research-fallback-urls.md — curated WebFetch allow-list per stack.references/manifest-shape-example.md — one example of how a populated MANIFEST might look. Labelled as illustrative; not a template.The skill is intentionally script-light. Subagents do the substantive authoring; scripts handle only the mechanical, testable parts.
scripts/substitute.py — Phase 3 parameter substitution + <!-- if FLAG --> conditional fences. Used only for the small set of generic shared assets.scripts/seed_manifest.py — Optional Phase 8 retrofit MANIFEST seeding (regex TS/TSX scanner).scripts/validate.py — Phase 6 mechanical checks.scripts/upgrade.py — Upgrade-mode three-way diff per file.assets/shared/claude/agents/project-analyzer.md — read-only project introspector. Emits the analysis JSON.assets/shared/claude/agents/rules-author.md — staging-only authoring agent. Writes rules, commands, agents, AGENTS.md, MANIFEST.md from scratch using analyzer evidence.assets/shared/claude/agents/realism-verifier.md — read-only gate. Confirms paths exist, aliases resolve, packages are real, no contamination, no leftover placeholders.assets/shared/ holds the truly generic files that ship verbatim into every install. Anything project-specific is authored by the rules-author at install time.