Skip to content
Back to search

capa

One capabilities.yaml wires skills, tools, rules, sub-agents, MCP servers, and plugins into Cursor, Claude Code, Codex, Windsurf, GitHub Copilot, and 30+ other AI coding agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/infragate--capa/badge.svg)](/listings/infragate--capa)

HTML

<a href="/listings/infragate--capa"><img src="/api/listings/infragate--capa/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**macOS and Linux:**

curl -LsSf https://capa.sh/install.sh | sh

**Windows:**

powershell -ExecutionPolicy ByPass -c "irm https://capa.sh/install.ps1 | iex"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 248 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.svg">
  4. <source media="(prefers-color-scheme: light)" srcset="assets/banner-light.svg">
  5. <img alt="CAPA" src="assets/banner-light.svg" width="280">
  6. </picture>
  7. </p>
  8. <h3 align="center">The package manager and MCP gateway for AI coding agents</h3>
  9. <p align="center">
  10. <a href="https://github.com/infragate/capa/releases/latest"><img src="https://img.shields.io/github/v/release/infragate/capa?style=flat-square&label=latest&color=6366f1" alt="Latest Release"></a>
  11. <a href="https://github.com/infragate/capa/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/infragate/capa/test.yml?style=flat-square&label=tests&logo=github" alt="Tests"></a>
  12. <a href="https://github.com/infragate/capa/actions/workflows/release.yml"><img src="https://img.shields.io/github/actions/workflow/status/infragate/capa/release.yml?style=flat-square&label=release&logo=github" alt="Release"></a>
  13. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License: MIT"></a>
  14. <a href="https://github.com/infragate/capa/releases/latest"><img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat-square" alt="Platforms"></a>
  15. <a href="https://x.com/InfragateAI"><img src="https://img.shields.io/badge/follow-%40InfragateAI-000000?style=flat-square&logo=x&logoColor=white" alt="Follow @InfragateAI on X"></a>
  16. </p>
  17. <p align="center">
  18. <a href="#why-capa">Why</a> ·
  19. <a href="#features">Features</a> ·
  20. <a href="#installation">Install</a> ·
  21. <a href="#quick-start">Quick start</a> ·
  22. <a href="#capa-wrap">Wrap</a> ·
  23. <a href="#web-ui--observability">Web UI</a> ·
  24. <a href="#documentation">Docs</a> ·
  25. <a href="#community">Community</a>
  26. </p>
  27. Declare skills, tools, rules, sub-agents, MCP servers, hooks, and plugins once in `capabilities.yaml`. Run `capa install`. CAPA writes them into Cursor, Claude Code, Codex, Windsurf, GitHub Copilot, and 35+ other agents — native formats, pinned SHAs, zero manual sync. At runtime it is also the **MCP gateway**: every agent talks to one local endpoint; CAPA proxies upstream servers, lazy-loads tools, and scopes what each sub-agent can call.
  28. https://github.com/user-attachments/assets/200a8cf9-7236-4cc0-a9e4-332bb6664b41
  29. ## Why CAPA?
  30. Agent config today is scattered across `CLAUDE.md`, `.cursor/rules/`, `AGENTS.md`, MCP JSON, hooks, and skill folders. No two teammates match. Nothing is pinned. Cloning the repo does not clone the agent setup.
  31. CAPA collapses that into one version-controlled file next to your code — and a local MCP gateway in front of every tool:
  32. - **`capabilities.yaml`** — source of truth for every capability
  33. - **`capabilities.lock`** — SHA pins so tomorrow's clone gets the same bytes
  34. - **Marker blocks** — surgical writes that leave hand-edited content alone
  35. - **MCP gateway** — one endpoint per project; CAPA proxies stdio / HTTP / SSE servers, applies formatters, and records activity
  36. The teammate who clones tomorrow gets the exact setup you have today.
  37. ## Features
  38. - **One file → 35+ agents** — write once; CAPA fans out to each provider's native layout (`.cursor/rules/`, `.claude/agents/`, `AGENTS.md`, …)
  39. - **MCP gateway** — one local endpoint per agent; CAPA proxies upstream MCP servers, lazy-loads tools on demand, and filters tools per sub-agent
  40. - **Cheaper inference, same quality** — on-demand tool loading instead of front-loading the whole catalog (**19–40%** fewer tokens across 150 trials on claude-opus-4-8)
  41. - **`capa wrap`** — run Cursor, Claude, Codex, and more from a shadow workspace so provider dirs never touch your real repo
  42. - **Local Web UI** — interactive capabilities editor with live YAML sync, registry browse, OAuth setup, and drag-to-reorder
  43. - **Activity traces** — live feed of every MCP call, shell tool, and agent span on the project page
  44. - **Plugins that unpack** — Claude and Cursor plugins decompose into skills, MCP, rules, sub-agents, and hooks
  45. - **Registries** — browse skills.sh, Cursor Marketplace, Claude plugins, and Claude marketplace catalogs
  46. - **`capa add --passthrough`** — write provider-native files directly when you want unmanaged one-offs
  47. - **Sub-agent isolation** — each sub-agent gets a filtered MCP endpoint, so research agents never inherit a `git push` tool
  48. ## Installation
  49. **macOS and Linux:**
  50. ```bash
  51. curl -LsSf https://capa.sh/install.sh | sh
  52. ```
  53. **Windows:**
  54. ```powershell
  55. powershell -ExecutionPolicy ByPass -c "irm https://capa.sh/install.ps1 | iex"
  56. ```
  57. ## Quick start
  58. ### 1. Initialize
  59. ```bash
  60. cd your-project
  61. capa init
  62. ```
  63. Creates `capabilities.yaml` and registers the project with the local CAPA server (default `http://localhost:5912`).
  64. The new file points at the [JSON Schema](./schema/capabilities.schema.json), so editors with YAML/JSON language support autocomplete and validate it. For an existing file, add this first line:
  65. ```yaml
  66. # yaml-language-server: $schema=https://raw.githubusercontent.com/infragate/capa/main/schema/capabilities.schema.json
  67. ```
  68. ### 2. Add capabilities
  69. ```bash
  70. capa add vercel-labs/agent-skills@web-researcher
  71. capa add --server --id brave --cmd npx --arg @brave/brave-search-mcp
  72. capa registry search skills-sh "research"
  73. ```
  74. ### 3. Install
  75. ```bash
  76. capa install # interactive: confirms executable surface, then installs
  77. capa install --yes # CI / scripts: skip confirmation
  78. capa install --dry-run # preview MCP servers, hooks, and commands without changes
  79. ```
  80. Resolves SHAs, fills the cache, writes per-provider files, and registers one MCP endpoint with each configured agent. Resolved SHAs land in `capabilities.lock`.
  81. > [!NOTE]
  82. > Non-interactive shells (CI, scripts) must pass `--yes`. The first install prints the executable surface (MCP stdio servers, hooks, command tools, plugins) and asks for confirmation; unchanged surfaces skip the prompt on re-run.
  83. > [!TIP]
  84. > Already have skills, MCP configs, and rules in the repo? After `capa init`, use the bundled `/bootstrap` skill — the agent scans the project and drafts the CAPA config for you.
  85. ### 4. Run tools from the terminal
  86. ```bash
  87. capa sh # list every configured tool
  88. capa sh brave # list brave subcommands
  89. capa sh brave search --query "…" # run a tool directly
  90. capa sh --raw brave search --query "…" # skip per-tool formatters
  91. ```
  92. Every tool you define is also a CLI command under `capa sh`.
  93. ### 5. Open the Web UI
  94. ```bash
  95. capa open # open this folder's project in the browser
  96. capa open ../other # or any other project folder
  97. capa status # prints the local URL when the server is up
  98. ```
  99. Edit skills, tools, rules, hooks, plugins, and agents in the browser. Changes sync live back to `capabilities.yaml`.
  100. ## `capa wrap`
  101. Run an agent **without polluting your repo** with `.cursor/`, `.claude/`, and friends. CAPA builds a shadow workspace under `~/.capa/workspaces/`, symlinks your project (minus provider-owned paths), installs capabilities into the shadow, and launches the agent.
  102. ```bash
  103. capa wrap cursor # Cursor GUI — stops when the window closes
  104. capa wrap claude # Claude Code (aliases: claude-code)
  105. capa wrap agent # Cursor CLI
  106. capa wrap codex
  107. capa wrap gemini-cli
  108. capa wrap opencode
  109. capa wrap cursor --print-dir # print shadow path, then launch
  110. capa wrap --prune # clean stale workspaces
  111. capa stop # stop server + active wrap sessions
  112. ```
  113. **Wrappable today:** Claude Code, Codex, Cursor, Gemini CLI, OpenCode, iFlow CLI, Kiro CLI, Qwen Code, Kimi CLI.
  114. > [!NOTE]
  115. > On Windows, creating the shadow workspace may require [Developer Mode](https://learn.microsoft.com/windows/apps/get-started/enable-your-device-for-development) (or an elevated shell) for symlinks. GitHub Copilot is not wrappable yet — it owns shared `.github/` / `.vscode/` trees that need subpath exclusions.
  116. ## Web UI & observability
  117. The embedded React UI (served by the local server) covers the full project lifecycle:
  118. | Area | What you get |
  119. | --- | --- |
  120. | **Capabilities editor** | Skills, tools, rules, hooks, sub-agents, plugins, agents — CRUD, local file pickers, drag reorder |
  121. | **Registries** | Search seeded catalogs (skills.sh, Cursor Marketplace, Claude plugins) and add your own |
  122. | **Activity** | Live tool-call feed, charts, and run timelines (default-on via `options.agentActivity`) |
  123. | **Variables / OAuth** | Credential setup when install needs secrets |
  124. Activity is powered by system hooks and the MCP proxy tracer — MCP failures show as error rows, shell tools from `capa sh` are labeled correctly, and secrets in args/results are redacted.
  125. ## Plugins & registries
  126. Plugins are not opaque blobs. CAPA clones the repo, reads Claude (`.claude-plugin/`) or Cursor (`.cursor-plugin/`) manifests, and merges skills, MCP servers, rules, sub-agents, and hooks into the same install pipeline as everything else.
  127. ```bash
  128. capa add owner/repo --plugin --install
  129. capa add cursor-marketplace:some-plugin --plugin
  130. capa registry list
  131. capa registry add anthropics/claude-plugins-official --type claude-marketplace
  132. capa registry search skills-sh "typescript"
  133. ```
  134. > [!IMPORTANT]
  135. > Most registry adapters are executable TypeScript fetched into `~/.capa/registries-managed/`. Review the source before enabling a third-party registry. Claude marketplaces are JSON catalogs only — safer by design.
  136. ## Passthrough mode
  137. Need a one-off native write without CAPA managing the file?
  138. ```bash
  139. capa add owner/repo@skill --passthrough --provider cursor
  140. capa add --rule --id ts-strict --inline "Always use strict TypeScript" --passthrough
  141. capa install --passthrough
  142. ```
  143. Passthrough skips `capabilities.yaml`, the lockfile, and managed-file tracking. Tool aliases, defaults, and formatters still require managed mode (`capa add --tool … --passthrough` is refused).
  144. ## How it fits together
  145. ```
  146. capabilities.yaml ──► capa install ──► provider files (.cursor/, .claude/, AGENTS.md, …)
  147. │ │
  148. │ ├── capabilities.lock
  149. │ ├── ~/.capa/cache/ (content-addressed snapshots)
  150. │ └── ~/.capa/db.sqlite (projects, variables, activity)
  151. │
  152. └──► Web UI editor ◄──► file watcher ◄──► disk
  153. Agent ──MCP──► capa gateway (:5912) ──proxy──► upstream MCP (stdio / HTTP / SSE)
  154. │
  155. ├── on-demand tools (setup_tools / call_tool)
  156. ├── per-sub-agent filtered endpoints
  157. └── ToolCallTracer → activity feed
  158. ```
  159. ## CLI cheat sheet
  160. ```bash
  161. capa init # create capabilities.yaml + register project
  162. capa add <source> [--plugin] [--install]
  163. capa add --server|--tool|--rule|--hook …
  164. capa install [-p <provider>] [-e .env] [--no-cache] [--yes] [--dry-run]
  165. capa wrap <provider> [--project <path>]
  166. capa sh [tool] [args…] [--raw]
  167. capa registry search|add|list|refresh|remove …
  168. capa start|stop|restart|status
  169. capa clean # remove managed artifacts
  170. capa auth github|gitlab
  171. capa cache | capa cache clean
  172. capa upgrade [--yes] # pin GitHub release + verify installer checksum
  173. ```
  174. ## Documentation
  175. Guides, the full schema reference, and the registry catalog:
  176. **[https://capa.sh](https://capa.sh/getting-started/introduction/)**
  177. Maintainer-oriented internals (install pipeline, provider matrix, lockfile semantics) live in [`docs/`](./docs/README.md).
  178. ## Community
  179. - **[@InfragateAI](https://x.com/InfragateAI)**: release notes, new providers, and CAPA tips
  180. - **[@AntonioZaitoun](https://x.com/AntonioZaitoun)**: built by Antonio Zaitoun; follow along for what's next
  181. Questions or bugs? [Open an issue](https://github.com/infragate/capa/issues).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.