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는 패키지 매니저 스타일의 도구로, AI 코딩 에이전트의 모든 기능(스킬, 도구, 규칙, 하위 에이전트, MCP 서버, 플러그인 등)을 단일 capabilities.yaml 파일에 선언하고 수십 개의 에이전트(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 기반 웹 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도 제공합니다.