Agent Plugins 1.0.0 설계법: Skill과 MCP를 함께 배포하는 패키징 기준

요약: Agent Plugins 1.0.0은 Agent Skills와 MCP 서버를 하나의 디렉터리 구조로 묶는 vendor-neutral 패키징 규격입니다. 단일 skill이나 단일 MCP 서버에는 과할 수 있지만, 여러 AI 코딩 에이전트와 IDE에 같은 기능을 배포해야 하는 팀에는 표준 패키지 형식이 됩니다.

왜 Agent Plugins가 나왔나

AI 에이전트 생태계에서 Skill과 MCP는 이미 중요한 구성요소가 됐습니다. Skill은 에이전트에게 특정 업무 절차, 참고 자료, 스크립트를 제공하고, MCP 서버는 외부 도구와 데이터를 연결합니다. 문제는 둘을 함께 배포할 때 생깁니다. Claude Code, Cursor, Gemini CLI, 사내 IDE가 각자 다른 manifest와 디렉터리 구조를 요구하면 같은 기능을 여러 번 포장해야 합니다.

Google Developers Blog는 이 문제를 “컴포넌트가 아니라 manifest의 문제”라고 설명했습니다. skill 자체와 MCP 서버는 재사용 가능하지만, 그것들을 담는 상자가 클라이언트마다 달라 drift가 생긴다는 뜻입니다. Agent Plugins 1.0.0은 이 상자를 작고 고정된 구조로 표준화합니다.

규격은 Amazon, Cursor, Microsoft, OpenAI, Vercel 등이 참여한 Core Maintainers TSC에서 발표했고, Google도 Core Maintainer로 합류했습니다. Google은 Agents CLI와 Data Agent Kit에서 지원을 시작했다고 밝혔습니다.

기본 구조: plugin.json, skills, mcp.json

Agent Plugin은 디렉터리입니다. 핵심 파일은 plugin.json이고, skill은 skills/ 아래, MCP 서버 선언은 mcp.json에 둡니다. 클라이언트별 확장이 필요하면 reverse-domain 디렉터리, 예를 들어 com.example.client/ 같은 공간을 둡니다. 모르는 클라이언트는 이 확장 디렉터리를 무시합니다.

reports-plugin/
  plugin.json
  skills/
    summarize/
      SKILL.md
      scripts/
      references/
  mcp.json
  com.example.client/

plugin.json은 일부러 작습니다. 이름과 schema 정도만 두고, 컴포넌트를 다른 위치로 옮기거나 inline으로 선언하지 못하게 합니다. 이 제한이 오히려 장점입니다. 클라이언트가 discovery path나 우선순위 규칙을 추측하지 않아도 됩니다. skills/가 있으면 읽고, mcp.json이 있으면 읽고, 실패한 MCP 서버가 있어도 skill 전체가 죽지 않게 독립적으로 처리할 수 있습니다.

언제 plugin을 쓰고 언제 쓰지 말아야 하나

Agent Plugins는 모든 것에 붙이는 포맷이 아닙니다. 단일 MCP 서버를 한 클라이언트에만 배포한다면 mcp.json만으로 충분합니다. 단일 skill만 공유한다면 skill 디렉터리 자체가 더 간단합니다. 플러그인은 여러 구성요소가 함께 움직여야 할 때 가치가 있습니다.

예를 들어 주간 데이터 리포트 에이전트를 생각해봅시다. skill은 “어떤 쿼리를 실행하고 결과를 어떤 형식으로 요약할지”를 설명합니다. MCP 서버는 BigQuery나 사내 DB에 연결합니다. reference 파일은 팀의 지표 정의를 담습니다. 이 세 가지가 따로 배포되면 버전이 어긋날 수 있습니다. 플러그인으로 묶으면 하나의 패키지로 리뷰하고 배포할 수 있습니다.

반대로 “코드 리뷰 시 보안 체크리스트를 참고하라” 정도의 instruction만 있다면 플러그인은 과합니다. 구조가 늘어나는 만큼 유지비도 생깁니다. 실무 기준은 간단합니다. skill과 tool, reference가 함께 버전 관리되어야 하면 plugin을 고려하고, 그렇지 않으면 더 작은 단위를 유지합니다.

v1이 일부러 다루지 않는 것

Agent Plugins v1은 패키지 형식입니다. 설치 방식, 배포 프로토콜, 권한 모델, 샌드박스, provenance 검증, 사용자 승인 UX를 정의하지 않습니다. 이 점을 단점으로 볼 수도 있지만, 현재 단계에서는 현실적인 선택입니다. IDE, CLI, 엔터프라이즈 플랫폼은 보안 요구사항과 사용자 경험이 다릅니다. 포맷이 권한 정책까지 강제하면 채택이 어려워질 수 있습니다.

개발팀은 이 공백을 자체 운영 기준으로 메워야 합니다. 플러그인을 받았다고 바로 실행하면 안 됩니다. 어떤 MCP 서버가 어떤 네트워크 접근을 하는지, 어떤 환경변수를 요구하는지, 어떤 파일을 읽고 쓰는지 확인해야 합니다. skill 문서는 instruction이므로 prompt injection이나 과도한 권한 요청이 없는지도 리뷰해야 합니다.

즉 Agent Plugins는 “안전한 실행 환경”이 아니라 “예측 가능한 패키지 구조”입니다. 안전은 클라이언트와 조직 정책이 담당해야 합니다.

실무 설계 기준

첫째, plugin 이름은 기능 단위로 잡습니다. company-tools처럼 너무 넓으면 버전 관리가 어려워집니다. weekly-report-plugin, incident-review-plugin, customer-support-plugin처럼 업무 결과물이 분명한 이름이 좋습니다.

둘째, skill은 실행 절차 중심으로 씁니다. “친절하게 답하라” 같은 일반 지침보다 입력, 도구 호출 순서, 실패 처리, 산출물 템플릿을 적습니다. MCP 서버가 실패했을 때 대체 경로도 skill에 넣어야 합니다.

셋째, mcp.json의 서버는 명시적으로 선언합니다. transport를 클라이언트가 추측하게 하지 말고, stdio인지 Streamable HTTP인지 분명히 둡니다. 환경변수 요구사항은 README나 reference에 적고, secret 값은 절대 패키지에 넣지 않습니다.

넷째, 클라이언트별 확장은 reverse-domain 디렉터리에 둡니다. 공통 규격에 사내 IDE 전용 command를 억지로 넣으면 portability가 깨집니다. 공통 core와 client-specific extension을 분리해야 오래 갑니다.

버전 관리와 배포 흐름

플러그인은 코드처럼 리뷰해야 합니다. skill 변경은 모델 행동을 바꾸고, MCP 변경은 외부 시스템 접근 방식을 바꿉니다. 따라서 PR에는 변경 요약, 권한 변경, 테스트 방법, 롤백 방법이 포함되어야 합니다.

테스트는 최소 세 단계가 필요합니다. 첫째, manifest schema 검증입니다. 둘째, MCP 서버 부팅 테스트입니다. 셋째, 대표 task를 샌드박스에서 실행해 산출물 형식이 맞는지 확인합니다. 가능하다면 플러그인별 smoke test 명령을 scripts에 넣고 CI에서 돌립니다.

배포는 registry나 catalog와 분리해서 생각해야 합니다. Agentic Resource Discovery나 AI Catalog 같은 검색 계층이 플러그인을 찾게 할 수 있지만, 플러그인 자체는 실행 단위가 아닙니다. 발견, 설명, 패키징, 실행은 서로 다른 계층입니다. 이 구분을 흐리면 운영 문서가 복잡해집니다.

실행 체크리스트

• 단일 skill인지, 단일 MCP인지, 함께 버전 관리할 묶음인지 먼저 판단합니다.
• 함께 움직여야 하는 skill, MCP, reference가 있다면 plugin 구조를 사용합니다.
• plugin.json은 작게 유지하고 컴포넌트 위치를 표준 디렉터리에 둡니다.
• 클라이언트별 확장은 reverse-domain 디렉터리로 분리합니다.
• secret, 토큰, 개인 설정은 플러그인에 포함하지 않습니다.
• MCP 서버의 transport, 필요 권한, 환경변수를 문서화합니다.
• PR에서 skill 변경과 tool 권한 변경을 반드시 리뷰합니다.
• CI에서 schema 검증, MCP 부팅, 샌드박스 smoke test를 실행합니다.
• 설치와 권한 승인은 각 클라이언트 정책으로 별도 통제합니다.

Agent Plugins 1.0.0의 의미는 화려한 에이전트 기능이 아닙니다. Skill과 MCP를 매번 다른 포맷으로 싸는 낭비를 줄이고, 팀이 재사용 가능한 에이전트 기능을 코드처럼 배포하게 만드는 기반입니다. 에이전트가 실험 단계를 지나 조직 도구가 되려면 이런 지루한 패키징 표준이 먼저 필요합니다.