gptaku 플러그인 구조 파헤치기 — 며칠간의 학습 기록

소개

시도한 것: Claude Code의 gptaku 플러그인이 어떻게 만들어졌는지 며칠간 뜯어보고, 그 구조를 직접 학습 자료로 정리했습니다. 특히 3개 플러그인 — docs-guide, show-me-the-prd, kkirikkiri — 을 깊게 팠습니다.

이유: "플러그인"이라는 게 그냥 마법처럼 동작하는 줄 알았는데, 내부를 보니 commands · agents · skills · references 라는 부품들의 조합이더군요. 이 구조를 이해하면 나만의 AI 도구(플러그인/스킬)도 만들 수 있겠다 싶어서 시작했습니다.

진행 방법

사용 도구: Claude Code (플러그인 파일 직접 읽기 + 서브에이전트로 병렬 조사)

핵심은 "혼자 다 읽지 말고 Claude에게 조사를 시키고, 의심나면 직접 검증"이었습니다. 실제로 던진 프롬프트들:

1. 전체 플러그인 목록 및 기능, 설계 철학(commands/agents/skills 구성)을 정리하고,
   3개 플러그인의 command→skill→reference 흐름을 도식화해줘.

2. command가 SKILL.md를 명시적으로 호출하는 구조인지,
   단지 reference만 호출하는 구조인지 확인해서 알려줘.

3. kkirikkiri 플러그인 SKILL.md의 SendMessage에 대해 설명해줘.
   어디서 선언되어 있고 누가 사용하는지 알고 싶어.

4. docs-guide는 agent를 명시적으로 만들었는데, kkirikkiri는 인터뷰로
   동적으로 agent가 구성되는 것 같아. 맞는지 확인하고 둘을 비교해줘.

이렇게 알아낸 핵심 구조 (도식):

[플러그인 한 개의 부품]
plugin.json   → 명함 (이름·버전)
commands/     → 접수창구 (/명령어로 부르는 진입점)
agents/       → 파견 전문가 (독립적으로 일하는 일꾼)
skills/SKILL.md → 업무 매뉴얼 (실제 작업 순서)
  └ references/ → 부록 자료집 (필요할 때만 펼침)

여러 플러그인이 모인 "가게"가 마켓플레이스입니다. marketplace.json이 플러그인 목록을 들고 있고, 각 플러그인은 위 부품들을 골라 조합합니다. (모든 부품이 필수는 아님 — 예: agents/는 docs-guide·vibe-sunsang만 가짐)

이 부품들을 꿰는 3가지 설계 원칙도 알게 됐는데, 이게 플러그인 설계 철학의 핵심이었습니다:

① 진입점 ↔ 본체 분리   (command ↔ skill)
   - 얇은 진입점(command)과 두꺼운 본체(skill/매뉴얼)를 나눔
   - 덕분에 /명령어로도, 자연어로도 같은 기능을 부를 수 있다

② 지식 외부화          (skill ↔ references)
   - 무거운 지식은 references(부록)로 빼고 '필요할 때만' 읽음
   - 매뉴얼이 가벼워지고, 여러 일꾼이 같은 부록을 공유

③ 격리 실행            (agent)
   - 무거운 전담 작업은 별도 방(agent)에서 처리
   - → 메인 대화 컨텍스트가 안 더러워짐

이 세 원칙을 알고 나니, 플러그인마다 ①을 어떻게 연결하느냐가 다 달랐다는 게 보였습니다. 그게 다음 발견입니다.

가장 의외였던 발견 — "command가 skill을 부른다"는 공식이 없었다. 3개가 다 달랐고, 저는 이걸 3가지 패턴으로 정리했습니다.

[패턴 A] 위임형 — docs-guide
  command ──Task──► agent에게 넘김          (미리 만든 전문가가 처리)

[패턴 B] 자체 내장형 — show-me-the-prd
  command 안에 작업 순서가 통째로 들어있음    (진행자가 직접 처리, skill 안 부름)

[패턴 C] 로더형 — kkirikkiri
  command ──Read──► SKILL.md 읽어옴 ──► 매뉴얼대로
  팀원(subagent)을 즉석 생성·운영           (매뉴얼 로딩 + 동적 팀 운영)

한눈에 비교 (skill 사용 + reference 참조 함께 정리)

여기서 꼭 구분해야 할 두 가지 — "skill 사용"과 "reference 참조"는 별개입니다.

• skill 사용 = SKILL.md(작업 순서가 담긴 매뉴얼 본체)를 읽어와 그대로 따르는가

• reference 참조 = references/*.md(필요할 때 펼치는 부록 자료집)를 읽는가

이 둘은 따로 논다 → 매뉴얼은 안 봐도 부록은 볼 수 있다. (docs-guide·show-me-the-prd가 그 경우)

누가 reference(부록)를 펼치나?
  A 위임형     :  주로 agent가 펼침   (command은 폴백 때 1개)
  B 자체 내장형 :  command이 직접 펼침  (1개)
  C 로더형     :  command이 펼친 뒤 SKILL.md 워크플로우가 마저 활용

💡 중요한 사실: 세 플러그인 모두 Skill 도구를 쓰지 않는다. "skill을 부른다"가 아니라, Task(agent에게 위임)거나 Read(매뉴얼·부록 파일 읽기)일 뿐. 그래서 "command = skill 호출"이라는 단일 공식은 틀렸다. 그런데 공통점은 하나 있다 — 매뉴얼(SKILL.md)은 안 봐도, references/라는 부록 자료집은 셋 다 (직접이든 agent·skill을 거치든) 반드시 나눠 쓴다. 즉 진짜 공유 자산은 skill이 아니라 references였다.

특히 kkirikkiri(패턴 C)는 2단계로 동작합니다 — ① 매뉴얼(SKILL.md)을 읽어오고 → ② 그 매뉴얼대로 팀원을 그 자리에서 만들어 운영합니다:

/kkirikkiri "리서치 팀 만들어줘"
   │
   ├─① command가 SKILL.md + 참고파일 읽어옴            (매뉴얼 로딩)
   │
   └─② 매뉴얼(8단계)대로 실행
        ├ 인터뷰로 무엇이 필요한지 파악
        ├ archetype(7종) × 도메인 정보 = 팀원 카드 즉석 합성
        ├ Task로 팀원(subagent) 여러 명 생성
        └ 공유 메모리(md) + SendMessage로 협업·운영
                 ▲
        ※ 미리 만들어 둔 팀원이 없음 — 부탁받은 그 순간 만들어진다 (동적)

결과와 배운 점

배운 점 (핵심 3가지)

1. 부품 분리의 미학 — 무거운 지식은 references/로 빼두고 필요할 때만 읽는다. 그래야 매뉴얼이 가벼워지고 여러 일꾼이 공유할 수 있다.

2. agent를 만드는 두 방식 — 비유하자면:

   • docs-guide = 정규직 전문가 미리 채용 (정해진 일을 항상 똑같이 잘함)

   • kkirikkiri = 매뉴얼을 읽어와 그 자리에서 팀을 꾸리는 즉석 캐스팅 (무슨 일이든 맞춰 만들고, 여러 명을 팀으로 운영)

   • 👉 정해진 일엔 전자, 뭐가 올지 모르는 일엔 후자가 유리.

3. 에이전트끼리는 생각을 공유하지 않는다 — 각자 분리된 방에서 일하므로, kkirikkiri는 공유 메모리(md 파일) 에 내용을 적고 SendMessage로 "확인해!" 신호만 보낸다. (파일=무엇을, 메시지=언제)

나만의 꿀팁 🍯

• 문서를 통째로 읽지 말고 "이미 아는 건 빼고 빠진 것만 찾아줘" 라고 서브에이전트에게 시키면 중복 없이 핵심만 모인다.

• AI 정리는 항상 직접 한 번 검증하자 (아래 시행착오 참고).

시행착오

처음에 Claude가 세 플러그인을 전부 command → SKILL.md → reference 흐름으로 정리했는데, 직접 command 파일을 열어보니 틀렸습니다. allowed-tools에 Skill 도구가 아예 없었고, 실제론 위 도식처럼 셋이 다 다른 방식이었죠. → "AI가 그렸다고 다 맞는 게 아니다" 를 체감하고 v2로 전부 수정했습니다.

앞으로의 계획

• 학습한 구조를 토대로 나만의 간단한 멀티에이전트 스켈레톤(문서 작성 팀)을 만들어봤고, 이걸 더 다듬어볼 예정.

• 나머지 플러그인(deep-research, vibe-sunsang 등)도 같은 양식으로 정리.

• SendMessage/TeamCreate 는 Claude Code의 Agent Teams 기능이 켜져야 동작하는데, 이 기능에 대한 정리.