plugin.json 완전 해부 — Claude Code가 서브에이전트를 패키지로 인식하는 방법

에이전트 정의 마크다운 파일 하나만 있으면 서브에이전트로 동작하는데, 왜 plugin.json이 필요한가? 그 답은 하나다. plugin.json이 있어야 Claude Code가 그 디렉토리를 "설치 가능한 패키지"로 인식한다. 이 파일이 없으면 디렉토리는 그냥 폴더일 뿐이고, /plugin install로 설치하거나 팀원과 공유하는 것이 불가능해진다.

plugin.json이 하는 단 하나의 일

파일 수백 바이트가 에이전트의 지위를 바꾼다. plugin.json이 있는 순간 디렉토리는 설치·배포·버전 관리가 가능한 패키지로 격상된다. 에이전트 자체의 능력은 변하지 않는다 — 단지 그 에이전트를 배포하는 방법이 생기는 것이다.

플러그인 디렉토리는 어디에 둬도 된다 — 단 내부 구조는 고정

먼저 한 가지 오해를 풀고 가자. my-plugin/ 디렉토리 자체는 아무 위치에 둬도 된다. ~/.claude/ 하위에 넣어야 하는 게 아니다. 개발 중에는 그냥 작업하기 편한 곳(예: ~/projects/my-plugin/, ~/src/my-plugin/, 또는 어느 git 레포 안)에 두면 된다.

Claude Code가 그 디렉토리를 인식하는 시점은 둘 중 하나다.

• 로컬 설치: /plugin install /절대/경로/my-plugin 으로 직접 경로를 알려준다.
• 마켓플레이스: marketplace.json에 등록된 출처에서 발견되면 자동으로 인지한다.

설치가 일어나면 Claude Code가 디렉토리 전체를 ~/.claude/plugins/cache/<출처>/<이름>/<버전>/로 복사한다. "플러그인 디렉토리를 어디 둬야 하지?"라는 고민은 사실 없는 셈이다. 개발은 어디서든 하고, 활성화는 install 명령이 처리한다.

플러그인 내부 구조 — .claude-plugin/ 하위에 plugin.json

위치는 자유롭지만 플러그인 디렉토리 안의 구조는 고정이다. my-plugin/이 어디 있든, 그 안에는 정확히 .claude-plugin/plugin.json 경로로 메타데이터 파일이 있어야 한다.

▲ ✅ 올바른 위치 — .claude-plugin/ 안에 plugin.json

▲ ❌ 잘못된 위치 1 — 루트에 직접 두면 인식 안 됨

▲ ❌ 잘못된 위치 2 — 디렉토리 이름이 다르면 인식 안 됨

디렉토리 이름이 정확히 .claude-plugin이어야 하고, 그 안에 plugin.json이 있어야 한다. 점(.)이 앞에 붙는다는 것, 하이픈이 있다는 것을 주의한다.

plugin.json의 4개 필드

실제 debug-pack의 plugin.json

{
  "name": "debug-pack",
  "version": "0.1.0",
  "description": "Python debugging subagent + error pattern skill + reasoning/fetch MCP for DGX Spark projects",
  "author": {
    "name": "<your-handle>"
  }
}

version 필드 — 캐시 경로에 박힌다

캐시 경로는 ~/.claude/plugins/cache/출처/이름/버전/ 구조다. version이 다르면 다른 경로에 저장된다. 덕분에 v1.0.0과 v1.1.0이 동시에 캐시에 공존할 수 있고, 버전 롤백도 가능하다.

설치 후 생기는 일 — plugin.json이 트리거하는 전체 흐름

plugin.json이 발견되면 패키지 내 모든 자산이 자동으로 로드된다. agents/, skills/, commands/, .mcp.json을 직접 등록할 필요 없이 플러그인 디렉토리만 가리키면 Claude Code가 모두 처리한다.

없어도 되는 상황 vs 반드시 필요한 상황

단일 프로젝트 팀에서 도메인 특화 에이전트를 쓴다면 plugin.json은 필요 없다. .claude/agents/에 파일을 두고 git으로 공유하면 충분하다. 여러 프로젝트나 팀에 배포하거나 MCP 서버를 포함할 때 비로소 plugin.json이 필요해진다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.