/bootstrap

name: bootstrap
description: Capify an existing project. Scans the repo for already-installed MCP servers, skills, rules, hooks, sub-agents, and plugins (across .claude, .cursor, .codex, .gemini, etc.), consolidates them into shared top-level directories (skills/, rules/, hooks/), and synthesizes a sound capabilities.yaml from the inventory. Use whenever the user says "bootstrap capa", "capify this project", "onboard capa onto an existing repo", "inventory my agent setup", or asks how to turn an ad-hoc Claude/Cursor/Codex configuration into a capabilities file. Use even when the user only mentions one provider — discovery should still sweep all of them.

Bootstrap

Turn an existing project that has accumulated MCP servers, skills, rules, hooks, and sub-agents across several provider-specific directories into a clean, reproducible `capabilities.yaml` managed by capa.

When to use

The user has a repo that already works with at least one AI coding agent (Claude Code, Cursor, Codex, Gemini, Copilot, etc.) but has never run `capa init`. They want capa to take over so the configuration is shared across providers and version-controlled in one place.

Trigger words and shapes: "bootstrap capa", "capify", "set capa up on this repo", "convert my .claude/.cursor config to capa", "I have a bunch of skills and rules already — onboard them".

If `capabilities.yaml` already exists at the repo root, this skill is the wrong tool — point the user at the `capabilities-manager` skill instead, which knows how to extend an existing file.

How this relates to `capabilities-manager`

Bootstrap is the one-time on-boarding helper. It produces a `capabilities.yaml` from scratch. `capabilities-manager` is the long-term editor — adding skills, registering MCP servers, configuring hooks on an already-bootstrapped project. **Read `capabilities-manager` for schema details and YAML examples** rather than re-deriving them here; this skill focuses on discovery and migration, and defers all schema questions to it.

When you (the agent) need to know the exact shape of a `skills:` entry, a `hooks:` entry, the canonical event names, the difference between `@` and `::` in `def.repo`, or any other schema-level detail — load the `capabilities-manager` skill rather than guessing. Bootstrap calls schema decisions out by name, but never inlines the schema reference.

The flow at a glance

1. **Preflight** — verify capa is installed, decide whether to branch, check for an existing `capabilities.yaml`. 2. **Discover** — sweep the repo for every flavor of agent config, including symlinks and submodules. 3. **Plan** — present the inventory to the user, propose moves, get sign-off before touching files. 4. **Migrate** — move provider-specific items into shared top-level dirs. 5. **Synthesize** — write `capabilities.yaml` and update `.gitignore`. 6. **Verify** — run `capa install` and surface anything that didn't take. 7. **Inspect tools** — for each registered MCP server, ask capa what tools it exposes. Servers expose all their tools by default (`expose: all`), and with the default `search` mode the agent finds them by task, so usually nothing needs to be added; narrow with `except` / `exactly` or curate `tools:` only when the project needs it. Servers with zero tools usually mean unfinished auth — tell the user and wait.

Each phase is described below. Don't skip a phase; each one's output is the next one's input.

Phase 1 — Preflight

Before scanning, confirm three things:

**Capa is installed.** Run `capa --version`. If it isn't installed, stop and ask the user to install it (point them at the README); don't attempt to bootstrap blind.

**Git state is sane.** Run `git status --porcelain` and `git rev-parse --abbrev-ref HEAD`. If the working tree has uncommitted changes that aren't agent-config files (i.e., user is mid-edit on real code), tell them and ask whether to proceed; bootstrap will move files and they may want a clean slate first.

**Branch decision.** Look at the current branch:

• If it's `main`, `master`, `trunk`, or matches the repo's default branch (from `git symbolic-ref refs/remotes/origin/HEAD` — fall back to `main` if unset), create a new branch named `capa/bootstrap` (or a unique suffix if that already exists) with `git checkout -b capa/bootstrap`. Bootstrap touches many files; isolating that in a branch makes it trivially revertable.
• If it's anything else, the user is already working on something — stay on that branch and tell them so. Don't switch.

**Existing capabilities file.** If `capabilities.yaml` or `capabilities.json` already exists at the repo root, stop. Tell the user the project is already bootstrapped and they should use `capabilities-manager` to extend it.

Phase 2 — Discover

Sweep the project for every kind of agent configuration. **Run the searches in parallel** — they're independent and reading them sequentially wastes time on large repos. Always exclude `node_modules`, `dist`, `build`, `.git`, `vendor`, and `target` from globs.

For each category below, also resolve **symlinks** (`find . -type l -not -path './node_modules/*' -not -path './.git/*'`) and check **git submodules** (`git submodule status` — if any submodule is itself an agent-config repo, surface it). A symlinked `.cursor` pointing at `~/dotfiles` is a real finding that affects what you do with it.

See `references/discovery.md` for the exhaustive search matrix — every file glob, every JSON/TOML key, every provider quirk. Use that file rather than memorizing locations; provider directories change and the reference is updated when capa learns a new one.

The shape of the inventory you build should look like:

discovered:
  mcp_servers:
    - source: .cursor/mcp.json
      id: postgres
      kind: local-subprocess
      def: { cmd: ..., args: ..., env: ... }
  skills:
    - source: .claude/skills/code-review/SKILL.md
      id: code-review
      provider: claude-code
  rules:
    - source: .cursor/rules/typ