Agent Plugins 1.0 적용 가이드: 스킬과 MCP 서버를 한 번에 배포하는 표준 패키징 방법

AI 코딩 도구를 여러 개 쓰는 팀은 같은 문제를 반복해서 겪는다. Claude Code에서 쓰던 스킬을 Cursor에도 넣고 싶고, Gemini CLI에서도 같은 MCP 서버를 쓰고 싶다. 그런데 각 도구가 요구하는 디렉터리 구조와 설정 파일이 다르면 같은 내용을 여러 번 포장해야 한다. 시간이 지나면 설정이 drift되고, 어떤 환경에서 어떤 도구가 연결됐는지 추적하기 어려워진다.

Google은 Agent Plugins 1.0.0 지원을 발표하며 이 문제를 공개 표준으로 풀겠다고 밝혔다. 원문은 Agent Plugins package your skills, tools, and more에서 확인할 수 있다. Agent Plugins는 Amazon, Cursor, Microsoft, OpenAI, Vercel 등이 참여한 Core Maintainers 체계에서 나온 vendor-neutral 디렉터리 규격이다. 목적은 Agent Skills와 MCP 서버를 하나의 휴대 가능한 패키지로 묶는 것이다.

문제: 스킬은 재사용되지만 포장 방식은 도구마다 다르다

스킬 자체는 보통 단순하다. “우리 팀의 코드 리뷰 기준”, “데이터베이스 리포트 생성 절차”, “배포 전 체크리스트”, “고객 지원 답변 톤” 같은 지식과 스크립트가 들어 있다. MCP 서버도 독립적으로는 표준화되어 있다. 문제는 이 둘을 특정 AI 클라이언트에 설치하는 방식이다. 어떤 도구는 설정을 JSON에 inline으로 넣고, 어떤 도구는 경로를 요구하고, 어떤 도구는 transport를 추론한다.

결과적으로 팀은 같은 스킬을 도구별로 복사한다. Claude용 폴더, Cursor용 폴더, 내부 CLI용 폴더가 생긴다. 처음에는 괜찮지만 한 달만 지나도 문서와 스크립트가 달라진다. 보안 정책을 하나 수정했는데 어떤 클라이언트에는 반영되지 않는 일이 생긴다. MCP 서버 주소가 바뀌었는데 일부 개발자는 예전 설정으로 계속 접속한다.

Agent Plugins는 이 포장 문제를 좁게 해결한다. 설치 UX, 권한 모델, 배포 마켓플레이스까지 한 번에 정의하지 않는다. 대신 디렉터리 안에 무엇이 어디 있어야 하는지만 정한다. 작은 범위지만 실무에는 꽤 중요하다. 표준 패키지 구조가 생기면 팀은 스킬과 도구를 제품처럼 버전 관리할 수 있다.

구조: plugin.json, skills, mcp.json, client namespace

Agent Plugin은 디렉터리다. 루트에는 plugin.json이 있고, 스킬은 skills/ 아래에 각 폴더로 들어간다. MCP 서버 선언은 mcp.json에 둔다. 특정 클라이언트 전용 확장은 reverse-domain namespace 폴더에 넣는다. 예를 들어 com.example.client/ 같은 식이다. 클라이언트가 모르는 namespace는 무시한다.

이 구조의 장점은 discovery가 단순하다는 점이다. 클라이언트는 skill 위치를 추측하지 않는다. skills/를 보면 된다. MCP 설정도 mcp.json을 보면 된다. plugin.json은 핵심 메타데이터만 담고, 컴포넌트를 inline으로 선언하거나 경로를 마음대로 바꾸지 않는다. 구성요소가 실패해도 독립적으로 실패한다. MCP 서버 하나가 시작하지 못한다고 스킬 전체를 못 쓰게 만들 필요가 없다.

실무적으로는 plugin.json을 너무 똑똑하게 만들지 않는 것이 좋다. 많은 내부 플랫폼이 manifest에 모든 것을 넣고 싶어 하지만, 그러면 다시 클라이언트별 해석 차이가 생긴다. Agent Plugins의 미덕은 제한이다. 공통 부분은 고정하고, 클라이언트별 혁신은 namespace로 빼는 방식이 장기 유지보수에 유리하다.

언제 플러그인을 써야 하나

모든 스킬을 플러그인으로 만들 필요는 없다. 단일 스킬 하나만 개인적으로 쓰는 수준이면 기존 스킬 폴더만으로 충분하다. 단일 MCP 서버 하나만 배포한다면 mcp.json만으로도 된다. Agent Plugins가 필요한 경우는 스킬과 MCP 서버, 참고 문서, 스크립트가 함께 움직여야 할 때다.

예를 들어 데이터팀이 “주간 매출 리포트 생성” 기능을 만든다고 하자. 스킬에는 리포트 작성 기준과 해석 규칙이 들어 있다. MCP 서버는 BigQuery나 내부 warehouse에 접근한다. scripts에는 쿼리 샘플이나 후처리 도구가 있다. references에는 지표 정의서가 있다. 이 묶음은 따로 떨어지면 의미가 약해진다. 이런 경우 plugin으로 배포하면 좋다.

또 다른 예는 보안 리뷰 plugin이다. 스킬에는 코드 리뷰 기준, 금지 패턴, 승인 절차가 들어 있다. MCP 서버는 SAST 결과나 dependency scanner에 접근한다. 클라이언트별 namespace에는 VS Code용 command나 내부 CLI용 hook을 넣을 수 있다. 핵심 정책은 공통이고, 각 도구의 UX만 다르게 가져간다.

적용 절차: 작은 hello world보다 내부 업무 하나를 고르라

처음 도입할 때는 hello world보다 실제로 반복되는 업무 하나를 고르는 편이 낫다. 예를 들어 “릴리스 노트 작성”, “고객사 장애 리포트 작성”, “PR 보안 리뷰”, “데이터 품질 점검”처럼 매주 반복되고 여러 도구에서 쓰이는 작업이 좋다. 그래야 표준화의 효과가 바로 보인다.

1단계는 현재 흩어진 자산을 모으는 것이다. 관련 스킬 문서, 스크립트, MCP 서버 설정, 샘플 입력, 결과 예시를 한 폴더에 넣는다. 2단계는 portable core와 client-specific extension을 나눈다. 모든 클라이언트에서 같아야 하는 것은 skills/, mcp.json, references에 둔다. 특정 도구에서만 필요한 명령이나 UI 설정은 namespace 폴더로 뺀다.

3단계는 versioning이다. plugin 디렉터리를 저장소에서 관리하고 SemVer를 붙인다. 보안 정책이나 MCP 권한이 바뀌면 minor 또는 major 변경으로 기록한다. 4단계는 설치 검증이다. 지원하는 클라이언트마다 plugin이 로드되는지, MCP 서버 실패 시 스킬은 유지되는지, 권한 오류가 사용자에게 명확히 보이는지 테스트한다.

보안과 거버넌스: 패키징 표준은 권한 표준이 아니다

Agent Plugins v1은 권한 모델을 정의하지 않는다. 이 점이 중요하다. plugin이 표준 구조라고 해서 안전하다는 뜻은 아니다. mcp.json 안의 서버가 파일 시스템, 데이터베이스, SaaS API에 접근할 수 있다면 여전히 위험하다. 설치 승인, provenance, 서명, sandbox, 비밀키 접근은 각 조직과 클라이언트가 별도로 해결해야 한다.

따라서 팀은 plugin registry 또는 허용 목록을 둬야 한다. 누가 plugin을 만들 수 있는지, 누가 배포 승인하는지, 어떤 MCP 서버가 어떤 권한을 요청하는지, secret은 어디서 주입되는지 정해야 한다. plugin 디렉터리 자체에도 README, CHANGELOG, SECURITY 문서를 두는 것이 좋다. 특히 MCP 서버에는 read-only 기본값을 권장하고, write 권한은 별도 승인 흐름을 붙인다.

공급망 관점에서는 plugin 서명도 고려해야 한다. 공식 spec이 설치 메커니즘을 정의하지 않더라도, 내부 배포에서는 release artifact에 checksum과 서명을 붙일 수 있다. 개발자 PC에서 임의 plugin을 내려받아 설치하는 관행은 막아야 한다. AI agent가 실행하는 도구는 일반 개발 도구보다 권한이 넓어질 수 있기 때문이다.

팀 운영에 주는 효과

잘 만든 plugin은 온보딩 시간을 줄인다. 신입 개발자가 IDE를 무엇을 쓰든 같은 리뷰 기준과 같은 데이터 도구를 받을 수 있다. 정책 변경도 한 곳에서 배포된다. “Claude에는 최신 보안 체크리스트가 있는데 Cursor에는 예전 버전” 같은 문제를 줄일 수 있다.

또한 AI 도구 교체 비용이 낮아진다. 특정 벤더에 종속된 prompt와 tool 설정이 줄어들면, 팀은 더 나은 클라이언트가 나왔을 때 옮기기 쉽다. 이는 구매 협상에도 영향을 준다. 핵심 업무 지식이 벤더 설정 안에 갇히지 않고, 표준 디렉터리로 관리되기 때문이다.

다만 표준화가 과하면 개인 실험이 죽을 수 있다. 추천은 core plugin과 experimental plugin을 분리하는 것이다. core plugin은 팀 표준으로 승인된 안정 버전이고, experimental plugin은 개인이나 작은 그룹이 빠르게 실험한다. 실험이 반복적으로 효과를 내면 core로 승격한다.

실행 체크리스트

• 여러 AI 클라이언트에서 반복해서 쓰는 업무 하나를 고른다.
• 스킬 문서, MCP 서버 설정, 참고 문서, 스크립트를 한 plugin 디렉터리로 모은다.
• 공통 자산은 skills/와 mcp.json에 두고, 클라이언트 전용 설정은 reverse-domain namespace에 둔다.
• plugin.json에는 핵심 메타데이터만 두고 컴포넌트 경로를 임의로 바꾸지 않는다.
• SemVer, CHANGELOG, README, SECURITY 문서를 함께 관리한다.
• MCP 서버는 read-only 기본값으로 시작하고 write 권한은 승인 절차를 붙인다.
• plugin 설치는 허용 목록이나 내부 registry를 통해 관리한다.
• 지원 클라이언트별 로드 테스트와 MCP 실패 시 graceful degradation을 확인한다.
• 보안 정책 변경은 plugin 버전 업데이트로 배포하고, 구버전 사용자를 추적한다.
• core plugin과 experimental plugin을 분리해 표준화와 실험 속도를 함께 유지한다.