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

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

내 서브에이전트를 플러그인에 태우기

스킬은 언제 알아서 나오고 언제 안 나올까 — 호출 방식의 원리까지.

혹시 .claude/agents/ 폴더에 코드 리뷰어나 테스트 담당 에이전트를 만들어둔 게 있어? 있다면 오늘 편이 제일 실용적일 거야. 그거 그대로 플러그인에 넣어서 어디서든 쓸 수 있게 만들 거거든.

에이전트 넣기는 허무할 정도로 쉬워

agents/ 폴더에 .md 파일 넣으면 끝이야. 정말 그게 다야.

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── agents/
    └── code-reviewer.md

파일 내용도 .claude/agents/에 쓰던 거랑 똑같아. 프론트매터에 설정 적고, 아래에 성격 써주면 돼.

my-plugin/agents/code-reviewer.md

---
name: code-reviewer
description: 코드 리뷰 전담. 커밋 전이나 PR 올리기 전에 쓴다.
tools: Read, Grep, Glob
---

너는 우리 팀 전담 코드 리뷰어야.

리뷰할 때 이 순서로 봐줘:
1. SQL 인젝션 — 특히 문자열 연결로 쿼리 만드는 부분
2. 트랜잭션 처리 누락
3. 널 체크 빠진 곳
4. 네이밍이 팀 컨벤션에 맞는지

지적할 땐 어디를 어떻게 고쳐야 하는지까지 같이 알려줘.

💡 tools로 권한 잠그기 — 위 예시는 Read, Grep, Glob만 줬어. 읽기만 되고 파일 수정은 못 해. 리뷰어한테 수정 권한까지 줄 이유는 없잖아. 배포할 플러그인이면 이 습관이 더 중요해져.

확인은 이렇게

플러그인 로드한 다음에 에이전트가 제대로 들어왔는지 보는 방법은 두 가지야.

• /context 실행 → Custom Agents 항목에 뜨는지 확인
• @ 멘션으로 이름 불러보기

⚠️ 이름이 겹치면 프로젝트 쪽이 이겨
프로젝트나 유저의 .claude/agents/에 같은 이름의 에이전트가 있으면 그쪽이 플러그인 에이전트를 덮어써. 플러그인 버전을 쓰려면 원본을 지워야 해. 7편(마이그레이션)에서 이 얘기 또 나올 거야.

스킬은 왜 어떤 건 알아서 나오고 어떤 건 안 나올까

여기가 오늘의 핵심이야. 스킬은 기본적으로 모델이 알아서 꺼내 쓰는 방식이거든. 클로드가 지금 상황을 보고 "아 이거 써야겠다" 하고 판단해.

그럼 뭘 보고 판단하냐? 오로지 description이야. 본문은 안 봐. 그래서 description을 어떻게 쓰냐에 따라 스킬이 잘 불려나오기도 하고, 만들어놓고 평생 안 쓰이기도 해.

✕ 안 불려나오는 설명

• "코드 리뷰"
• "유용한 도구"
• "이 스킬은 코드를 봅니다"
• → 언제 써야 할지가 없음

○ 잘 불려나오는 설명

• "코드를 모범 사례 관점에서 리뷰한다. 코드 리뷰할 때, PR 확인할 때, 코드 품질 분석할 때 사용."
• → 무엇을 + 언제가 둘 다 있음

공식 문서 예시도 딱 이 형태야. "무엇을 한다" 뒤에 "이럴 때 쓴다"를 붙이는 거지.

my-plugin/skills/code-review/SKILL.md

---
description: 코드를 모범 사례와 잠재적 문제 관점에서 리뷰한다.
  코드 리뷰할 때, PR 확인할 때, 코드 품질을 분석할 때 사용.
---

코드를 리뷰할 때는 다음을 확인해:
1. 코드 구조와 조직
2. 에러 처리
3. 보안 문제
4. 테스트 커버리지

스킬 설계의 전부

description은 클로드한테 보내는 호출 신호야.
"무엇을 하는지" + "언제 쓰는지" 둘 다 넣자.

반대로, 알아서 나오면 곤란한 스킬도 있어

배포 스크립트나 파괴적인 작업처럼 내가 명시적으로 부를 때만 나와야 하는 스킬이 있잖아. 이럴 땐 이 한 줄을 넣어.

---
description: 프로덕션 배포를 실행한다
disable-model-invocation: true
---

이러면 클로드가 알아서 꺼내 쓰지 않고, /my-plugin:deploy처럼 직접 불러야만 동작해. 3편에서 인사 스킬에 걸어뒀던 그 옵션이 이거야.

호출 방식	어떻게	이럴 때
모델이 알아서	기본값. description 보고 판단	리뷰, 문서화, 분석처럼 상황 맞으면 도와주면 좋은 것
내가 직접	disable-model-invocation: true + 슬래시 호출	배포, 삭제, 외부 API 호출처럼 내가 통제해야 하는 것

에이전트 vs 스킬 — 뭘 언제 쓰지?

둘 다 "클로드한테 일 시키는 법"이라 헷갈리기 쉬워. 이렇게 구분하면 편해.

스킬을 쓸 때

• "이럴 땐 이렇게 해" 같은 지침
• 메인 대화 안에서 처리해도 되는 일
• 결과를 바로 이어서 쓸 때

에이전트를 쓸 때

• 독립된 작업 공간이 필요할 때
• 탐색이 길어서 대화창을 어지럽힐 때
• 도구 권한을 따로 잠가야 할 때

실무 감각으로는 이래. 코드 수백 줄 뒤져야 하는 일은 에이전트. 결과만 요약해서 가져오니까 메인 대화가 깨끗하게 유지돼. 반면 "커밋 메시지는 이 형식으로 써" 같은 건 스킬이 맞아.

같이 넣으면 이런 모양이 돼

my-review-plugin/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   ├── code-reviewer.md      # 깊게 파는 리뷰어
│   └── security-auditor.md   # 보안 전담
└── skills/
    ├── commit-message/
    │   └── SKILL.md          # 커밋 메시지 형식
    └── pr-description/
        └── SKILL.md          # PR 본문 템플릿

✓ 이게 진짜 쓸모 있는 이유 — 팀원이 이 플러그인 하나만 깔면 우리 팀 코드 리뷰 기준이 통째로 전파돼. 컨벤션 문서를 위키에 올려두고 아무도 안 읽는 것보다 훨씬 확실하지.

⚠️ 수정했는데 반영이 안 된다면 — 스킬이나 에이전트 파일을 고친 뒤엔 /reload-plugins를 꼭 실행해야 해. 이 명령어 하나로 플러그인, 스킬, 에이전트, 훅, MCP 서버, LSP 서버가 전부 다시 로드돼.

다음 편 예고 → 6편에서는 훅이랑 MCP를 붙일 거야. 파일 저장할 때마다 자동으로 린트를 돌리고, 플러그인 설치 한 번에 MCP 서버 연결까지 끝나게 만드는 편이야. 여기까지 하면 "설치하면 환경이 완성되는" 플러그인이 돼.