Agent Plugins Specification v1.0.0은 에이전트 확장을 배포 가능한 플러그인으로 포장하기 위한 최소·벤더 중립 규격이다. 현재 규격이 직접 정의하는 구성 요소는
skills/아래의 Agent Skill과 루트mcp.json으로 선언하는 MCP 서버이며, 플러그인 클라이언트의 설치·노출·실행 UX는 의도적으로 표준 바깥에 둔다.
한눈에 보기
- 무엇인가: 재사용 가능한 에이전트 확장을
plugin.json중심의 디렉터리 패키지로 묶는 커뮤니티 표준. - 현재 버전: 저장소의
main이 가리키는 2026-08-06 고정 커밋에서spec/1.0.0.md,schemas/1.0.0/*.schema.json이 함께 제공된다. - 핵심 구성: 플러그인 매니페스트
plugin.json, 즉시 하위 디렉터리의skills/<name>/SKILL.md, 루트mcp.json. - 실행 경계: 클라이언트는 플러그인 루트 밖의 파일을 읽지 않아야 하며, 명령어·경로·환경변수 확장은 제한된 규칙을 따른다.
- 의도적인 비범위: 설치 UI, 레지스트리, 서명·신뢰 모델, 샌드박스·권한, 비밀 저장, 스킬을 모델에 노출하는 방식은 v1.0.0이 정의하지 않는다.
- 에이전트 관점: 스킬은 지시문/워크플로 확장이고 MCP는 도구·데이터 연결 표면이다. 두 표면을 하나의 이동 가능한 배포 단위로 묶는 것이 이 규격의 중심 아이디어다.
공식 확인 — 규격의 구조
플러그인 패키지와 매니페스트
플러그인은 하나의 디렉터리 안에 모든 파일을 담는 배포 단위다. 루트에는 반드시 plugin.json이 있어야 하고, 매니페스트에는 schema와 name이 필수다. description, version, author, homepage, repository, license, keywords, icon, category, engines, capabilities, permissions 등은 선택적 메타데이터로 정의된다.
name은 소문자 영숫자로 시작해야 하며 소문자 영숫자·하이픈만 사용할 수 있고, 하이픈으로 끝날 수 없다. 길이는 2~64자다. 플러그인 경로는 패키지 루트 안에 있어야 하며 ..을 통한 탈출과 루트 밖 심볼릭 링크는 허용되지 않는다. 매니페스트에서 표준이 모르는 최상위 필드는 보고 후 무시할 수 있지만, 필수 필드 누락이나 형식 위반은 플러그인 전체를 무효화할 수 있는 오류로 분류된다.
JSON Schema의 현재 기본 shape은 다음과 같다.
| 표면 | 규칙 |
|---|---|
plugin.json | schema, name 필수; 현재 스키마 URL은 https://agent-plugins.org/spec/1.0.0/schema.json |
version | Semantic Versioning 형식 권장/검증 |
author | 문자열 또는 name·email·url을 가진 객체 |
engines | 클라이언트별 요구 버전 조건을 담는 자유 키 객체 |
capabilities·permissions | 클라이언트가 이해할 수 있는 확장 메타데이터 표면 |
| 알 수 없는 속성 | 스키마의 additionalProperties: false에 따라 매니페스트에서는 허용되지 않음; 본문 규격은 클라이언트의 오류 보고·무시 정책도 설명 |
Skills 발견 규칙
skills/가 있으면 그 즉시 하위 디렉터리를 스킬로 스캔한다. 각 스킬 디렉터리에는 SKILL.md가 필요하며, 이 파일은 Agent Skills specification의 형식을 따른다. 중첩된 스킬 디렉터리는 발견 대상이 아니다. 스킬 이름은 디렉터리 이름에서 가져오며 플러그인 매니페스트에 별도 목록을 두지 않는다.
이 표준은 스킬의 내용을 특정 에이전트·모델에 어떻게 노출할지는 정하지 않는다. 클라이언트가 스킬을 설치 후 자동 활성화할지, 선택 가능한 프롬프트·도구·메뉴로 제공할지, 사용자의 승인을 요구할지는 클라이언트의 책임이다. 따라서 저장소만으로 “모든 에이전트가 자동으로 이 스킬을 실행한다”고 결론 내릴 수 없다.
MCP 서버 발견 규칙
플러그인 루트에 mcp.json이 있으면 mcpServers 객체의 각 항목을 MCP 서버 구성으로 읽는다. 서버 이름은 키이며, 각 서버는 command 또는 url을 통해 stdio·Streamable HTTP·SSE 중 하나의 명시적 전송 방식을 사용한다. mcp.json 스키마는 표준 MCP 설정의 최소 공통 표면을 기술하고, args, env, cwd, headers, timeout 같은 실행 옵션을 둔다.
| 전송 | 핵심 필드 | 확인된 제약 |
|---|---|---|
| stdio | command, 선택적 args·env·cwd | command는 단일 실행 파일 토큰이어야 하며 셸 문법은 허용하지 않음 |
| Streamable HTTP | url, 선택적 headers·timeout | 원격 URL은 HTTPS를 사용해야 함 |
| SSE | url, 선택적 headers·timeout | 원격 URL은 HTTPS를 사용해야 함 |
각 서버 설정의 type은 허용된 전송 종류를 명시한다. 잘못된 서버 하나가 발견되면 해당 서버를 건너뛸 수 있지만, MCP 설정을 포함한 플러그인 전체가 반드시 실패해야 하는 것은 아니다. 헤더에 자격 증명을 직접 넣지 말라는 보안 지침은 있지만, 비밀 저장·OAuth·토큰 치환을 위한 표준 메커니즘은 아직 없다.
확장 디렉터리
표준이 정의하지 않는 기능은 역도메인(reverse-domain) 이름 공간의 extensions/ 아래에 둘 수 있다. 예를 들어 extensions/com.example.feature/처럼 구성하며, 다른 최상위 디렉터리나 파일도 클라이언트별 확장으로 사용할 수 있다. 다만 확장의 의미·실행 방식·호환성은 확장을 정의한 클라이언트나 생태계가 책임진다.
공식 확인 — 실행과 환경
경로·명령어 안전성
표준은 플러그인 루트와 데이터 저장소를 구분한다.
PLUGIN_ROOT: 설치된 플러그인 파일이 있는 읽기 전용 루트.PLUGIN_DATA: 플러그인별 영속 데이터를 저장하는 디렉터리.PLUGIN_ROOT는 플러그인 업데이트로 교체될 수 있으므로 사용자 데이터 저장에 사용하지 않는다.PLUGIN_DATA는 업데이트 사이에도 유지되며 설정·캐시·상태 저장에 사용한다.- 경로는 플러그인 루트 안으로 제한되고 심볼릭 링크로 이 경계를 우회할 수 없다.
환경변수 치환은 MCP의 args, env, cwd 같은 문자열 필드에서만 허용된다. $VAR, ${VAR}, ${VAR:-default} 형식을 사용하며, 매니페스트·서버 이름·키 같은 식별자에서는 치환하지 않는다. stdio command는 셸을 거치지 않는 단일 실행 파일이어야 하므로 node server.js, python -m server, 파이프·리다이렉션·&& 같은 셸 명령을 하나의 command 값으로 넣는 방식은 규격과 맞지 않는다.
버전과 클라이언트 적합성
규격 버전은 매니페스트의 schema URL, 정식 문서 경로, JSON Schema 경로에 함께 반영된다. 플러그인 자체의 version은 SemVer를 사용하도록 권장된다. 클라이언트는 지원하는 규격 버전을 명시하고, 플러그인이 요구하는 클라이언트 버전·기능을 engines 등으로 확인할 수 있다. 현재 문서는 클라이언트가 규격을 어느 정도 지원하는지 full, partial, unsupported 같은 적합성 수준으로 설명할 수 있도록 하지만, 자동화된 인증·호환성 배지·공식 conformance test 실행 결과까지 제공하지는 않는다.
공식 확인 — 거버넌스와 라이선스
GOVERNANCE.md는 Agent Plugins를 특정 회사가 독점하지 않는 커뮤니티 주도 기술 규격으로 설명한다. 기술 헌장과 규격 변경 절차, maintainer·contributor의 역할, RFC와 이슈를 통한 제안·검토 흐름을 정의하며, 한 업체가 핵심 의사결정에서 영구적인 단독 지배력을 갖지 않도록 하는 원칙을 둔다. MAINTAINERS.md에는 현재 관리 주체와 역할이 기록되어 있다.
LICENSE.md는 문서·규격 텍스트를 CC-BY-4.0, 스키마·스크립트 등 소프트웨어 성격의 산출물을 Apache-2.0으로 구분한다. 반면 GitHub REST API의 저장소 license 필드는 이 시점에 Other/NOASSERTION을 반환했다. 따라서 실제 재사용 시에는 저장소의 라이선스 문서와 대상 파일의 라이선스 범위를 직접 확인해야 한다.
미래 고려사항과 현재의 빈틈
FUTURE_CONSIDERATIONS.md가 열어 둔 후속 주제는 다음과 같다.
- 플러그인 출처(provenance), 서명, 무결성 검증
- 신뢰 모델과 샌드박싱
- 권한 선언 및 사용자 승인
- 비밀·자격 증명 관리
- 엔터프라이즈 정책·감사 로그·조직 통제
- 의존성·버전 해결
- 테스트·검증·호환성 도구
- 레지스트리와 배포 채널
- 플러그인 업데이트·롤백·폐기
이 목록은 v1.0.0의 기능 약속이 아니라 향후 논의를 위한 범위다. 현재 표준만으로는 악성 플러그인의 실행을 안전하게 격리하거나 MCP credential을 공통 방식으로 주입하거나, 설치한 플러그인의 신뢰도를 검증할 수 없다. 실제 클라이언트는 자체 보안 정책과 승인 UX를 추가해야 한다.
사용자 관점의 해석
“에이전트 플러그인”을 배포 단위로 만드는 최소 계약
이 저장소의 핵심 기여는 새로운 실행 엔진을 만드는 것이 아니라, 서로 다른 에이전트 클라이언트가 공통으로 이해할 수 있는 파일 레이아웃·발견 규칙·환경 계약을 제안하는 데 있다. SKILL.md는 모델에게 주는 절차적 지식, mcp.json은 외부 도구·데이터 서버 연결을 담당하므로 둘을 한 플러그인 디렉터리에서 함께 배포할 수 있다.
이 구조는 다음과 같은 흐름을 가능하게 한다.
plugin package
├── plugin.json # 정체성·메타데이터·호환성
├── skills/<name>/SKILL.md # 작업 절차·도메인 지식
├── mcp.json # 도구·데이터 서버 연결
└── extensions/<reverse-domain> # 클라이언트별 확장Hermes와의 관련성
Hermes처럼 스킬·MCP·도구 라우팅을 모두 갖춘 에이전트 하네스에는 이 규격이 배포·이식성의 공통 어휘가 될 수 있다. 다만 이 저장소가 Hermes의 지원이나 자동 호환을 선언하는 것은 아니다. 실제 통합에는 최소한 다음이 추가로 필요하다.
plugin.json검증과 플러그인 루트 경계 검사SKILL.md검색·설치·활성화 정책mcp.json을 Hermes MCP 설정으로 변환하는 어댑터PLUGIN_ROOT/PLUGIN_DATA수명주기 및 업데이트 정책- 신뢰·승인·비밀·샌드박스에 대한 Hermes 고유 정책
- 규격 버전별 conformance 테스트와 실패 격리
즉, Agent Plugins Specification은 실행 하네스 자체보다 확장 패키징 인터페이스에 가깝다. 이 구분을 유지해야 “포맷 표준”과 “안전한 플러그인 런타임”을 혼동하지 않을 수 있다.
확인 범위와 미검증 주장
공식 소스에서 직접 확인한 것
agentplugins/agent-plugins-spec저장소와main의 고정 커밋- Agent Plugins Specification v1.0.0 문서와 plugin/MCP JSON Schema
plugin.json,skills/,mcp.json,extensions/의 패키징·발견 규칙PLUGIN_ROOT,PLUGIN_DATA, 경로 경계와 환경변수 확장 규칙- 거버넌스·기여·라이선스 문서와 향후 고려사항
이 노트의 해석
- Skills와 MCP를 한 배포 단위로 묶는 구조는 에이전트 확장 이식성을 높일 수 있다.
- 규격의 현재 범위는 실행 보안보다 상호운용 가능한 패키징 계약에 집중한다.
- Hermes와 같은 하네스는 이 포맷을 수용할 수 있지만, 검증·승인·sandbox·secret management는 별도의 런타임 설계다.
확인하지 않은 것
- 실제 클라이언트에서의 플러그인 설치·검색·실행
- Agent Plugins Registry의 운영 상태나 실제 배포 성공 여부
- 특정 에이전트가 v1.0.0 conformance를 통과했다는 주장
- MCP 서버의 연결·인증·tool call 실행
SKILL.md가 특정 모델에 자동 활성화되는지 여부- 플러그인 서명·sandbox·권한·secret injection이 이미 구현되었다는 주장
출처와 고정 캡처
- 원문 provenance: raw source:
github-agentplugins-agent-plugins-spec - GitHub 저장소: https://github.com/agentplugins/agent-plugins-spec
- 고정 커밋:
bd383552095128f6effe895b9257cfd580a6d179 - README byte SHA-256:
e4e5178edaaf62e57e930684e3cd0ecd654e9f83994b40233d2e2d5ab2d13929 - 캡처 기준일: 2026-08-08 09:42 KST