Claude Code에서 나만의 AI 전문가 만들기 — 서브에이전트 제작 가이드

Claude Code를 쓰다 보면 이런 순간이 온다. "이 작업만큼은 전문가가 봐줬으면." 코드를 짜다가 보안 취약점도 함께 검사하고 싶을 때, 대용량 로그 파일을 분석하느라 정작 하던 작업의 맥락을 잃어버릴 때, PR마다 똑같은 체크리스트를 반복할 때다.

Claude Code에는 이 문제를 해결하는 서브에이전트(Sub-agent)라는 개념이 있다. 메인 Claude에게 특정 작업을 "이건 전문가한테 맡겨"라고 위임할 수 있는, 목적에 특화된 AI 조수다. 마치 회사에서 법무팀·디자인팀·보안팀이 따로 있듯이, Claude Code에도 역할별 전문가를 만들어 붙일 수 있다.

더 좋은 점은 이 전문가를 직접 만들 수 있다는 것이다. 텍스트 파일 하나로 시작할 수 있고, 필요하면 새 도구까지 추가해 진짜 전문 시스템으로 키울 수 있다. 이 글은 그 방법을 처음부터 끝까지 설명한다.

언제 서브에이전트가 필요한가

서브에이전트가 빛을 발하는 상황은 크게 네 가지다. 하나만 해당해도 도입을 고려할 만하고, 여러 개가 겹칠수록 효과가 배가된다.

네 상황이 겹칠수록 서브에이전트의 효과가 커진다. 예를 들어 "보안 감사"는 ① 전문 지식이 필요하면서 ② 분석 결과가 방대하고, ④ PR마다 반복되는 경우가 많다. 세 가지가 겹치면 서브에이전트 없이는 버거운 작업이 된다.

핵심 구성요소 3가지

서브에이전트는 레고 블록처럼 세 가지 파츠를 맞추면 완성된다. 이 세 가지 중 하나라도 빠지면 제대로 동작하지 않는다.

세 구성요소의 역할을 비유로 이해하면 쉽다. 시스템 프롬프트는 직원 채용 공고의 "직무 기술서"다. 도구 목록은 그 직원이 회사 시스템에서 접근할 수 있는 "권한 범위"다. SKILL.md는 "이 사람을 언제 부를지"를 정하는 호출 규칙이다. 세 가지가 갖춰져야 제대로 된 전문가 에이전트가 탄생한다.

방법 1 — SKILL.md 파일 하나로 3가지 구성요소 담기

가장 빠른 방법은 SKILL.md 파일 하나를 작성하는 것이다. 이 파일 하나가 앞서 설명한 3가지 핵심 구성요소를 전부 담는다. 코드 한 줄도 필요 없다.

파일은 크게 두 영역으로 나뉜다. ---으로 감싼 frontmatter에 ② 도구 목록(allowed-tools)과 ③ 트리거(triggers)를 적고, 그 아래 본문에 ① 시스템 프롬프트를 적는다. 파일 하나로 끝이다.

# 파일 위치: ~/.claude/skills/code-reviewer/SKILL.md

# ━━━ frontmatter 시작 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
---
name: code-reviewer
description: |
  Python 코드 품질을 검사하는 시니어 리뷰어.
  코드 리뷰, PR 리뷰, review code를 언급하면 반드시 이 스킬을 사용한다.
version: 1.0.0

# [구성요소 ②: 도구 목록]
# 에이전트가 쓸 수 있는 도구를 제한한다.
# 리뷰어는 읽고 검색만 하면 되므로 Edit·Write 권한은 주지 않는다.
allowed-tools:
  - Read      # 파일 읽기
  - Grep      # 코드 내 패턴 검색
  - Glob      # 파일 목록 조회
  - Bash      # 테스트·린트 실행 확인

# [구성요소 ③: 트리거]
# 이 단어가 대화에 나오면 이 에이전트를 자동으로 호출한다.
triggers:
  - 코드 리뷰
  - PR 리뷰
  - review code
  - 리뷰해줘
---
# ━━━ frontmatter 끝 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# [구성요소 ①: 시스템 프롬프트]
# 여기서부터 아래 전체가 에이전트에게 주는 지시문이다.

당신은 Python 전문가로, 10년 경력의 시니어 엔지니어입니다.
코드를 볼 때 다음 순서로 검토합니다.

## 리뷰 순서

1. 변경된 파일 목록부터 확인한다.
2. 핵심 로직을 파악한다 (5분 이내).
3. 이슈를 버그 → 보안 → 성능 → 스타일 순으로 분류한다.
4. 각 이슈에 구체적인 수정 제안을 작성한다.

## 리뷰 원칙

- 문제를 지적할 때 반드시 코드의 정확한 위치(파일명:줄번호)를 명시한다.
- 좋은 부분도 반드시 언급해 균형 잡힌 피드백을 제공한다.
- "이 코드는 문제가 있습니다"가 아니라 "38번 줄의 user_input이 SQL에
  직접 들어가고 있어 SQL Injection 위험이 있습니다. f-string 대신 파라미터
  바인딩을 사용하세요"처럼 구체적으로 말한다.

파일 구조를 보면 3가지 구성요소가 어디에 들어가는지 분명하다. frontmatter의 allowed-tools가 ② 도구 목록이고, triggers가 ③ 트리거다. 그리고 frontmatter 아래 본문 전체가 ① 시스템 프롬프트가 된다. 파일 하나가 세 역할을 동시에 한다.

설치도 간단하다. 파일을 올바른 경로에 두면 Claude Code가 자동으로 인식한다.

# 스킬 디렉토리 만들고 파일 저장
mkdir -p ~/.claude/skills/code-reviewer
# 위 내용을 ~/.claude/skills/code-reviewer/SKILL.md 에 저장

# 대화창에서 바로 쓸 수 있다
# 사용자: "auth.py 코드 리뷰해줘"
# → "리뷰해줘"가 triggers에 있으므로 code-reviewer가 자동 호출된다
# → allowed-tools에 따라 Read·Grep·Glob·Bash만 사용한다
# → 본문 지시(시스템 프롬프트)대로 버그→보안→성능 순으로 분석한다

방법 2 — Plugin으로 구성요소를 분리하고 새 도구 추가하기

SKILL.md는 세 구성요소를 파일 하나에 몰아넣는다. 빠르지만 에이전트가 복잡해질수록 관리가 어려워지고, 가장 중요한 제약이 하나 있다. Claude Code에 이미 내장된 도구만 쓸 수 있다는 것이다. 외부 API를 호출하는 도구나 특수한 서비스와 연결하는 도구를 추가하고 싶다면 플러그인(Plugin) 방식으로 가야 한다.

여기서 두 개념을 구분해 두자. MCP(Model Context Protocol)는 AI 모델이 외부 도구를 표준 방식으로 호출하는 프로토콜이다 — USB-C처럼 규격이 통일되어 있으면 어떤 도구든 꽂을 수 있는 것과 같다. 플러그인은 그 MCP 서버를 비롯해 에이전트 정의·스킬·명령어를 한 묶음으로 패키징한 패키지다. MCP는 도구를 추가하는 방식이고, Plugin은 그것을 담는 그릇이다.

Plugin 방식에서는 3가지 구성요소가 각각 별도 파일로 분리된다.

my-project/                ← 프로젝트 루트 (이름은 자유)
  plugins/
    my-debugger/           ← 플러그인 ID (설치·공유의 기준이 되는 이름)
      .mcp.json            ← [선택] 새 도구를 제공하는 MCP 서버 목록
      agents/
        debugger.md        ← [구성요소 ①②] 시스템 프롬프트 + 도구 목록
      skills/
        SKILL.md           ← [구성요소 ③] 트리거 조건

SKILL.md에서 한 파일에 몰려 있던 세 구성요소가 agents/와 skills/로 나뉜다. 그리고 .mcp.json이 선택적으로 추가되어 새 도구를 Claude Code에 등록한다.

파이썬 디버깅 전문 에이전트를 예시로 만들어 보자. 이 에이전트는 sequential-thinking(LLM이 가설을 단계별로 명시적으로 세우고 검증하는 MCP 도구)이라는 새 도구를 추가해 사용한다.

1단계 — .mcp.json: 새 도구를 제공하는 MCP 서버 등록 (구성요소 ②의 확장)

// plugins/my-debugger/.mcp.json
// Claude Code에 없는 새 도구를 MCP 서버로 추가한다
{
  "sequential-thinking": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
  }
}

2단계 — agents/debugger.md: 시스템 프롬프트(본문) + 도구 목록(frontmatter)

---
name: python-debugger
description: Python 오류와 스택 트레이스를 보고할 때 자동 호출된다.

# [구성요소 ②: 도구 목록]
# .mcp.json에 등록한 MCP 도구도 여기서 허용할 수 있다
tools: Read, Edit, Bash, Grep, mcp__sequential-thinking__sequentialthinking
model: sonnet
---

# [구성요소 ①: 시스템 프롬프트]
당신은 Python 디버깅 전문가입니다.

오류를 받으면 다음 순서로 진행합니다.

1. 오류 메시지와 스택 트레이스를 꼼꼼히 읽는다.
2. sequential-thinking 도구로 가설을 단계별로 세우고 검증한다.
3. 스택 트레이스에서 파일과 줄 번호를 찾아 해당 코드를 읽는다.
4. 근본 원인을 고치는 가장 작은 변경만 제안한다.

출력 형식: 근본 원인 / 수정 내용 / 검증 명령

3단계 — skills/SKILL.md: 트리거 조건 (구성요소 ③)

---
name: python-debugger
description: Python 디버거 스킬

# [구성요소 ③: 트리거]
triggers:
  - Python 오류
  - 스택 트레이스
  - pytest 실패
  - 왜 안 되지
---

방법 1과 방법 2를 비교하면 이렇다. SKILL.md 방식은 파일 하나가 세 구성요소를 전부 담고, Plugin 방식은 구성요소를 파일별로 분리해 관리하면서 MCP로 새 도구를 추가한다. 에이전트가 단순하면 SKILL.md로 시작하고, 새 도구가 필요하거나 여러 사람에게 배포하려면 Plugin으로 키우면 된다.

배포: 만든 에이전트를 패키징하고 팀에 전달하기

에이전트를 팀과 공유하려면 먼저 배포용 패키지를 만들어야 한다. SKILL.md 방식은 폴더를 통째로 Git에 올리고, Plugin 방식은 npm 패키지로 묶는다.

SKILL.md 방식 배포 — Git 저장소로 공유

스킬 폴더를 Git 저장소에 올리면 팀원이 clone해서 가져다 쓸 수 있다. 버전 관리가 되므로 "이 에이전트가 언제 어떻게 바뀌었는지"도 추적할 수 있다.

# 1단: 공유할 스킬을 Git 저장소에 올린다
mkdir claude-skills
cp -r ~/.claude/skills/code-reviewer claude-skills/
cd claude-skills
git init && git add . && git commit -m "add code-reviewer skill"
git push origin main

# 2단: 팀원이 받아서 설치한다
git clone https://github.com/my-team/claude-skills.git
cp -r claude-skills/code-reviewer ~/.claude/skills/
# Claude Code 재시작 없이 바로 인식된다

Plugin 방식 배포 — npm 패키지로 배포

Plugin을 npm으로 배포하면 /plugin install 명령 한 번으로 설치할 수 있다. 먼저 프로젝트 루트에 package.json을 추가해 Claude Code가 이것을 설치 가능한 패키지로 인식하게 한다.

// my-project/package.json
{
  "name": "@my-team/claude-debugger",
  "version": "1.0.0",
  "description": "Python 디버깅 전문 에이전트",
  "keywords": ["claude-code-plugin"],
  "main": "plugins/my-debugger"
}

# npm에 배포
npm publish --access public

# 팀원이 설치하는 방법 — 한 명령으로 끝난다
/plugin install @my-team/claude-debugger

# 배포 전 로컬 테스트는 경로로 바로 설치
/plugin install ~/my-project

만들고 나면 어떻게 달라지나

서브에이전트를 도입하고 나면 작업 방식이 달라진다. 메인 Claude가 "작업 감독"이 되고, 전문 에이전트들이 "실무자"가 된다. 메인이 PR을 받으면 코드 리뷰어, 보안 감사자, 테스트 실행자에게 동시에 맡기고, 결과가 돌아오면 취합해서 사용자에게 보고한다.

이 구조가 가장 빛나는 순간은 병렬 실행이다. 코드 리뷰(3분)와 보안 감사(5분)를 순서대로 하면 8분이 걸리지만, 동시에 실행하면 5분에 끝난다. 에이전트 수가 많아질수록 이 효과는 커진다.

시작은 간단하다. 오늘 가장 자주 반복하는 작업 하나를 골라 SKILL.md 파일을 만들어 보자. "이 작업을 전문가에게 시키면 어떻게 하도록 지시할까"를 텍스트로 쓰는 것이 전부다. 그것이 서브에이전트의 첫 걸음이다.

---

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