클로드코드 플러그인 완전정복 · 4편

클로드코드 플러그인 완전정복 · 4편

"분명 만들었는데 안 뜨는데요" — 구조 완전정복

플러그인 만들다 막히는 이유 8할이 폴더 위치야. 한 번에 정리하고 가자.

3편에서 만든 인사 플러그인은 파일이 두 개뿐이라 헷갈릴 일이 없었어. 근데 에이전트 넣고 훅 넣고 MCP 붙이기 시작하면 얘기가 달라져. 어디에 뭘 둬야 하는지가 갑자기 중요해지거든.

그리고 여기서 거의 모두가 똑같은 실수를 해.

가장 흔한 실수 하나

⚠️ .claude-plugin/ 안에는 plugin.json만 들어간다
skills/, agents/, hooks/, commands/를 저 폴더 안에 넣으면 아무것도 로드 안 돼. 에러도 안 나. 그냥 조용히 없는 셈 쳐.

왜 헷갈리냐면, .claude-plugin이라는 이름이 "여기가 플러그인 폴더구나" 싶게 생겼거든. 근데 아니야. 저긴 설정 파일 하나만 두는 자리고, 나머지는 전부 그 위 레벨에 있어야 해.

✕ 이렇게 하면 안 돼

• my-plugin/
• └ .claude-plugin/
•    ├ plugin.json
•    └ skills/ ← 여기 아님!

○ 이게 맞아

• my-plugin/
• ├ .claude-plugin/
• │  └ plugin.json
• └ skills/ ← 루트에!

하나 더. 플러그인 루트는 ~/.claude/가 아니야. 플러그인 루트란 --plugin-dir로 넘긴 그 폴더, 또는 .claude-plugin/plugin.json이 들어있는 그 폴더를 말해. 그래서 ~/.claude/.mcp.json 같은 데 파일 둬봐야 클로드코드는 쳐다도 안 봐.

전체 구조 치트시트

플러그인 루트에 올 수 있는 것들 전부야. 물론 다 있을 필요는 없고, 필요한 것만 골라 쓰면 돼.

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # 매니페스트 (여긴 이것만!)
├── skills/              # 스킬 — 폴더별 SKILL.md
│   └── code-review/
│       └── SKILL.md
├── agents/              # 서브에이전트 정의
├── hooks/
│   └── hooks.json       # 이벤트 훅
├── monitors/
│   └── monitors.json    # 백그라운드 감시
├── output-styles/       # 응답 스타일
├── themes/              # 색 테마 (/theme에 뜸)
├── bin/                 # 실행 파일 (PATH에 자동 추가됨)
├── .mcp.json            # MCP 서버 설정
├── .lsp.json            # LSP 서버 설정
├── settings.json        # 플러그인 켜질 때 적용될 기본 설정
└── README.md            # 문서 (배포할 거면 필수)

폴더/파일	담는 것
.claude-plugin/	plugin.json 매니페스트. 컴포넌트가 기본 위치에 있으면 생략도 가능
skills/	<이름>/SKILL.md 형태의 스킬 폴더들
commands/	평평한 마크다운 파일 형태의 스킬. 레거시 형식이라 새로 만들 땐 skills/ 쓰자
agents/	서브에이전트 정의 파일들
hooks/	hooks.json에 이벤트 핸들러
.mcp.json	MCP 서버 설정
.lsp.json	LSP 서버 설정 (코드 지능)
monitors/	monitors.json에 백그라운드 모니터
output-styles/	클로드가 응답하는 스타일 정의
themes/	색 테마. 설치하면 /theme 목록에 나타나
bin/	플러그인 켜져 있는 동안 Bash 도구의 PATH에 추가되는 실행 파일
settings.json	플러그인 활성화 시 적용할 기본 설정

외울 건 딱 한 줄

.claude-plugin/ 안엔 plugin.json만.
나머지는 전부 플러그인 루트에.

스킬 하나짜리면 더 줄일 수 있어

스킬을 딱 하나만 넣을 거면 skills/ 폴더 안 만들고 루트에 SKILL.md를 바로 둬도 돼. 이때는 프론트매터의 name 필드가 호출 이름이 되고.

my-tiny-plugin/
├── .claude-plugin/
│   └── plugin.json
└── SKILL.md          # 이것만으로도 동작

💡 근데 추천은 — 나중에 스킬이 하나 더 늘어날 것 같으면 처음부터 skills/ 구조로 가는 게 편해. 옮기는 것도 일이거든.

settings.json — 플러그인이 클로드코드 성격을 바꿀 수 있어

이건 좀 재밌는 기능이야. 플러그인 루트에 settings.json을 두면 플러그인이 켜질 때 자동으로 적용되는 기본 설정을 넣을 수 있어. 지금은 agent랑 subagentStatusLine 키만 지원해.

my-plugin/settings.json

{
  "agent": "security-reviewer"
}

이렇게 하면 플러그인의 agents/에 정의된 security-reviewer 에이전트가 메인 스레드로 올라와. 그 에이전트의 시스템 프롬프트, 도구 제한, 모델 설정이 통째로 적용되는 거지. 즉 플러그인 하나 켜는 걸로 클로드코드 자체의 성격을 바꿔버릴 수 있어.

💡 우선순위 — settings.json의 값이 plugin.json 안에 적은 settings보다 우선해. 모르는 키는 조용히 무시되고.

안 될 때 순서대로 확인하기

• 구조부터 확인. 폴더가 .claude-plugin/ 안에 들어가 있진 않은지
• 하나씩 떼서 테스트. 스킬만, 에이전트만, 훅만 따로 확인해보기
• 검증 명령어 돌리기. claude plugin validate ./my-plugin — 매니페스트, 스킬/에이전트 프론트매터, hooks.json까지 다 봐줘
• Errors 탭 열기. /plugin → Errors에 이유가 적혀 있어

💡 뭐가 실제로 로드됐는지 한눈에 — claude plugin details <이름>을 치면 그 플러그인이 실제로 제공하는 컴포넌트 목록이랑 토큰 비용이 나와. "분명 만들었는데 안 뜬다" 싶을 때 여기 없으면 로드 자체가 안 된 거야.

⚠️ hooks.json이 깨지면 플러그인 전체가 안 떠
JSON 문법 하나 틀렸을 뿐인데 스킬도 에이전트도 다 안 뜨는 상황이 나와. 훅 건드린 뒤엔 claude plugin validate 한 번 돌리는 습관을 들이자.

여러 개 동시에 테스트하기

--plugin-dir는 여러 번 붙일 수 있어. 플러그인끼리 충돌 나는지 볼 때 유용해.

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

참고로 --plugin-dir로 띄운 플러그인이 이미 설치된 같은 이름의 플러그인보다 우선해. 그래서 설치된 걸 지우지 않고도 수정본을 테스트할 수 있어. 이거 은근 편해.

다음 편 예고 → 구조를 잡았으니 이제 진짜 쓸모 있는 걸 넣어볼 차례야. 5편에서는 예전에 만들어둔 서브에이전트를 플러그인에 태우는 방법을 다룰게. 이미 .claude/agents/에 뭔가 있다면 그거 그대로 재활용할 수 있어.