클로드코드 에이전트/스킬/스크립트/훅이 뭘까에 대해 정리 해 봤습니다.

Claude Code에서 에이전트·스킬·스크립트·훅을 어떻게 구분해야 할까?

소개

Claude Code를 사용하다 보면 가장 먼저 부딪히는 벽은 개별 기능이 아니라 개념 간의 경계였다.

• 에이전트(Subagent)는 언제 쓰는 건지?

• 스킬(Skill)은 자동으로 실행되는 건지?

• 스크립트는 스킬이 실행하는 건지, Claude가 실행하는 건지?

• 훅(Hook)은 왜 Claude의 판단을 안 거치는지?

공식 문서를 읽어도 각각은 설명돼 있지만, 서로 어떻게 연결되는지 한 번에 이해하기는 쉽지 않았다.
이 글은 Claude Code를 실제로 조사하며 던졌던 질문 흐름과, 그 과정에서 정리된 개념을 기술 문서 관점에서 깔끔하게 정리한 것이다.

진행 방법

1. 조사하며 실제로 헷갈렸던 질문들

조사를 시작하면서 반복해서 나왔던 질문은 다음과 같았다:

• 서브에이전트는 스킬을 사용할 수 있는가?

• 스킬이 서브에이전트를 호출할 수는 없는가?

• 스킬과 스크립트의 관계는 정확히 무엇인가?

• 훅은 왜 Claude의 판단 없이 실행되는가?

• 복잡한 작업을 Claude가 자동으로 병렬 처리해줄 수 있는가?

이 질문들에 답하기 위해 Anthropic의 공식 저장소(anthropics/skills, anthropics/claude-code)와 실제 로드된 스킬 구조를 함께 확인했다.

2. 핵심 개념 4가지 정의

아래는 Claude Code에서 가장 혼동되기 쉬운 네 가지 요소를 역할 중심으로 재정의한 것이다.

🤖 Subagent (서브에이전트)

정의
특정 작업을 위임받아 수행하는 독립된 실행 주체

핵심 특징

• 별도의 컨텍스트를 가짐 (메인 Claude와 분리)

• 병렬 실행 가능

• Skills를 읽고 활용할 수 있음

• Scripts 실행 가능 (Bash 권한 필요)

못하는 것

• 다른 서브에이전트를 호출 ❌

언제 쓰나

• 대용량 작업

• 병렬 처리

• 메인 컨텍스트 오염 방지

📘 Skill (스킬)

정의
Claude에게 제공되는 지식·절차·가이드 문서

핵심 특징

• SKILL.md 중심의 마크다운 문서

• Claude가 상황에 따라 자동 로드

• 실행 주체가 아님

할 수 있는 것

• Scripts 사용 방법 안내

• 워크플로우 가이드 제공

못하는 것

• 서브에이전트 호출 ❌

• 스스로 실행 ❌

비유
→ 레시피북 (읽히기만 함)

🧩 Script (스크립트)

정의
Claude 또는 서브에이전트가 실행하는 결정론적 코드 파일

핵심 특징

• Python, Bash 등 실제 실행 코드

• Skills 내부 또는 Agent 전용으로 포함 가능

• 토큰 절약 & 결과 일관성

중요 포인트

• Script는 스스로 실행되지 않음

• 항상 Claude 또는 Subagent가 실행 주체

⚙️ Hook (훅)

정의
Claude Code의 특정 이벤트 발생 시 무조건 실행되는 자동화 명령

핵심 특징

• Claude의 판단을 거치지 않음

• PreToolUse / PostToolUse / SessionEnd 등 이벤트 기반

• 셸 명령으로 실행

언제 쓰나

• 자동 포맷팅

• 보안 차단

• 로깅, 정책 강제

비유
→ 센서 기반 자동 장치 (조건 만족 시 즉시 작동)

실전 구조 다이어그램

Claude Code 실행 구조 한눈에 보기

graph TD
    User[사용자 입력]
    Claude[Claude 메인]
    Skill[Skill
지식·가이드]
    Subagent[Subagent
전문 실행 주체]
    Script[Script
결정론적 코드]
    Hook[Hook
자동화 이벤트]

    User --> Claude
    Claude -->|읽음| Skill
    Claude -->|위임| Subagent
    Claude -->|실행| Script
    Subagent -->|읽음| Skill
    Subagent -->|실행| Script

    Claude --> Hook
    Hook -->|이벤트 발생 시 자동 실행| Script

이 다이어그램에서 핵심은 행동 주체는 오직 Claude와 Subagent뿐이라는 점이다.
Skill은 읽히고, Script는 실행되며, Hook은 조건 없이 개입한다.

실전 선택 가이드 (언제 무엇을 써야 할까?)

상황별 판단 체크리스트

✅ Skill을 써야 할 때

• 작업 방법을 Claude에게 가르치고 싶을 때

• 반복되는 절차나 판단 기준이 있을 때

• 코드보다 설명·가이드가 중요한 경우

예:

• “PDF 처리 방식 표준화”

• “프론트엔드 디자인 원칙 고정”

✅ Subagent를 써야 할 때

• 작업 단위가 크고 독립적일 때

• 병렬 처리가 필요할 때

• 메인 컨텍스트를 깔끔하게 유지하고 싶을 때

예:

• PDF 분석 + 코드 리뷰 동시 수행

• 대형 코드베이스 전수 분석

✅ Script를 써야 할 때

• 항상 같은 결과가 나와야 할 때

• 토큰을 절약하고 싶을 때

• 실제 파일/데이터 처리가 필요할 때

예:

• 포맷 변환

• 데이터 정제

• 자동 리포트 생성

✅ Hook을 써야 할 때

• Claude의 판단과 무관하게 강제해야 할 때

• 실수 방지, 정책 적용, 자동화가 목적일 때

예:

• 파일 저장 시 자동 포맷팅

• 특정 디렉토리 수정 차단

• 모든 Bash 명령 로깅

결과와 배운 점

1. 가장 중요한 구조적 결론

행동 주체: Claude / Subagent
지식 제공: Skill
실제 실행: Script
강제 자동화: Hook

2. 가능 / 불가능 관계 요약

3. 병렬 처리에 대한 오해 정리

• Claude는 기본적으로 병렬 실행을 자동 판단하지 않는다

• 병렬 처리를 원하면 다음 중 하나가 필요하다:

  • CLAUDE.md에 명시적 규칙 작성

  • Slash Command로 병렬 실행 강제

  • Subagent description에 proactively 힌트 제공

결과와 배운 점

1. 가장 중요한 구조적 결론

행동 주체: Claude / Subagent
지식 제공: Skill
실제 실행: Script
강제 자동화: Hook

2. 가능 / 불가능 관계 요약

3. 병렬 처리에 대한 핵심 깨달음

• Claude는 기본적으로 병렬 실행을 자동 판단하지 않는다

• 병렬 처리는 ‘기능’이 아니라 설계 결과다

• 다음이 있어야 병렬이 된다:

  • CLAUDE.md 규칙

  • Slash Command

  • Subagent description 힌트

마무리 정리

Claude Code는 기능이 많은 도구라기보다 역할이 분리된 시스템에 가깝다.

• Skills는 생각하지 않는다

• Scripts는 판단하지 않는다

• Hooks는 묻지 않는다

• 판단과 조율은 오직 Claude와 Subagent의 몫이다

이 구조를 이해하고 나니, 어떤 기능을 만들어야 할지 훨씬 명확해졌다.

도움 받은 자료 (선택)

• anthropics/skills GitHub

• anthropics/claude-code GitHub

• Claude Code 공식 문서