Bootstrap

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/typescript.mdc
      id: typescript
      provider: cursor
      applies_to: ["**/*.ts", "**/*.tsx"]
  hooks:
    - source: .claude/settings.json
      event: PreToolUse
      provider: claude-code
      command: "..."
  subagents:
    - source: .claude/agents/api-reviewer.md
      id: api-reviewer
  symlinks: [...]
  submodules: [...]
  ignored_dirs_present: [".claude", ".cursor"]

You don't have to use that exact format — it's a checklist. Whatever you produce should let the user see, at a glance, what's about to be migrated.

Phase 3 — Plan

Show the inventory to the user. Before moving any files, propose:

Why moves are necessary (lead with this — users often resist file moves until they understand): capa's install model assumes it owns the provider-specific directories. On every capa install, it rewrites .claude/skills/, .cursor/skills/, etc. from a separate source-of-truth location. If a skill stays under .claude/skills/ and is also declared as type: local pointing at the same dir, install fails with "directory already exists and is not managed by capa." So the source has to live outside provider dirs — that's the whole reason for the move, not aesthetics.

If the project's own conventions designate .claude/skills/ (or similar provider dir) as the shared canonical location (often documented in an AGENTS.md at that path), call that out and explain that the convention worked pre-capa but capa-managed projects need a separate source dir. Offer to update the project's AGENTS.md as part of the migration so it reflects the new layout.

1. Which items to migrate into shared dirs, and what they'll become:

   • .claude/skills/foo/ → skills/foo/ referenced as type: local, def.path: ./skills/foo
   • .cursor/skills/bar/ → skills/bar/ (or merged with an existing one of the same name; flag the conflict)
   • .cursor/rules/*.mdc → rules/*.md referenced as type: local with path: ./rules/<id>.md (preferred for anything non-trivial). Small one-liners can stay type: inline with content: embedded.
   • .claude/agents/*.md → entries in the top-level subagents: section (capa regenerates the file on install)
   • Hooks in .claude/settings.json / .cursor/hooks.json → top-level hooks: entries, using canonical event names. For non-trivial hook scripts, move the script under hooks/<id>.sh and reference via source: { type: local, path: ./hooks/<id>.sh }. Inline one-liners stay inline.
   • MCP servers from .cursor/mcp.json, .claude/settings.json mcpServers, .codex/config.toml mcp_servers → top-level servers: entries. Merge duplicates by id; flag mismatched configs (e.g., two providers point a server with the same id at different commands).

2. Which providers to declare in options.providers (or to omit so capa resolves at install time). Default: declare exactly the providers whose config dirs you found.

3. Which directories to .gitignore — by default, ignore generated subpaths only:

   .claude/skills/
   .claude/agents/
   .cursor/skills/
   .cursor/rules/
   .cursor/mcp.json

   .claude/settings.json and .cursor/settings.json often contain user-specific bits the user wants to keep editing by hand, so leave them tracked. If the user has nothing hand-authored there, they can broaden to .claude/ / .cursor/ themselves.

4. Conflicts and ambiguities — call them out explicitly:

   • Two skills with the same name in different provider dirs (likely the same skill installed twice — confirm before merging)
   • A symlinked config dir (user probably wants this preserved, not moved)
   • A rule with provider-specific frontmatter that won't round-trip cleanly into capa's type: local / type: inline form (note any lost Cursor-only fields like complex globs and ask)
   • A submodule that itself ships skills (probably should become a plugin or a github-typed skill — don't auto-vendor it)

Wait for confirmation before Phase 4. The user may want to skip some items, rename others, or change the target layout. Don't move files without sign-off — bootstrap's whole value is being the careful path.

Phase 4 — Migrate

Execute the plan. Use git mv rather than mv so history follows the files. Keep moves atomic per category — easier to revert if something looks wrong.

After moving, run git status and show the user the rename list so they can spot-check before you write the capabilities file.

Phase 5 — Synthesize

Compose capabilities.yaml at the project root. The skeleton:

providers:
  # only the ones actually present in the project
options:
  toolExposure: search
skills:
  - id: capabilities-manager
    type: github
    def:
      repo: infragate/capa@capabilities-manager
      description: Guide for managing capabilities with capa CLI
  # then everything discovered, sorted by id
servers: []
tools: []
rules: []
hooks: []
subagents: []
plugins: []

Rules of composition:

• Always include capabilities-manager so future edits have the schema available to the agent.
• Sort entries by id within each section. Stable order makes future diffs readable.
• Don't invent ids. Use the directory or file basename for discovered items, kebab-cased.
• For each MCP server, prefer the most complete config from any source (e.g., if .cursor/mcp.json has env vars and .claude/settings.json doesn't, take Cursor's). Replace literal secrets with ${VarName} placeholders and warn the user that capa will prompt for them on capa install.
• For rules, prefer type: local with path: pointing at the migrated file under rules/ — capa re-reads it on each install. Use type: inline with content: only for short one-liners. Remote github/gitlab sources are fine when the rule already lives in another repo.
• For hooks, translate provider event names to canonical names using the table in references/event-mapping.md. If a hook's provider event has no canonical mapping, keep the provider-scoped form (cursor:beforeShellExecution) — don't drop it.
• Don't include empty sections unless they're useful as placeholders. servers: [] and tools: [] belong (so users know where to add things); subagents: [] only belongs if you actually expect them to add some.

For the exact field-by-field shape of every entry type, consult the capabilities-manager skill's references/capabilities-schema.md — bootstrap should never duplicate that.

Then update .gitignore per the plan from Phase 3. Append a clearly-marked block so the user can see what bootstrap added:

# Added by capa bootstrap — generated agent configs
.claude/skills/
.claude/agents/
.cursor/skills/
.cursor/rules/
.cursor/mcp.json

Phase 6 — Verify

Run capa install and watch the output. Three things to surface to the user:

1. What got installed — list of skills/rules/hooks/servers that capa wrote to disk.
2. Anything blocked — a forbidden phrase, a missing CLI prerequisite, an unreachable remote. Don't silently swallow these.
3. What's left to do — credentials capa will prompt for, optional fields the user might want to fill in (descriptions, sub-agent instructions, etc.).

If install fails, don't auto-rollback — the user is on a branch, and the partial state is debuggable. Tell them what failed and let them decide whether to fix forward or git reset.