새로 만든 것은 형식이 아니라 상자입니다

Agent Plugins는 새 스킬 문법도, 새 프로토콜도 아닙니다. 이미 있는 두 가지, 즉 Agent Skills 규격(SKILL.md)과 MCP 서버 설정을 한 폴더에 어떤 이름으로 어디에 놓을지만 정한 규칙입니다. 폴더 맨 위에 plugin.json 하나, 그 옆에 skills/ 폴더, 필요하면 mcp.json. 이게 전부입니다. plugin.json에 꼭 써야 하는 항목도 $schema와 name 두 개뿐입니다. 공식 문서는 이 표준을 "이식 가능한 부분에 대한 최소한의 상호운용 바닥"이라고 설명합니다. 배포, 설치, 권한, 업데이트, 화면은 일부러 규격 밖에 두었습니다. 다시 말해 상자의 모양만 통일했고, 상자를 어디서 사고 어떻게 여는지는 각 도구가 알아서 정합니다. 그래서 채택 문턱이 낮고, 한 달 만에 지원 도구가 아홉 개까지 늘었습니다.

Claude Code 플러그인과 다른 자리는 딱 두 군데입니다

Claude Code 공식 문서의 플러그인 구조를 옆에 놓고 보면 닮은꼴입니다. 둘 다 skills/ 폴더 아래에 스킬 이름 폴더, 그 안에 SKILL.md를 두고, 서브폴더에 scripts/와 references/를 넣습니다. 스킬을 설명하는 앞머리(frontmatter)의 name·description도 같은 Agent Skills 규격을 따릅니다. 다른 자리는 두 군데입니다. 첫째, 설명서 파일의 위치. Claude Code는 .claude-plugin/plugin.json이라는 숨은 폴더 안에, Agent Plugins는 폴더 맨 위 plugin.json에 둡니다. 둘째, MCP 설정 파일의 이름. Claude Code는 .mcp.json(점으로 시작), Agent Plugins는 mcp.json입니다. 이 두 파일만 다르고 나머지 뼈대는 겹칩니다. 그래서 지금 ~/.claude/skills/ 아래에 쌓아 둔 스킬 폴더는 SKILL.md를 한 글자도 안 고치고 다른 도구의 상자에 옮겨 담을 수 있습니다. 옮겨지지 않는 것은 Claude Code 전용 부품인 commands/, agents/, hooks/ 쪽입니다. 이건 표준이 "각 도구가 자기 이름의 폴더(예: com.example.client/)에 넣어라"고 따로 자리를 비워 두었습니다.

지원 도구 아홉 개, 빠진 도구 하나

공식 호환 목록에는 9월 기준 아홉 개가 올라 있습니다. Cursor, VS Code, GitHub Copilot, ChatGPT·Codex, Kiro, Grok Bot, 그리고 오픈소스 개인 에이전트인 Hermes Agent·OpenClaw·NanoClaw입니다. 아홉 개 모두 Agent Skills를 읽고, MCP 서버는 stdio와 Streamable HTTP를 공통으로 지원합니다(구형 SSE 방식은 도구마다 다릅니다). 목록에 없는 도구가 Claude Code입니다. Agent Skills 규격 자체는 Anthropic이 먼저 만들어 공개한 것인데, 그 스킬을 담는 상자 표준에는 초기 운영위원회 다섯 회사 명단에 Anthropic이 없습니다. 현재 Claude Code는 자기 형식(.claude-plugin/plugin.json)만 읽습니다. 그래서 같은 스킬을 Claude Code와 Cursor 양쪽에 배포하려면 설명서 파일을 두 벌 유지해야 합니다. 스킬 본체는 하나, 포장지만 둘인 셈이라 부담은 크지 않지만, 자동으로 되는 일은 아닙니다. 참고로 누끼토끼는 Claude Code와 Hermes Agent를 같이 쓰고 있어서, 이 두 벌 포장이 실제로 필요한 상황입니다.

하나가 깨져도 전체가 안 죽는 규칙

이 표준에서 실무자가 눈여겨볼 조항은 실패 처리입니다. 오류를 치명적인 것과 아닌 것으로 나눕니다. plugin.json이 깨졌거나 name이 없거나, 파일 경로가 폴더 밖으로 빠져나가면 치명적이라 플러그인 전체를 거부합니다. 반면 mcp.json 안의 서버 항목 하나가 잘못됐거나 지원 안 하는 통신 방식이면, 그 항목만 건너뛰고 나머지(예: 같이 들어 있던 스킬)는 정상 동작합니다. 무인 자동화에서 MCP 서버 설정 하나 때문에 스킬까지 통째로 안 먹는 경험을 해 보셨다면, 이 규칙의 값어치가 보이실 겁니다. 또 하나, 파일 경로는 반드시 ./로 시작하는 상대 경로여야 하고 심볼릭 링크로 폴더 밖을 가리키는 것도 금지입니다. 스킬 안에서 scripts/ 밖의 절대 경로를 부르고 있었다면, 옮기기 전에 이 부분부터 손봐야 합니다.

지금 뭘 하고, 뭘 안 해도 되는가

지금 당장 모든 스킬을 Agent Plugins로 다시 포장할 필요는 없습니다. Claude Code 한 도구만 쓰고 있다면 바뀌는 것이 없습니다. 반대로 스킬을 남에게 배포하거나, 두 개 이상의 에이전트를 같이 쓴다면 세 가지만 미리 맞춰 두면 됩니다. 첫째, 스킬은 항상 skills/이름/SKILL.md 구조로, frontmatter에 name과 description을 빠뜨리지 않습니다. 둘째, 스킬 안의 파일 참조는 ./scripts/… 같은 상대 경로로만 씁니다. 셋째, Claude Code 전용 부품(훅·서브에이전트·슬래시 명령)과 순수 스킬을 폴더 단위로 분리해 둡니다. 이렇게 해 두면 나중에 plugin.json 한 장만 얹어 다른 도구로 옮길 수 있고, Claude Code가 표준을 받아들이는 날이 와도 다시 손댈 것이 거의 없습니다. 아직 없는 것도 알아 두셔야 합니다. 이 표준에는 플러그인 장터(레지스트리), 샌드박스, 권한, 서명 검증, 자동 업데이트가 없습니다. 어디서 받은 스킬인지 검증하는 책임은 여전히 쓰는 사람 몫입니다.

Agent Plugins는 스킬과 MCP를 담는 상자의 모양을 통일한 표준입니다. 스킬 본체는 Claude Code에서 쓰던 그대로 옮겨지고, 다른 것은 설명서 파일 위치와 MCP 설정 파일 이름 두 가지뿐입니다. Claude Code가 아직 이 상자를 읽지 않기 때문에 두 도구 이상을 쓰는 사람은 포장지를 두 벌 유지해야 하고, 그 대신 스킬 폴더 구조와 상대 경로 규칙만 지켜 두면 옮기는 비용은 파일 한 장 수준으로 줄어듭니다.

누끼토끼가 운영하는 Claude Code 강의에서는 실무 스킬을 처음부터 skills/ 폴더 구조로 만들고, 도구 전용 부품과 분리해 두는 방식을 다룹니다. 어떤 에이전트로 갈아타도 스킬 자산이 남는 구조가 목표입니다.