infragate/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

TL;DR

CAPA 是一个包管理器风格的工具，让您可以在单个 capabilities.yaml 文件中声明所有 AI 编码代理的功能（技能、工具、规则、子代理、MCP 服务器、插件等），然后自动为数十个代理（Cursor、Claude Code、Codex、Gemini-CLI、GitHub Copilot 等）写入适当的配置。它还会运行本地 MCP 网关，让每个代理都连接到同一个端点，该网关会代理上游服务器、延迟加载工具，并隔离子代理。

它的功能（以通俗语言说明）

步骤	您运行的命令	发生什么
初始化	`capa init`	在您的代码旁创建 `capabilities.yaml`，并将项目注册到本地 CAPA 服务器（默认 `http://localhost:5912`）。
声明功能	`capa add …`（例如 `capa add vercel-labs/agent-skills@web-researcher`）	将技能、工具、规则、MCP 服务器或插件添加到 YAML 文件。您也可以从 skills.sh 或 Claude Marketplace 等注册表拉取。
安装	`capa install`（或在 CI 中使用 `capa install --yes`）	解析确切的 SHA，将所需文件写入每个代理的原生布局（`.cursor/`、`.claude/`、`AGENTS.md` 等），创建锁文件（`capabilities.lock`），并启动代理将使用的每个项目 MCP 端点。
运行代理而不污染您的仓库	`capa wrap cursor`（或 `capa wrap claude`、`capa wrap codex` 等）	CAPA 在 `~/.capa/workspaces/` 下创建影子工作区，将您的项目符号链接（排除提供商特定的文件夹），在该处安装声明的功能，并启动所选的代理。真实的仓库保持干净。
从终端交互	`capa sh brave search --query "…"`	通过本地 MCP 网关直接调用已注册的工具。`capa sh` 也会列出可用的工具。
可视化编辑	`capa open`	打开本地 React 构建的 Web UI，您可以在其中对功能进行 CRUD、浏览注册表、查看实时活动追踪，以及设置 OAuth 凭据。

CAPA 背后的关键概念

单一事实来源 – 所有功能都位于一个版本控制的 YAML 文件中，加上锁文件固定确切版本（SHA）。不再有分散的 CLAUDE.md、.cursor/rules/ 等。
MCP 网关 – 本地代理（localhost:5912），每个代理都连接到它。它将调用转发到真正的上游 MCP 服务器，仅在需要时加载工具，并可以过滤子代理可以使用哪些工具。
写一次，分散输出 – 当您运行 capa install 时，CAPA 会将声明式配置转换为每个受支持代理（启动时有 35+ 个提供商）所需的原生文件格式。这让仓库在团队成员之间保持同步。
影子工作区 – capa wrap 让您在仓库的隔离副本中启动代理，防止提供商特定的隐藏文件夹污染您的源代码树。
可观测性 – 内置 UI 显示每个 MCP 调用、工具执行和代理范围的实时馈送，帮助您调试或审计代理正在做什么。

谁可能使用它？

依赖多个编码代理（例如 Claude Code、Cursor 和 Gemini-CLI 的混合）构建 AI 辅助开发工具的团队，并想要可重现、版本控制的设置。
需要固定确切工具版本并确保每个 CI 运行器获得相同代理设置的 DevOps / MLOps 工程师。
想要尝试新代理技能而不需手动编辑数十个配置文件的个人开发者。

快速入门检查清单（复制粘贴）

# 1️⃣ 安装 CLI（macOS / Linux）
curl -LsSf https://capa.sh/install.sh | sh
# Windows – 为简洁起见省略 PowerShell 版本

# 2️⃣ 初始化项目
cd my-project
capa init

# 3️⃣ 添加技能 / 工具（示例）
capa add vercel-labs/agent-skills@web-researcher
capa add --server --id brave --cmd npx --arg @brave/brave-search-mcp

# 4️⃣ 安装到所有代理
capa install   # 首次运行交互式
# 或在 CI 中
capa install --yes

# 5️⃣ 运行代理而不触及仓库
capa wrap cursor   # 在影子工作区中打开 Cursor GUI

# 6️⃣ 打开可视化编辑器（可选）
capa open   # 在浏览器中启动 http://localhost:5912

限制 / 开放问题（截至 README）

GitHub Copilot 目前无法被包装，因为它共享 .github/ / .vscode/ 目录。
在 Windows 上，创建影子工作区可能需要开发者模式或提升权限才能创建符号链接。
受支持的代理列表正在增长；如果您依赖某个小众代理，请检查是否有提供商插件。

哪里可以了解更多

官方文档与入门指南： https://capa.sh/getting-started/introduction/
模式参考与内部细节： 仓库内的 docs/README.md。
发布说明与二进制文件： GitHub 发布页面（README 中的徽章）。

结论

CAPA 旨在让 AI 编码代理环境可重现且易于管理，将分散、手动的设置转变为声明式、版本控制的工作流程，同时提供本地 MCP 网关和方便的 UI 以提供可见性。