Agent Plugins: 스킬과 MCP를 한 패키지로 묶기

에이전트용 스킬을 하나 잘 만들어 두면 여기저기서 쓰고 싶어집니다. 팀 동료는 클로드 코드 대신 Codex를 쓰고, 다른 동료는 Cursor를 쓰니까요.

스킬만 나눠주는 거라면 방법은 이미 있습니다. skills.sh의 npx skills add에 -a '*'를 붙이면 지원하는 코딩 에이전트 전부에 같은 스킬을 한 번에 설치해 주거든요. 진짜 문제는 스킬이 혼자 굴러가지 않을 때 드러납니다. 배포 상태를 조회하는 MCP 서버가 있어야 동작하는 스킬이라면, 서버 설정은 여전히 도구마다 손으로 넣어야 하죠. 스킬과 도구가 한 몸인데 배포는 따로 노는 셈입니다. 😅

바로 이 문제를 겨냥한 개방형 스펙이 발표되었습니다. Vercel이 주도하고 OpenAI, Microsoft, AWS, Cursor가 함께 만든 Agent Plugins 1.0인데요. Agent Skills와 MCP(Model Context Protocol) 서버를 하나의 패키지로 묶어서 호환되는 에이전트라면 어디서든 그대로 로드할 수 있게 해줍니다. 이번 글에서는 이 스펙이 풀려는 문제와 패키지의 실제 구조를 차근차근 살펴보겠습니다.

Agent Plugins란?

Agent Plugins는 AI 에이전트의 기능을 담는 표준 패키지 형식입니다. 여기서 중요한 점은 새로운 기능을 정의하는 스펙이 아니라는 것인데요. 에이전트 생태계에는 이미 두 개의 축이 자리 잡고 있습니다. 반복 작업의 절차와 지식을 재사용할 수 있게 해주는 Agent Skills, 그리고 데이터베이스나 브라우저 같은 외부 시스템을 런타임에 연결해주는 MCP입니다. Agent Plugins는 이 둘을 전혀 건드리지 않고, 두 컴포넌트를 하나의 디렉토리에 어떻게 담아서 배포할지만 정의합니다.

배포 보조 에이전트를 만든다고 생각해 볼까요? 언제 배포해도 되는지, 어떤 검사를 돌려야 하는지, 실패하면 어떻게 대응하는지는 스킬에 적어둡니다. 배포 상태를 조회하고 롤백을 실행하는 도구는 MCP 서버로 노출합니다. 지금까지는 이 두 가지를 쓰는 에이전트마다 제각각 설치해야 했지만, Agent Plugins에서는 하나의 플러그인으로 묶어 두면 어느 에이전트에서든 파일을 재배치하거나 매니페스트(manifest)를 고칠 필요 없이 그대로 로드할 수 있습니다.

flowchart TB
    accTitle: Agent Plugins 패키지와 에이전트의 관계
    accDescr: Agent Skills와 MCP 서버 설정을 plugin.json 매니페스트와 함께 하나의 플러그인 패키지로 묶으면, Codex, Cursor, GitHub Copilot 같은 호환 에이전트가 같은 패키지를 그대로 로드한다.

    subgraph plugin["플러그인 패키지"]
        direction TB
        manifest["plugin.json<br/>매니페스트"]
        skills["skills/<br/>Agent Skills"]
        mcp["mcp.json<br/>MCP 서버 설정"]
    end

    plugin --> codex["Codex"]
    plugin --> cursor["Cursor"]
    plugin --> copilot["GitHub Copilot"]

    classDef component stroke:#7c3aed,stroke-width:2px
    classDef client stroke:#0284c7,stroke-width:2px

    class manifest,skills,mcp component
    class codex,cursor,copilot client

발표 시점에 ChatGPT와 Codex, Cursor, GitHub Copilot, Kiro, VS Code가 호환 에이전트로 이름을 올렸습니다. 스펙은 공개 라이선스로 GitHub의 agent-plugins-spec 저장소에서 관리되며, 기술 운영 위원회에는 참여사의 핵심 유지보수자들이 들어가 있습니다.

패키지 구조

플러그인은 파일 시스템의 한 디렉토리에 뿌리를 둔 패키지입니다. 표준 레이아웃은 다음과 같습니다.

my-plugin/
├── plugin.json          # 매니페스트 (필수)
├── skills/              # Agent Skills
│   └── summarize/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
├── mcp.json             # MCP 서버 설정
└── com.example.client/  # 에이전트 전용 확장

눈에 띄는 특징은 매니페스트가 아주 가볍다는 점입니다. plugin.json의 필수 필드는 스키마와 이름, 딱 둘뿐입니다.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-plugin"
}

여기에 version, description, author, license, keywords 같은 선택 필드를 추가할 수 있지만, 매니페스트가 패키지에 어떤 컴포넌트가 들었는지 나열하지는 않습니다. 나머지 계약은 디렉토리 구조 자체가 표현하는데요. 에이전트는 skills/ 디렉토리와 mcp.json이라는 고정된 위치를 직접 확인해서 컴포넌트를 발견합니다. 설정 파일을 파싱해 경로를 알아내는 과정이 없으니 구현이 단순해지고, 어떤 에이전트가 열어도 같은 결과가 나옵니다.

플러그인 이름에는 제약이 있습니다. 1~64자 길이에 소문자와 숫자, 하이픈, 마침표만 쓸 수 있고, 시작과 끝은 영숫자여야 합니다. my-plugin이나 acme.tools는 유효하지만 My-Plugin은 대문자 때문에 거부됩니다.

스킬 발견 규칙

스킬을 찾는 규칙은 단순합니다. skills/ 바로 아래의 하위 디렉토리 중에서 SKILL.md 파일을 가진 디렉토리 하나하나를 스킬로 취급합니다. 더 깊은 곳은 탐색하지 않기 때문에, 스킬을 중첩해서 숨겨두는 구조는 만들 수 없습니다. 각 스킬은 기존 Agent Skills 스펙을 그대로 따르므로, 이미 만들어 둔 스킬 디렉토리를 통째로 복사해 넣으면 그걸로 끝입니다. 스킬을 직접 설계하고 작성하는 방법은 SKILL.md 작성 가이드에서 자세히 다뤘습니다.

mcp.json과 경로 변수

MCP 서버는 mcp.json에 선언합니다. 서버마다 type 키로 전송 방식(transport)을 고르는데, 로컬 프로세스로 띄우는 stdio, 원격 서버에 연결하는 streamable-http, 레거시 호환용 sse 세 가지가 있습니다.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "local-validator": {
      "type": "stdio",
      "command": "./bin/validator",
      "args": ["--data", "${PLUGIN_DATA}/validator"],
      "env": {
        "CONFIG": "${PLUGIN_ROOT}/config.json"
      }
    },
    "deployment-api": {
      "type": "streamable-http",
      "url": "https://deploy.example.com/mcp"
    }
  }
}

최상위에는 $schema와 mcpServers 두 가지만 올 수 있고 둘 다 필수입니다. mcpServers 아래의 키(local-validator, deployment-api)는 서버를 구분하는 이름이고요. type을 무엇으로 정하느냐에 따라 함께 쓸 수 있는 속성이 달라집니다.

스키마가 정의하지 않은 속성은 거부되므로 오타가 조용히 넘어가지 않습니다.

이 파일에는 이식성을 위한 장치가 두 가지 숨어 있는데요. 우선 command에는 실행할 프로그램 하나만 적어야 합니다. 터미널에 치듯 인자를 붙여 쓸 수 없다는 뜻입니다.

{ "command": "bunx server --port 3000" }

{ "command": "bunx", "args": ["server", "--port", "3000"] }

command에 적은 값이 ./로 시작하면 플러그인 루트 기준 상대 경로로, 그냥 이름이면 플랫폼의 실행 경로에서 찾습니다. 이렇게 프로그램과 인자를 분리해 두면 셸을 거치지 않으므로, 운영체제마다 따옴표 처리가 달라지는 문제도 명령어 주입의 여지도 사라집니다.

또 하나는 경로 변수입니다. 플러그인은 자신이 어디에 설치될지 모르기 때문에 절대 경로를 하드코딩할 수 없습니다. 그래서 스펙은 두 개의 경로 변수를 정의합니다. ${PLUGIN_ROOT}는 플러그인 루트의 절대 경로로, ${PLUGIN_DATA}는 에이전트가 관리해주는 플러그인 전용 영속 데이터 디렉토리로 치환됩니다. 에이전트는 서브프로세스를 실행할 때 같은 이름의 환경 변수도 함께 넣어줍니다. 그래서 env에는 이 두 이름을 쓸 수 없습니다. 플러그인이 값을 덮어쓰지 못하도록 스키마가 아예 막아뒀거든요. 참고로 원격 URL은 HTTPS가 강제되며, 평문 HTTP는 localhost 같은 루프백 주소에서만 허용됩니다.

직접 만들어보기

앞에서 예로 든 배포 보조 플러그인을 실제로 만들어보겠습니다. 필요한 건 디렉토리 세 개와 파일 세 개가 전부입니다.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "deploy-helper",
  "version": "0.1.0",
  "description": "배포 절차와 롤백 도구를 함께 제공하는 플러그인",
  "license": "MIT"
}

배포 절차는 skills/deploy/SKILL.md에 담습니다. 기존에 쓰던 스킬이 있다면 디렉토리를 그대로 옮겨 넣으면 됩니다.

---
name: deploy
description: 프로덕션 배포 전 검사와 실패 시 롤백 절차를 안내한다.
---

# 배포 절차

1. `bun run test`로 E2E 테스트를 통과시킨다.
2. 배포 상태를 조회해 진행 중인 배포가 없는지 확인한다.
3. 실패하면 직전 성공 배포로 롤백한다.

배포 상태 조회와 롤백을 담당할 원격 MCP 서버는 mcp.json에 선언합니다.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "deployment-api": {
      "type": "streamable-http",
      "url": "https://deploy.example.com/mcp"
    }
  }
}

완성된 구조는 이렇게 단순합니다.

deploy-helper
├── mcp.json
├── plugin.json
└── skills
    └── deploy
        └── SKILL.md

3 directories, 3 files

매니페스트가 스펙에 맞는지는 공식 JSON 스키마로 검증할 수 있습니다. $schema 필드에 적어둔 URL이 그대로 실제 스키마 문서라서, ajv 같은 검증 도구에 바로 물려주면 됩니다.

curl -O https://agent-plugins.org/schemas/1.0.0/plugin.schema.json
bunx ajv-cli validate --spec=draft2020 -s plugin.schema.json -d deploy-helper/plugin.json

deploy-helper/plugin.json valid

앞에서 이름 규칙이 까다롭다고 했는데, 실제로 어긋나면 어떻게 되는지도 확인해볼까요? name을 Deploy-Helper로 바꾸고 다시 돌려보면 대문자 때문에 정규식 패턴에 걸립니다.

deploy-helper/plugin.json invalid
[
  {
    instancePath: '/name',
    schemaPath: '#/properties/name/pattern',
    keyword: 'pattern',
    params: {
      pattern: '^(?!.*(?:--|\\.\\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$'
    },
    message: 'must match pattern "^(?!.*(?:--|\\.\\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$"'
  }
]

스키마가 공개되어 있으니 CI에 이 검증 한 줄을 걸어두면, 플러그인을 배포하기 전에 형식 오류를 미리 걸러낼 수 있습니다.

에이전트 확장과 실패 격리

표준이 스킬과 MCP만 다룬다면, 각 에이전트의 고유 기능은 어디에 둘까요? 스펙은 역도메인(reverse domain) 네임스페이스라는 통로를 열어뒀습니다. 매니페스트의 extensions 필드나 최상위 디렉토리에 com.example.client 같은 이름을 붙여 에이전트 전용 데이터를 담는 방식입니다.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-plugin",
  "extensions": {
    "com.example.client": {
      "autoApprove": true
    }
  }
}

핵심 규칙은 에이전트가 자신이 구현하지 않은 네임스페이스를 내용 검증 없이 무시해야 한다는 점입니다. 어떤 에이전트 전용 설정이 들어 있어도 다른 에이전트에서 로드가 깨지지 않습니다.

호환 에이전트가 되기 위한 문턱도 낮습니다. 스킬과 MCP 서버라는 두 컴포넌트 타입 중 최소 하나만 지원하면 되고, MCP를 지원하는 경우에도 stdio나 streamable-http 중 한 가지 전송 방식만 구현하면 됩니다. 구현 부담을 줄여야 더 많은 에이전트가 빠르게 올라탈 수 있다는 계산이겠죠.

같은 철학이 실패 처리에도 흐릅니다. plugin.json 자체가 없거나 스키마에 어긋나면 플러그인 전체가 거부되지만, 그 아래에서 일어나는 문제는 최대한 좁게 격리됩니다. 스킬 하나가 스펙에 맞지 않으면 그 스킬만 건너뜁니다. MCP 서버 항목이 잘못되었을 때도, 지원하지 않는 전송 방식을 만났을 때도 해당 서버 하나만 무효 처리하고 나머지는 계속 로드하고요. 플러그인에 담긴 컴포넌트가 많아져도 사소한 문제 하나가 전체를 무너뜨리지 않도록 실패 경계를 스펙 차원에서 정해둔 셈입니다.

의도적으로 다루지 않는 것

1.0 스펙에서 눈여겨볼 부분은 오히려 빠진 목록입니다. 슬래시 커맨드나 훅(hook), 서브에이전트 같은 컴포넌트는 여러 에이전트에 비슷한 개념이 존재하는데도 제외되었습니다. 커맨드가 무엇을 할 수 있는지, 훅이 언제 실행되는지가 도구마다 다른 상태에서 형식만 표준화하면 껍데기만 호환되는 결과가 나오기 때문인데요. 에이전트 간 의미가 합의되고 구현 의향이 확인된 컴포넌트만 이후 버전에서 추가하겠다는 입장입니다.

배포와 신뢰 영역도 스펙 밖입니다. 레지스트리와 마켓플레이스, 설치와 업데이트, 권한과 샌드박싱, 서명과 발행자 검증은 모두 에이전트와 생태계의 몫으로 남겨졌습니다. 이미 MCP 서버는 MCP Registry에서, 스킬은 skills.sh 같은 카탈로그에서 찾는 흐름이 만들어져 있는데, Agent Plugins는 그 위에 얹히는 패키징 계층일 뿐 검색과 신뢰까지 떠안지 않겠다는 겁니다.

이렇게 관심사를 나눠 놓고 보면 지금 에이전트 생태계가 어떤 층으로 쌓이고 있는지가 한눈에 들어옵니다.

각 층이 독립적으로 발전할 수 있다는 게 이 구분의 이점입니다. 스킬 스펙이 개선되어도 패키징 형식은 그대로 두면 되고, 새로운 레지스트리가 나와도 플러그인 구조는 손댈 필요가 없습니다. 발표 글은 이를 두고 “에이전트가 혁신을 계속하면서도 수렴할 수 있는 공간”을 만드는 것이 목표라고 설명합니다.

참고로 이번 발표 글은 Linux Foundation 산하 Agentic AI Foundation(AAIF) 블로그에도 게스트 포스트로 실렸는데요, Agent Plugins 자체는 AAIF 프로젝트가 아니라 독립적으로 관리되는 스펙입니다.

벌써 올라탄 에이전트들

표준이 문서로만 남을 걱정은 접어도 될 것 같습니다. 발표 당일부터 실제 구현이 붙기 시작했거든요.

AWS는 스펙이 공개된 8월 6일에 맞춰 Kiro와 AWS Agent Toolkit에서 지원을 시작했습니다. AWS Agent Toolkit은 Lambda나 S3, DynamoDB, CDK 같은 서비스를 다루는 서른 개 넘는 스킬을 여러 플러그인에 나눠 담은 공식 묶음인데요. 스펙에 맞춰 배포되니 Kiro가 아닌 다른 에이전트에서도 그대로 집어 쓸 수 있습니다.

하루 뒤인 8월 7일에는 Codex CLI 0.147.0이 나왔습니다. 릴리즈 노트의 새 기능 첫 줄이 플러그인 설치와 카탈로그 검색인데, 로컬과 개인, 워크스페이스, 원격까지 네 종류의 카탈로그를 한 번에 뒤집니다. 스펙이 발견 계층을 비워둔 자리를 에이전트가 어떻게 채우는지 보여주는 또 하나의 예입니다.

Cursor는 자체 플러그인 형식을 이미 갖고 있었는데도 표준을 나란히 받아들였습니다. 공식 문서에서 스펙을 따르는 플러그인은 아무것도 고치지 않아도 Cursor에서 로드된다고 안내하고 있고요. 자체 형식은 매니페스트를 .cursor-plugin/plugin.json에 두고 룰과 에이전트, 커맨드, 훅까지 담는 별도 체계로 남겨둔 채, 표준 플러그인은 표준대로 읽는 방식입니다.

GitHub Copilot이 보여준 그림

그중 가장 자세한 그림을 내놓은 곳은 GitHub입니다. 8월 12일, VS Code와 Copilot CLI, Copilot SDK, Copilot 앱에서 Agent Plugins 1.0 지원을 정식 출시했는데요. 별도 미리보기 없이 모든 Copilot 요금제에 한꺼번에 열렸습니다. 참고로 스펙 발표 당일에는 Google도 핵심 유지보수자로 합류해서 참여사 명단이 한 번 더 늘었습니다.

눈여겨볼 부분은 GitHub이 앞에서 살펴본 두 가지 설계를 어떻게 써먹었는가입니다.

먼저 역도메인 네임스페이스입니다. 기존 Copilot 플러그인을 표준에 맞추는 작업은 매니페스트 손질이 거의 전부인데요. plugin.json에 $schema 필드를 추가하고, 스킬은 skills/에 MCP 설정은 mcp.json에 그대로 두고, Copilot 전용 파일만 com.github.copilot/ 디렉토리로 옮기면 됩니다.

my-plugin/
├── plugin.json           # $schema 필드만 추가
├── skills/               # 그대로
├── mcp.json              # 그대로
└── com.github.copilot/   # 커스텀 에이전트, 커맨드, 룰, 훅, 캔버스

스펙이 표준화를 미뤄둔 커맨드와 훅, 서브에이전트가 바로 이 통로로 들어갑니다. 다른 에이전트는 이 디렉토리를 통째로 무시하니 이식성이 깨지지 않고, Copilot 쪽에서는 VS Code든 Copilot CLI든 Copilot 앱이든 여기서 고유 기능을 읽어갑니다. 네임스페이스가 왜 필요한지를 보여주는 첫 실제 사례인 셈이죠.

다음은 스펙이 비워둔 발견과 신뢰 영역입니다. 플러그인을 찾는 자리는 Awesome Copilot 마켓플레이스가 채웁니다. VS Code와 Copilot CLI, Copilot 앱에 기본으로 연결되어 있어서 별도 등록 없이 바로 설치할 수 있습니다. 조직 차원의 통제는 기존 관리 설정 파일인 managed-settings.json이 그대로 맡는데요. enabledPlugins로 특정 플러그인을 자동 설치하거나 차단하고, extraKnownMarketplaces로 쓸 수 있는 마켓플레이스를 늘리고, strictKnownMarketplaces로 관리 대상 마켓플레이스에서만 설치하도록 제한합니다. MCP 서버를 품은 플러그인이라면 기존 MCP 허용 목록(allowlist)과 짝지어 URL이나 명령, 이름 단위로 서버를 승인하거나 막을 수도 있고요.

GitHub이 덧붙인 한 문장이 인상적입니다. 이미 Copilot 플러그인을 통제하는 설정이 있다면 Agent Plugins 1.0에도 그대로 적용되니 별도의 정책이 필요 없다는 것인데요. 표준을 받아들이면서 기존 거버넌스 체계는 하나도 건드리지 않았다는 뜻입니다. 스펙이 배포와 신뢰를 에이전트 몫으로 남긴 이유가 여기서 드러납니다. 각 에이전트가 이미 갖춘 정책 체계를 그대로 쓰게 두면, 표준을 도입하는 쪽에서도 새로 배울 게 없으니까요.

기존 플러그인이 마이그레이션 없이 계속 동작한다는 점도 부담을 덜어줍니다. 표준을 따를지는 각자의 선택이고, 따르기로 하면 같은 패키지를 다른 에이전트에서도 열 수 있다는 게 얻는 것입니다.

클로드 코드는 어디에?

그런데 이 구조, 어딘가 익숙하지 않으신가요? 클로드 코드는 이미 2025년 10월부터 자체 플러그인 시스템을 운영하고 있습니다. plugin.json 매니페스트 아래 스킬, MCP 서버, 슬래시 커맨드, 훅, 서브에이전트를 한 패키지로 묶어 마켓플레이스로 배포하는 방식이죠. 자세한 사용법은 클로드 코드 플러그인 사용법에서 다룬 적이 있습니다. Agent Plugins 1.0은 이 모델에서 에이전트 간에 의미가 통하는 교집합, 즉 스킬과 MCP만 추려서 표준화한 모양새입니다.

흥미로운 대목은 참여사 명단입니다. 기술 운영 위원회에 Anthropic이 없고, 출시 시점 호환 에이전트 목록에도 클로드 코드가 빠져 있습니다. 정작 이 스펙의 절반을 차지하는 Agent Skills는 Anthropic이 agentskills.io에서 공식 스펙을 호스팅하고 있는데 말이죠. 프로젝트 안내 파일 영역에서 AGENTS.md와 CLAUDE.md가 각자 출발했다가 표준화 움직임으로 이어졌던 것처럼, 플러그인 형식도 비슷한 길을 걷게 될지 지켜볼 만합니다. Anthropic이 위원회에 합류할지도 앞으로의 관전 포인트고요.

마치며

Agent Plugins 1.0은 화려한 신기능 없이 디렉토리 구조와 매니페스트, 발견 규칙만 정의한 작은 스펙입니다. 하지만 한 번 패키징하면 어디서나 로드된다는 약속은 생각보다 큰 변화를 예고하는데요. npm 패키지나 컨테이너 이미지가 그랬듯, 패키징 형식이 표준화되면 그 위에 공유 카탈로그, 조직 차원의 검증 정책, 크로스 에이전트 도구 같은 다음 단계가 열리기 때문입니다.

당장 무언가를 갈아엎을 필요는 없습니다. 스킬과 MCP 서버를 이미 만들어 쓰고 계시다면 그 자산이 그대로 플러그인의 내용물이 되니까요. 지금 쓰는 도구가 아직 호환 목록에 없더라도, 스킬 디렉토리와 MCP 설정을 깔끔하게 분리해 두는 것만으로 나중에 plugin.json 하나만 얹으면 됩니다. 스킬과 그 스킬이 기대는 도구를 따로 배포하던 수고가 머지않아 사라질지도 모르겠습니다.

더 자세한 내용은 Agent Plugins 공식 스펙과 GitHub Copilot의 지원 발표를 참고하세요.