Agent Plugins 1.0.0이란 무엇인가. plugin.json, MCP, Agent Skills, JSON 구성

읽기 전 요약

파일	명세가 요구하는 것	하지 않는 것
plugin.json	루트의 유일한 매니페스트. $schema와 name이 필수. 필드 목록은 닫혀 있다	MCP를 안에 넣거나 구성 요소 경로를 옮길 수 없다
skills/	바로 아래 자식의 SKILL.md만. 형식은 Agent Skills 명세	재귀하지 않는다. 디렉터리가 없어도 오류가 아니다
mcp.json	최상위는 $schema와 mcpServers뿐. 서버마다 type이 필요하다	도구를 실행하지 않는다. 1.0.0에 이식 가능한 자격 증명 필드는 없다
확장 디렉터리	com.example.client/ 같은 역도메인. extensions도 네임스페이스	다른 클라이언트는 무시할 수 있어야 한다

사실은 Agent Plugins 1.0.0 명세, Vercel 공개 노트, 같은 날 Google Developers Blog. 모두 2026-08-06. 주문 A-1042와 orders.example.com은 허구.

스킬과 MCP 서버를 옮길 수 있는 디렉터리 하나에 담는다

Agent Plugins 1.0.0은 2026년 8월 6일에 공개됐다. 당시 핵심 유지관리자는 Amazon, Cursor, Microsoft, OpenAI, Vercel이었다. 같은 날 Google Developers Blog는 Kevin Hou를 대표로 Google이 그 그룹에 합류하고, 자사 제품 지원을 시작한다고 적었다. 이것은 Google이 혼자 낸 사설 형식이 아니다. 명세가 정의하는 이식 가능 구성 요소는 둘, Agent Skills와 MCP 서버다. 설치, 배포, 정책, 화면은 각 클라이언트에 남는다. 클라이언트는 구성 요소를 찾기 전에 루트 plugin.json을 검증한다. 플러그인을 읽는 동안 Schema를 네트워크에서 가져오면 안 된다.

• 매니페스트: $schema는 https://agent-plugins.org/schemas/1.0.0/plugin.schema.json. name은 필수.
• 스킬: skills/<이름>/SKILL.md. 바로 아래만. 재귀하지 않는다.
• MCP: 루트 mcp.json. 각 항목은 stdio, streamable-http, 또는 선택적인 옛 sse.

MCP가 선에서 어떻게 불리는지는 Coding Agent가 MCP를 부르는 방법. MCP Tool Schema와 Function Calling의 차이는 MCP Tool Schema와 Function Calling. 이 글은 그 두 편을 다시 쓰지 않는다. 플러그인 디렉터리의 JSON 두 장이 무엇을 맡는지 적는다.

plugin.json 필드 목록은 닫혀 있다

허용되는 최상위는 $schema, name, version, description, author, homepage, repository, license, keywords, extensions뿐이다. 필수은 앞의 둘. 이름은 1자에서 64자, 소문자, 숫자, 하이픈, 점만. 처음과 끝은 영숫자. 연속된 --나 ..는 안 된다. version은 시맨틱 버전을 권하지만, SemVer가 아니라는 이유만으로 거부하지 않는다. author는 name, email, url만. 허구 주문 플러그인:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "orders-plugin",
  "version": "1.0.0",
  "description": "Look up fictional order A-1042. No refunds.",
  "license": "Apache-2.0",
  "keywords": ["orders"]
}

모르는 최상위 필드는 보고하고 무시한다. 나머지가 맞으면 읽기를 계속한다. 필수 누락, 잘못된 타입, 불법 이름은 패키지 전체를 거부한다. 구성 요소는 발견하지도 실행하지도 않는다. 클라이언트 전용 데이터는 extensions에 둔다. 키는 역도메인, 값은 객체. 다른 파일이 루트 매니페스트의 핵심 필드를 덮어쓸 수 없다.

스킬과 MCP는 매니페스트 안에 쓸 수 없다

명세는 위치를 고정한다. skills/의 바로 아래 자식 중 정확히 SKILL.md라는 일반 파일을 가진 것이 스킬 하나다. 머리말과 scripts/, references/, assets/는 Agent Skills 명세가 맡는다. 이 명세는 발견 방법만 정하고, 클라이언트가 모델에 어떻게 보여 주는지는 정하지 않는다. MCP는 plugin.json에 넣을 수 없고, 다른 경로로 옮길 수도 없다. mcp.json 최상위는 $schema와 mcpServers뿐. 빈 mcpServers는 합법이다. 두 $schema 버전은 같아야 한다. 1.0.0 MCP 식별자는 https://agent-plugins.org/schemas/1.0.0/mcp.schema.json. stdio는 type과 command가 필수. args, env, cwd는 선택. ./로 시작하는 경로는 플러그인 루트 상대. ../로 루트 밖으로 나가면 안 된다. 클라이언트는 PLUGIN_ROOT와 PLUGIN_DATA를 펼친다:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "orders": {
      "type": "stdio",
      "command": "./bin/orders",
      "args": ["--data", "${PLUGIN_DATA}/orders"],
      "cwd": "${PLUGIN_ROOT}"
    }
  }
}

원격은 streamable-http이고 url이 필수다. sse는 폐기 예정인 선택 전송이다. 실패 뒤의 대체는 정의하지 않는다. 준수 클라이언트는 stdio와 streamable-http 중 적어도 하나를 지원하고, 둘 다 지원하는 편이 낫다. 1.0.0에는 이식 가능한 OAuth나 자격 증명 참조가 없다. 인증은 클라이언트가 가진다. 경로 규칙은 패키지 안 파일에 한정되며, 자식 프로세스 샌드박스가 아니다. 도구 인자는 별도의 Schema 문이 필요하다. AI가 JSON Schema를 필요로 하는 이유.

망가진 부분은 자기 경계에서 멈춘다

명세는 실패를 나눈다. 나쁜 JSON 하나를 패키지 전체의 죽음으로 읽지 않는다:

클라이언트는 지원하지 않는 구성 요소 종류를 무시한다. com.example.client/ 같은 역도메인은 한 클라이언트의 확장이다. 다른 클라이언트는 못 본 척할 수 있어야 한다. extensions의 모르는 네임스페이스도 같다. 이미 보낸 tools/call을 샌드박스가 어떻게 막는지는 다른 층이다. OpenShell과 Sentry.

플러그인을 내기 전 여섯 확인

MCP 서버 URL을 plugin.json에 붙여 넣는 것부터 시작하지 않는다:

1. 먼저 루트 plugin.json을 쓴다. 닫힌 필드 목록의 키만. orders-plugin처럼 소문자 이름.
2. 스킬은 바로 아래 자식에 둔다. skills/lookup-order/SKILL.md. 더 깊은 디렉터리는 발견되지 않는다.
3. MCP는 mcp.json에만 쓴다. 항목마다 type. 로컬은 stdio와 ./bin/orders. ../는 쓰지 않는다.
4. 두 $schema를 같은 1.0.0으로 둔다. 어긋나면 스킬은 남을 수 있고 MCP는 남을 수 없다.
5. 자격 증명은 클라이언트에 남긴다. 1.0.0 mcp.json에는 이식 가능한 비밀 필드가 없다. 토큰을 env나 headers에 넣어 커밋하지 않는다.
6. 도구 인자는 별도 Schema. 매니페스트는 서버 위치만 알려 준다. A-1042는 호스트가 검증한 뒤 실행한다.

skills/도 mcp.json도 없는 플러그인이 합법일 수 있다. 필수 파일은 plugin.json뿐이다.

합치기 전에 JSON 두 장을 펼친다

읽기 실패는 패키지 거부이거나 MCP 서버 하나의 건너뜀이다. 프롬프트보다 먼저 나눈다.

• plugin.json과 mcp.json을 포맷하고, Schema 검증로 최상위에 여분 키가 있는지, $schema가 빠졌는지 본다.
• JSONPath 추출로 $.name, $.mcpServers.orders.type, $.mcpServers.orders.command를 뽑는다.
• 이전 판과 JSON Diff한다. 경로가 플러그인 루트 밖으로 나갔는지 먼저 본다.
• skills/lookup-order/SKILL.md가 바로 아래 자식의 일반 파일이고, 더 깊은 파일이 아닌지 확인한다.
• 설정의 토큰은 먼저 가리기. 비밀이 든 mcp.json을 공개 포매터에 붙이지 않는다. JSONSort는 브라우저 로컬에서 돈다.

두 JSON이 닫힌 필드 목록으로 다시 조립되고 디렉터리가 고정 위치에 있으면, 그 플러그인은 1.0.0에 올라 있다. 조회를 실행할지는 매니페스트가 정하지 않는다.

흔한 실수

• Google의 사설 플러그인 형식으로 쓴다. 2026-08-06 공개 글은 벤더를 넘는 명세다. Google은 그날 핵심 유지관리자로 합류했다.
• mcpServers를 plugin.json에 넣는다. 명세는 인라인과 경로 변경을 금지한다. 클라이언트가 읽는 것은 루트 mcp.json뿐이다.
• 객체 모양으로 전송을 짐작한다. 서버마다 type이 필요하다. URL처럼 보이면 HTTP라는 규칙은 없다.
• API 키를 mcp.json에 넣는다. 1.0.0에는 이식 가능한 자격 증명 필드가 없다. 인증은 클라이언트. 예는 허구 주문만.
• 서버 하나가 뜨지 않는다고 스킬을 모두 버린다. 하나 실패는 그 항목만 멈춘다. 최상위 mcp.json이 무효면 MCP가 멈춘다. 스킬은 계속 읽힌다.
• 이 글로 MCP와 Function Calling 비교를 다시 쓴다. 여기서는 기존 MCP 설정을 고정 파일에 어떻게 두는지 적는다.

FAQ

plugin.json만 있고 스킬과 MCP가 없어도 합법인가?

합법이다. 필수 파일은 plugin.json뿐이다. skills/나 mcp.json이 없어도 클라이언트는 있는 것을 읽고, 그것을 오류로 보지 않는다. 필수 누락이나 불법 이름일 때 패키지 전체를 거부한다.

두 $schema가 다르면 어떻게 되나?

MCP 구성이 무효가 된다. 스킬과 다른 구성 요소 종류는 유효하다. 1.0.0에서는 둘 다 명세의 1.0.0 식별자를 쓰고, 버전은 같아야 한다.

SKILL.md를 skills/orders/extra/에 둘 수 있나?

발견되지 않는다. 클라이언트는 skills/의 바로 아래만 보고 재귀하지 않는다. 발견되려면 skills/lookup-order/SKILL.md처럼 바로 아래의 일반 파일이어야 한다.

stdio와 streamable-http를 둘 다 적어야 하나?

아니다. 서버 하나는 type 하나. stdio는 command, streamable-http는 url. sse는 폐기 예정이고 클라이언트가 지원하지 않아도 된다. 연결이 실패하면 다른 전송으로 바꾸는 정의는 없다.

이 JSON이 스스로 주문을 조회하나?

하지 않는다. plugin.json은 플러그인 이름을 붙이고, mcp.json은 서버 위치를 클라이언트에 알린다. tools/call은 호스트가 실행한다. A-1042 같은 인자는 별도 Schema로 검증한다. 매니페스트에 이식 가능한 비밀 필드는 없다.

결론

Agent Plugins 1.0.0은 Agent Skills와 MCP 서버를 옮길 수 있는 루트 디렉터리 하나에 담는다. plugin.json이 고정하는 것은 명세 버전과 이름이다. 구성 요소 위치는 매니페스트에서 바꿀 수 없다.

orders-plugin이 plugin.json에, ./bin/orders가 mcp.json에, SKILL.md가 바로 아래 자식에 있는지 먼저 확인한다. 세 곳이 고정 위치에 있으면 클라이언트는 설정을 어디에 숨겼는지 짐작하지 않아도 된다.

이어서 읽기

• Coding Agent는 MCP를 어떻게 부르나 tools/call의 선 위 모양. 이 글은 다시 쓰지 않는다
• MCP Tool Schema와 Function Calling 프로토콜 비교이지, 플러그인 디렉터리가 아니다
• AI는 왜 JSON Schema가 필요한가 서버를 찾은 뒤에도 인자는 문을 통과한다
• OpenShell과 Sentry 이미 보낸 tools/call을 샌드박스가 어떻게 막나
• JSONSort 로컬 도구 포맷, 검증, Diff, Schema
• 모든 글 JSON과 AI 개발에 대한 다른 노트

변경 기록: 2026-10-12 처음 게시