# AI Dev Setup > Bootstrap and optimize a repository for AI-assisted development. Analyzes the repo, detects existing AI tooling, researches and curates candidate artifacts (skills, prompts, agent instructions, SDD scaffolding, MCP servers, token/context optimizers like Serena/RTK, and agent/IDE integrations for Claude Code / Copilot / Codex), asks the user for approval on each meaningful decision, then installs, configures, and validates the chosen setup. Trigger this whenever the user wants to set up, bootstrap, harden, audit, upgrade, or "make this repo better for Claude / agents / Copilot / Codex" — including phrasings like "configure this project for AI", "install an MCP server here", "add Spec Kit", "add Serena", "add token optimization", "review our agentic setup", or "what AI tooling should this repo have". Also trigger when the user asks to discover or install reusable skills (skills.sh, find-skills) as part of a larger setup effort. Prefer this skill over ad-hoc installation even when the user names a single compone - Skill: `thiagopanini/ai-dev-setup-2` (Agent Skill, multi-file: 21 files) - Install (CLI): `npx skillmds@latest add thiagopanini/ai-dev-setup-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/thiagopanini/ai-dev-setup-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: ThiagoPanini (https://skillmd.com/u/thiagopanini) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/thiagopanini/ai-dev-setup-2 --- # AI Dev Setup Turn a repository into a tuned AI-assisted development environment — safely, modularly, and in a way the maintainer still owns. Most repos either have nothing (greenfield, unopinionated) or a patchwork of agent files, MCP snippets, and half-configured tools. Both cases benefit from the same discipline: **look first, decide with the user, install small, validate, leave a record**. This skill is that discipline, plus a curated map of what to consider. ## When to use - User asks to configure, bootstrap, or harden AI tooling in a repo. - User names a specific component (Serena, RTK, Spec Kit, an MCP server, a skill) but the install should be done safely in the context of the whole setup. - User wants an audit/recommendation pass without changes. - User wants to discover reusable skills for this repo. ## When NOT to use - Writing product code, fixing bugs, running tests — those are the work this skill is meant to make *easier*, not replace. - Pure documentation authoring unrelated to agent context files. - Single-file tweaks the user has already decided on (just do the edit). ## Modes The skill operates in one of four modes. Ask the user which one if it's not obvious from the request. | Mode | When | Behavior | |------|------|----------| | **audit** | "review", "what's missing", "recommend" | Detect + research + report. **No writes.** | | **bootstrap** | Greenfield or near-empty repo | Propose a full baseline; install only approved pieces. | | **optimize** | Repo already has AI setup | Inventory, find gaps/overlap, propose targeted changes. | | **selective** | User names a single category | Scope the flow to that category only (e.g. "add MCP"). | Default to **audit** when in doubt. It's the least destructive and naturally leads into the others. ## Core workflow Execute these phases in order. Each phase has a clear exit condition — don't skip ahead. ### Phase 1 — Detect Before recommending anything, understand what's already here. Read — don't write. Run `scripts/detect.sh` from the skill directory. It emits a JSON profile describing: - project type, languages, package managers, test/build tools - existing agent context files (`CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`, `.cursorrules`, etc.) - existing skills directories (`.claude/skills/`, `.agents/skills/`), skill-lock files - existing MCP configs (`.mcp.json`, `.vscode/mcp.json`, `~/.codex/config.toml` if readable) - token-optimization tooling signals (Serena config at `.serena/`, RTK in PATH, Caveman, etc.) - SDD signals (`.specify/`, spec/plan/task files) - hooks, settings, permissions (`.claude/settings.json`, `.claude/settings.local.json`) - git state (branch, remote, clean/dirty) If the script is unavailable or fails, fall back to an inline checklist — see [references/detection.md](references/detection.md). That reference also explains how to interpret the signals (e.g. "a skill-lock.json + symlinked skills dir means a skill registry tool is managing them — do not hand-install skills there"). **Exit condition:** you can state, in 3–5 bullets, what this repo already has and where the gaps are. ### Phase 2 — Decide the scope Given the detection report, propose a mode and a shortlist of categories to consider. Present it to the user concisely: ``` Detected: <1-line summary> Already configured: Gaps/opportunities: Proposed mode: Categories I'd consider: [AI artifacts, SDD, MCP, token optimization, agent/IDE integration] Out of scope for now: OK to proceed, or adjust? ``` Wait for confirmation before doing any research or writes. Scope drift is the #1 failure mode of setup skills. ### Phase 3 — Research & curate For each in-scope category, consult the category-specific reference under [references/categories/](references/categories/). Each reference lists well-known candidates, fit criteria, compatibility notes, and install sketches: - [references/categories/ai-artifacts.md](references/categories/ai-artifacts.md) — agent instructions, prompts, skills, memory - [references/categories/sdd.md](references/categories/sdd.md) — Spec Kit and alternatives - [references/categories/mcp.md](references/categories/mcp.md) — MCP servers - [references/categories/token-optimization.md](references/categories/token-optimization.md) — Serena, RTK, Caveman, Serena Slim - [references/categories/agent-ide.md](references/categories/agent-ide.md) — Claude Code, Copilot, Codex, Cursor, etc. When skill installation is on the table, follow [references/skill-discovery.md](references/skill-discovery.md). That reference requires consulting **skills.sh** and/or installing/using **find-skills** before shortlisting. Apply the decision framework in [references/decision-framework.md](references/decision-framework.md) to avoid tool overload. High-leverage over maximal — every tool is maintenance. Cross-check candidates against [references/compatibility.md](references/compatibility.md) before proposing. Some combinations conflict (e.g. two hook frameworks racing, two MCP servers offering the same capability) and must be flagged. **Exit condition:** for each in-scope category you have 1–3 recommended candidates + clear reasons. No blind "install everything popular." ### Phase 4 — Present decisions and get approval Decisions must be *presented*, not assumed. Use the pattern in [references/interaction.md](references/interaction.md). Skeleton: ``` Decision : Why it matters: Option A — Recommended: Best fit because: Tradeoffs: Option B: Best fit if: Tradeoffs: ... Option C: Best fit if: Your call? ``` Batch related decisions but cap at ~5 at a time — cognitive load matters. For `audit` mode, stop here and produce a written recommendation document instead of asking for decisions. ### Phase 5 — Install, configure, validate Only after explicit approval. Follow [references/install-playbook.md](references/install-playbook.md). Hard rules: 1. **Back up first.** `scripts/backup.sh` snapshots touched files into a tarball under `.ai-dev-setup/backups//`. Run it before any write. 2. **Idempotent writes.** Prefer merging into existing files (e.g. appending an MCP server to `.mcp.json`) over full rewrites. If you must rewrite, diff-preview first. 3. **No silent overwrites.** If a target file exists and your change isn't purely additive, show the diff and ask. 4. **Log the change.** Append an entry to `.ai-dev-setup/changelog.md` with what, why, which backup. 5. **Validate.** Run `scripts/validate.sh` (or the category-specific validator). For MCP: attempt the listed tools work. For skills: the skill shows up in the expected location. For Serena: the hook fires. 6. **Surface rollback.** Tell the user the exact command to undo (`tar -xf -C /`). **Exit condition:** validation passes, or you've surfaced a real failure with a clear next step. Never report success without running the validator. ### Phase 6 — Report One concise report at the end: - What was installed/changed (file-by-file, with backup locations). - What was deliberately *not* installed, and why (so the user can revisit later). - Suggested next steps (e.g. "run `rtk gh auth login` once before using the GitHub MCP"). - How to roll back. ## Skill discovery Any time the in-scope work includes *installing reusable skills*, you MUST perform active skill discovery before recommending anything. Read and follow [references/skill-discovery.md](references/skill-discovery.md). Summary: 1. Check if `find-skills` is installed locally. If yes, use it. 2. Otherwise, consult **skills.sh** (https://skills.sh/) as a web source. 3. Offer to install `find-skills` as a durable helper if the user will likely do this again. 4. Curate — do not dump — shortlisted candidates. Flag overlap with installed skills (read the detection inventory). 5. Get explicit approval per-skill before install. Do not invent skill names. If you can't confirm a skill exists on skills.sh or in a known index, say so rather than guessing. ## Safety constraints - Never modify `~/.claude/settings.json` or other *user-global* config without explicit, specific approval. Prefer project-local scopes (`.claude/settings.json`, `.mcp.json`). - Never commit secrets. GitHub tokens, API keys, etc. go in `.env` (git-ignored) and are referenced by env var in configs. - If the git tree is dirty, warn the user and offer to stash or create a dedicated branch before writing. - If the skill detects an active skill-registry tool (e.g. a `skills-lock.json`), do not hand-install into the managed skills directory — use the registry tool's own install path, or tell the user. - On destructive prompts (overwrites, deletes), require explicit confirmation with the file path echoed back. ## Reference index | Topic | File | |------|------| | Detection signals & fallback checklist | [references/detection.md](references/detection.md) | | Decision framework (when to install vs. defer) | [references/decision-framework.md](references/decision-framework.md) | | How to present options to the user | [references/interaction.md](references/interaction.md) | | Skill discovery (skills.sh, find-skills) | [references/skill-discovery.md](references/skill-discovery.md) | | Tool compatibility & conflicts | [references/compatibility.md](references/compatibility.md) | | Install / configure / validate / rollback | [references/install-playbook.md](references/install-playbook.md) | | Category: AI artifacts | [references/categories/ai-artifacts.md](references/categories/ai-artifacts.md) | | Category: SDD | [references/categories/sdd.md](references/categories/sdd.md) | | Category: MCP | [references/categories/mcp.md](references/categories/mcp.md) | | Category: Token optimization | [references/categories/token-optimization.md](references/categories/token-optimization.md) | | Category: Agent/IDE integration | [references/categories/agent-ide.md](references/categories/agent-ide.md) | | Known-tool registry (machine-readable) | [assets/manifests/registry.json](assets/manifests/registry.json) | | Templates | [assets/templates/](assets/templates/) | ## Scripts | Script | Purpose | |--------|---------| | `scripts/detect.sh` | Emit repo profile JSON to stdout | | `scripts/backup.sh ...` | Snapshot files before modification | | `scripts/validate.sh [category]` | Post-install validation | All scripts assume POSIX shell, `jq`, and `rg`. They degrade gracefully if a tool is missing (print a clear message; don't crash the skill flow). ## Anti-patterns to avoid - **Installing everything popular.** Maintenance is a real cost; each added tool adds surface. Prefer 3 tools the user will actually use over 10 they won't. - **Assuming the agent.** This repo may be used by Claude Code, Copilot, Codex, or all three. Detect, don't assume. - **Rewriting existing guidance wholesale.** If `CLAUDE.md` already exists and reflects deliberate choices, merge — never clobber. - **Silent destructive operations.** Always announce file path + intent before writing. - **Skipping validation.** A setup that "installed without errors" but doesn't work is worse than no setup. - **Overwhelming prompts.** If you're asking more than ~5 questions in a batch, you haven't done enough curation.