Agent Plugins 1.0: 에이전트 스킬과 MCP를 한 디렉토리로 묶는 패키징 표준

에이전트에 기능을 붙이는 두 조각은 이미 표준이 있습니다. 모델에게 절차적 지식을 주는 Agent Skills와 외부 도구·데이터에 연결하는 MCP입니다. 두 규약 모두 여러 클라이언트가 이미 지원합니다. 그런데 이 조각들을 실제로 배포하려고 하면 예상치 못한 곳에서 마찰이 생깁니다. 컴포넌트 자체는 멀쩡한데 그것을 담는 상자가 클라이언트마다 다르기 때문입니다.

2026년 8월 6일에 발표된 Agent Plugins 1.0.0이 이 상자를 표준화합니다. 오픈이고 벤더에 중립적인 패키징 표준이며, 기술 운영 위원회의 코어 메인테이너는 Amazon, Cursor, Microsoft, OpenAI, Vercel입니다. 발표 이후 Google이 코어 메인테이너로 합류했고, DeepMind의 Kevin Hou가 대표를 맡았습니다. 이 글에서는 표준이 무엇을 정의하고 무엇을 일부러 정의하지 않았는지를 코드 예시와 함께 살펴봅니다.

문제는 컴포넌트가 아니라 상자였다

같은 스킬 하나를 서로 다른 두 클라이언트에 올린다고 해봅시다. 스킬을 기술하는 SKILL.md는 Agent Skills 스펙을 따르므로 양쪽에서 동일합니다. 그런데 그 스킬을 “어디에 두고, 어떤 매니페스트로 선언하는가"는 클라이언트마다 제각각이었습니다. 한쪽은 매니페스트에서 스킬 경로를 인라인으로 지정하고, 다른 쪽은 별도 레지스트리 파일에 등록하는 식입니다. 같은 스킬을 감싸는 래퍼를 두 벌 유지하게 됩니다.

# 클라이언트 A가 기대하는 배치
client-a/
  manifest.yaml          # skills: [{ path: ./my-skill/SKILL.md }]
  my-skill/
    SKILL.md             # <- 동일한 스킬 본문

# 클라이언트 B가 기대하는 배치
client-b/
  plugin.config.json     # { "skillDir": "abilities", "entry": "index" }
  abilities/
    my-skill/
      SKILL.md           # <- 완전히 똑같은 스킬 본문

스킬 본문은 양쪽이 완전히 같은데, 그것을 감싸는 포장만 서로 다릅니다. 한쪽 매니페스트에서 경로를 고치면 다른 쪽도 똑같이 손봐야 하고, 이 동기화를 한 번 놓치면 두 사본이 조금씩 어긋나기 시작합니다. 스킬이 열 개, 클라이언트가 세 개로 늘어나면 이 표류(drift)는 관리가 불가능한 수준이 됩니다. 컴포넌트 규약은 이미 이식성이 있는데, 그 컴포넌트를 담는 포장 방식에 이식성이 없어서 생기는 문제입니다.

Agent Plugins 1.0이 정의하는 것: 플러그인은 그냥 디렉토리다

Agent Plugins의 해법은 단순합니다. 플러그인은 매니페스트 하나와 몇 가지 선택적 컴포넌트를 담은 자기 완결적 디렉토리이고, 그 루트에는 반드시 plugin.json이 있어야 합니다. 표준 레이아웃은 다음과 같습니다.

reports-plugin/
├── plugin.json              # 매니페스트 (필수, 루트에 위치)
├── skills/                  # 에이전트 스킬 (고정 위치)
│   └── summarize/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
├── mcp.json                 # MCP 서버 선언 (고정 위치)
├── bin/                     # mcp.json이 실행하는 서버 바이너리
│   └── report-server
├── data/                    # 서버 작업 디렉토리
├── com.example.client/      # 클라이언트 전용 확장 (역도메인 네임스페이스)
├── LICENSE                  # 선택
└── CHANGELOG.md             # 선택

여기서 눈에 띄는 두 가지가 있습니다. 첫째, 스킬은 항상 skills/ 아래에, MCP 서버는 항상 mcp.json에 있습니다. 위치가 표준으로 고정되어 있어서 클라이언트마다 다르게 뒤질 필요가 없습니다. 둘째, 클라이언트가 자기만의 정보를 얹고 싶으면 com.example.client/처럼 역도메인 네임스페이스 디렉토리를 씁니다. 표준이 정의한 공간과 벤더가 확장하는 공간이 이름 충돌 없이 분리됩니다.

매니페스트는 아주 작아도 됩니다. 최소한의 plugin.json은 실질적으로 두 줄이면 충분합니다.

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

이 두 필드만 있으면 위 디렉토리는 유효한 플러그인입니다. 물론 실제 배포에서는 메타데이터를 더 채웁니다. 전체 매니페스트는 다음과 같은 모양입니다.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "reports-plugin",
  "version": "1.2.0",
  "description": "회계 데이터를 요약해 리포트를 생성하는 스킬과 MCP 서버 묶음",
  "author": {
    "name": "Acme Data Team",
    "url": "https://acme.example"
  },
  "homepage": "https://acme.example/plugins/reports",
  "repository": "https://github.com/acme/reports-plugin",
  "license": "Apache-2.0",
  "keywords": ["reporting", "summarization", "bigquery"]
}

매니페스트 해부: 닫힌 스키마

plugin.json의 스키마는 닫혀(closed) 있습니다. 허용되는 최상위 필드는 아래 열 개가 전부이고, 그 외의 다른 최상위 필드는 스키마가 알지 못합니다.

필드	필수 여부	검증 방식
`$schema`	필수	1.0.0의 표준 식별자와 정확히 일치해야 함
`name`	필수	이름 규칙(아래 표) 적용
`version`	선택	JSON 타입만 검사 (SemVer 강제 아님)
`description`	선택	JSON 타입만 검사
`author`	선택	`name`·`email`·`url` 문자열만 허용하는 객체
`homepage`	선택	JSON 타입만 검사
`repository`	선택	JSON 타입만 검사
`license`	선택	JSON 타입만 검사 (SPDX 강제 아님)
`keywords`	선택	JSON 타입만 검사
`extensions`	선택	확장 선언용

여기서 검증 규칙이 두 갈래로 갈립니다. 클라이언트가 모르는 최상위 필드를 만나면, 그 필드를 보고하고 무시하되 플러그인은 계속 로드합니다. 오타로 넣은 필드 하나 때문에 플러그인 전체가 죽지는 않습니다. 반면 그 밖의 스키마 위반, 예를 들어 필수 필드가 없거나 $schema가 표준 식별자와 다르면, 이것은 치명적(fatal) 오류이고 매니페스트가 무효가 되어 플러그인이 거부됩니다. “관대하게 넘어갈 실수"와 “반드시 막아야 할 위반"의 경계를 표준이 명확하게 그어 둔 셈입니다.

이름 필드는 규칙이 구체적입니다. 소문자 a-z, 숫자 0-9, 하이픈, 마침표만 쓸 수 있고, 길이는 1자에서 64자 사이입니다. 첫 글자와 끝 글자는 영숫자여야 하며, --나 ..처럼 같은 기호가 연달아 오면 안 됩니다.

유효한 이름	무효한 이름	무효 사유
`my-plugin`	`My-Plugin`	대문자 사용
`acme.tools`	`-start`	하이픈으로 시작
`lint3r`	`has--double`	하이픈 연속
`a`	`too.many..dots`	마침표 연속

$schema에 대해 하나 짚어 둘 점이 있습니다. 이 필드는 매니페스트가 어느 버전을 따르는지 알려주는 고정된 식별 문자열이지, 클라이언트더러 로드하는 도중에 그 URL로 원격 스키마를 받아오라는 지시가 아닙니다. 값이 표준 식별자와 정확히 같은지만 확인하면 되고, 네트워크로 스키마를 가져오는 동작은 표준이 요구하지 않습니다. 오프라인에서도, 외부 도메인이 죽어 있어도 검증이 동작해야 하기 때문입니다.

컴포넌트 발견: 위치가 고정되어 있고, 인라인 선언이 없다

앞서 본 것처럼 스킬은 skills/ 아래 하위 디렉토리마다 SKILL.md로, MCP 서버는 루트의 mcp.json으로 발견됩니다. 중요한 제약은 plugin.json이 이 위치를 재정의하거나 컴포넌트를 인라인으로 선언할 수 없다는 점입니다. 매니페스트에 “내 스킬은 사실 abilities/에 있어"라고 적어 방향을 트는 일이 불가능합니다. 발견 규칙에 예외가 없으니, 어느 클라이언트든 같은 자리를 보면 됩니다.

mcp.json에서 stdio 방식 서버를 선언하는 예시는 다음과 같습니다.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "report-db": {
      "type": "stdio",
      "command": "./bin/report-server",
      "args": ["--mode", "readonly"],
      "env": {
        "LOG_LEVEL": "info"
      },
      "cwd": "./data"
    }
  }
}

각 필드의 의미는 이렇습니다. type은 전송 방식이고 stdio에서는 필수입니다. command는 실행할 단일 실행 파일 토큰이며, 셸에 넘길 명령 문자열이 아닙니다. 즉 "./bin/server --flag"처럼 인자를 붙여 넣으면 안 되고, 인자는 args 배열로 분리해야 합니다. env는 문자열 값을 담은 환경 변수 객체, cwd는 서버를 띄울 작업 디렉토리입니다. cwd를 생략하면 플러그인 루트가 기본값이 됩니다.

여기서 보안 관점의 규칙 하나가 등장합니다. 플러그인 안에서 쓰는 상대 경로는 반드시 ./로 시작해야 하고, 파일시스템에서 해석된 최종 경로가 플러그인 루트 밖으로 벗어나면 안 됩니다. 경로 격리(path containment)라고 부르는 규칙입니다.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "ok": {
      "type": "stdio",
      "command": "./bin/server",
      "cwd": "./data"
    }
  }
}

위는 유효합니다. ./bin/server와 ./data 모두 플러그인 루트 안쪽을 가리킵니다. 반면 아래는 무효입니다.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "bad": {
      "type": "stdio",
      "command": "../bin/server",
      "cwd": "data"
    }
  }
}

../bin/server는 상위 디렉토리로 올라가 플러그인 루트를 탈출하고, cwd의 data는 ./로 시작하지 않아 플러그인 상대 경로가 아닙니다. 이 규칙이 있으면 플러그인 하나가 호스트 파일시스템의 임의 위치를 실행하거나 참조하도록 매니페스트를 조작하는 경로가 원천적으로 닫힙니다. 배포 가능한 포맷을 정의할 때 경로 탈출을 스펙 수준에서 막아 두는 것은 신뢰 경계를 다루는 좋은 출발점입니다.

독립 실패: 서버 하나가 죽어도 스킬은 산다

실제 배포에서 컴포넌트 하나가 잘못되는 일은 흔합니다. MCP 서버의 실행 파일이 없거나, 지원하지 않는 전송 방식을 썼거나, 시작하다가 죽을 수 있습니다. Agent Plugins는 이런 국소적 실패가 플러그인 전체를 무너뜨리지 않도록 설계했습니다. 한 컴포넌트 타입이나 개별 항목, 또는 그 프로세스에서 생긴 실패가 나머지 정상 컴포넌트의 로드까지 막아서는 안 된다는 원칙입니다.

reports-plugin/
├── plugin.json
├── skills/
│   ├── summarize/SKILL.md      # 정상 -> 로드됨
│   └── translate/SKILL.md      # 정상 -> 로드됨
└── mcp.json
        └── report-db 서버 시작 실패    # 이 항목만 건너뜀 + 보고

mcp.json에 선언한 report-db 서버가 시작에 실패하면, 클라이언트는 그 항목만 건너뛰고 실패를 보고한 뒤 나머지를 계속 로드합니다. skills/의 두 스킬은 멀쩡히 살아 있습니다. 무효한 스킬이 섞여 있어도 그 스킬만 건너뛰고 나머지 스킬은 로드됩니다. 컴포넌트 사이에 “모 아니면 도” 식의 연쇄 실패가 없도록 격리한 것입니다. 여러 컴포넌트를 묶어 함께 배포하는 포맷이라면 이런 독립 실패 보장은 반드시 있어야 합니다.

일부러 정의하지 않은 것: 절제된 스코프

Agent Plugins 1.0에서 주목할 점은 정의하지 않기로 한 목록입니다. v1은 컴포넌트 타입을 정확히 두 가지, 스킬과 MCP 서버로 한정합니다. 커맨드, 훅, 에이전트, 규칙, LSP 서버 같은 것들은 아직 클라이언트별 편차가 커서, 이식 가능한 안정적 계약으로 굳히기에는 이르다고 보고 뺐습니다.

더 나아가 FUTURE_CONSIDERATIONS 문서는 다음 항목들을 명시적으로 뒤로 미룹니다.

트러스트·권한 모델과 샌드박싱: v1.0.0은 플러그인에 대한 트러스트 모델도, 권한 시스템도, 샌드박싱 요건도 정의하지 않습니다. 플러그인별 능력 제한이나 등급별 신뢰 수준은 이후 논의로 남았습니다.
프로버넌스·무결성 검증: 플러그인이 주장하는 출처에서 실제로 왔는지, 변조되지 않았는지 확인하는 방법을 v1.0.0은 규정하지 않습니다. 게시된 플러그인에 대한 암호학적 서명 검증 같은 개념이 여기 해당합니다.
secret 처리: 민감한 값을 어떻게 제공하고 저장하고 범위를 한정할지도 정의하지 않았습니다.
승인 UX: 임의 명령을 실행하거나 외부 서비스에 접근하는 MCP 서버를 사용자가 승인하는 인터페이스도 표준 밖에 있습니다.

설치·배포 방식 자체도 표준의 관심사가 아닙니다. 설계 결정 문서는 아카이브 포맷(.zip, .tar.gz)이나 레지스트리에서 받아오는 번들 대신 파일시스템 디렉토리를 패키지 단위로 택한 이유를 설명하는데, 발견 과정의 우회, 대체 소스 우선순위, 매니페스트 설정 같은 복잡성을 없애기 위해서입니다. 결과적으로 v1이 정의하는 것은 디스크 위의 패키지·매니페스트·컴포넌트 포맷뿐입니다.

이 절제가 왜 옳은 선택인지는 채택자의 처지를 보면 드러납니다. IDE, CLI, 엔터프라이즈 플랫폼은 설치 흐름과 정책 의무가 서로 다릅니다. 엔터프라이즈는 감사 추적과 승인 게이트가 필요하고, 로컬 CLI는 그런 무게가 오히려 방해가 됩니다. 이런 것까지 v1에 욱여넣었다면 어느 진영도 그대로 채택하기 어려운 스펙이 됐을 것입니다. 포장의 모양만 먼저 합의하고, 신뢰와 배포처럼 진영마다 답이 다른 부분은 각자 채우도록 열어 둔 것입니다.

생태계 네 계층: 찾고, 기술하고, 포장하고, 실행한다

Google 발표 블로그는 이 표준을 더 큰 그림 안에 놓습니다. 에이전트가 외부 능력을 쓰는 과정을 네 개의 독립적인 층으로 나누는데, Agent Plugins는 그중 세 번째 층입니다.

Find, Describe, Package, Run 네 층으로 나뉜 에이전트 생태계 스택. ARD는 찾기, AI Catalog는 기술, Agent Plugins 1.0은 포장, MCP와 Agent Skills는 실행 층을 맡으며 각 층은 독립적으로 채택할 수 있다

에이전트가 외부 능력을 쓰는 과정을 네 층으로 나눈 스택. Agent Plugins는 세 번째 포장 층이며, 각 층은 다음 층을 강제하지 않고 독립적으로 채택할 수 있습니다. 출처: Agent Plugins Specification v1.0.0 및 Google Developers Blog.

Find(찾기): Agentic Resource Discovery(ARD)라는 열린 발견 프로토콜입니다. 클라이언트가 “이 작업에 쓸 수 있는 게 뭐가 있지?“라고 물을 수 있게 합니다.
Describe(기술): ARD가 색인하는 항목 포맷인 AI Catalog입니다. 여기에 플러그인이라는 새 콘텐츠 타입을 등록하자는 제안이 오가고 있습니다.
Package(포장): Agent Plugins입니다. 디렉토리 하나, 고정된 위치, 클라이언트 간 이식 가능이라는 세 마디로 요약됩니다.
Run(실행): MCP와 Agent Skills입니다. 이미 이식성을 갖추고 있던 실행 계약입니다.

핵심은 각 층을 독립적으로 채택할 수 있다는 점입니다. 한 층을 도입한다고 해서 다음 층까지 반드시 써야 하는 의무가 생기지 않습니다. Agent Plugins만 채택해 포장 방식을 통일하고, 발견은 기존 방식을 그대로 써도 됩니다. 실제로 이 표준을 이미 지원하는 제품으로는 에이전트 구축·평가·배포·관측·게시를 위해 스킬을 묶어 제공하는 Google의 Agents CLI, 그리고 BigQuery·Spanner·Cloud SQL 등에 연결하는 플러그인 모음인 Data Agent Kit이 있습니다.

직접 만들어 보기: 1분 hello world

표준의 최소 표면적이 얼마나 작은지는 직접 만들어 보면 바로 느낄 수 있습니다. 디렉토리를 만들고, 두 줄짜리 매니페스트를 넣고, 스킬 하나를 추가하면 끝입니다.

# 1. 플러그인 디렉토리와 스킬 폴더 생성
mkdir -p hello-plugin/skills/greet

# 2. 최소 매니페스트 작성 (name만 있어도 유효)
cat > hello-plugin/plugin.json <<'JSON'
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "hello-plugin"
}
JSON

# 3. 스킬 본문 작성 (Agent Skills 스펙을 따름)
cat > hello-plugin/skills/greet/SKILL.md <<'MD'
---
name: greet
description: 사용자에게 이름을 넣어 인사말을 만들어 돌려줍니다.
---

사용자가 인사를 요청하면, 제공된 이름을 넣어
"안녕하세요, {name}님. 오늘도 좋은 하루 보내세요." 형태로 응답합니다.
MD

완성된 트리는 다음과 같습니다.

hello-plugin/
├── plugin.json
└── skills/
    └── greet/
        └── SKILL.md

이 구조가 낯설지 않다면 이유가 있습니다. 지금 이 블로그의 한국어 문장 교정에 쓰는 fluent-korean 스킬도 이와 비슷한 발상으로 배치되어 있습니다. 스킬 본문인 SKILL.md, 실제 지침을 담은 references/, 클라이언트에 얹는 확장인 output-styles/가 한 디렉토리에 모여 있습니다. 매니페스트와 컴포넌트를 한 폴더에 담아 옮긴다는 생각은 이미 여러 도구가 각자의 방식으로 실천하고 있었고, Agent Plugins는 그 배치에서 파일 이름과 위치를 표준으로 고정했습니다. 새로운 구조를 발명한 것이 아니라 흩어져 있던 관행에 공통 규격을 부여한 셈이라, 채택 비용이 낮습니다.

SA 관점 정리: MCP는 연결 규약, Agent Plugins는 배포 규약

정리하면 두 표준은 겨루는 관계가 아니라 역할이 다릅니다. MCP는 실행 중인 에이전트가 도구·데이터 소스와 어떻게 대화할지를 정하는 연결 규약입니다. Agent Plugins는 그 도구와 스킬을 어떻게 한 상자에 담아 여러 클라이언트로 옮길지를 정하는 배포 규약입니다. 하나는 런타임의 대화 방식이고, 다른 하나는 배포물의 포장 방식입니다.

둘 다 필요한 이유는 각자가 서로의 빈자리를 메우기 때문입니다. MCP만 있으면 서버를 어떻게 연결할지는 알아도, 그 서버 선언과 스킬 묶음을 클라이언트 사이에서 옮기는 표준 방법이 없습니다. Agent Plugins만 있으면 포장 방식은 표준이 되어도, 그 안의 서버가 실제로 어떻게 통신할지는 여전히 MCP가 정해야 합니다. 앞의 mcp.json 예시가 이 관계를 그대로 보여줍니다. 포장 표준이 위치와 스키마를 정하고, 그 안의 서버 항목은 MCP 규약을 따릅니다.

Amazon이 이 표준의 코어 메인테이너로 참여한 맥락도 여기서 읽힙니다. 클라우드 위에서 에이전트를 운영하는 입장에서는, 특정 벤더에 종속되지 않고 스킬과 도구를 이식할 수 있는 포장 표준이 생태계 전체의 마찰을 줄입니다. Cursor, Microsoft, OpenAI, Vercel, 그리고 뒤이어 합류한 Google까지, 평소 경쟁하는 회사들이 같은 위원회에 앉았다는 사실 자체가 이 단계에서는 표준화가 각자에게 이득이라는 판단을 공유했음을 시사합니다. 컴포넌트 규약(Agent Skills, MCP)이 먼저 자리를 잡았고, 이제 그것을 묶어 배포하는 방식에 대한 합의가 더해졌습니다. 배포 표류를 줄이려는 조직이라면, 실제 채택 여부와 무관하게 이 포맷의 최소 표면적을 지금 살펴볼 가치가 있습니다.

References

Agent Plugins Specification 1.0.0, agentplugins/agent-plugins-spec
FUTURE_CONSIDERATIONS, agentplugins/agent-plugins-spec
Agent Plugins: Package your skills, tools, and more, Google Developers Blog
Agent Skills
Model Context Protocol

문제는 컴포넌트가 아니라 상자였다#

Agent Plugins 1.0이 정의하는 것: 플러그인은 그냥 디렉토리다#

매니페스트 해부: 닫힌 스키마#

컴포넌트 발견: 위치가 고정되어 있고, 인라인 선언이 없다#

독립 실패: 서버 하나가 죽어도 스킬은 산다#

일부러 정의하지 않은 것: 절제된 스코프#

생태계 네 계층: 찾고, 기술하고, 포장하고, 실행한다#

직접 만들어 보기: 1분 hello world#

SA 관점 정리: MCP는 연결 규약, Agent Plugins는 배포 규약#

References#