앞선 Claude 첫 포스팅에서도, 그 이전의 2025년 회고에서도 예고했듯, 저는 AI 관련 포스팅(특히 Claude Code)을 계속 내놓을 예정입니다. 앞으로 글에서 계속 등장하게 될 용어들을 한 번은 소개하고 가는 시간이 필요하겠다고 느꼈습니다.

제가 Claude Code를 접하고 학습하면서 쌓아온 지식과 함께 저만의 해석을 곁들여 소개하겠습니다.

Thread와 LinkedIn, Blog에서 많은 노하우를 수집했지만, 학습 과정에서 AI를 활용하기도 했습니다.
제가 놓친 잘못된 정보는 댓글이나 메일로 제보해주시면 감사한 마음으로 정정하겠습니다. 잘 부탁드립니다.

Claude Code에는 Claude Code의 동작을 확장하는 수단이 있습니다. command, skill, sub-agent, hook입니다. 이게 무엇인지, 언제 무엇을 써야 하는지 헷갈리기 쉽죠.

이 글에서는 이런 내용들을 다뤄보겠습니다.

  • 각각의 개념이 무엇인지
  • 어떻게 작성하고 활용하는지
  • 각 요소를 조합하는 실전 패턴

이 글은 2026년 1월 기준으로 작성되었습니다.
Claude Code는 빠르게 진화 중입니다. 공식 문서도 함께 확인하시길 권합니다.

이후 소개할 내용의 요약본입니다. Hooks는 성격이 조금 달라 제외하고, 나머지 3가지 요소를 비교합니다.

구분Slash CommandsSkillsSubagents
호출 방식사용자가 /command 입력Claude가 자동 판단 (또는 /skill 호출)Claude가 병렬 실행
목적반복 작업 단축키도메인 전문 지식 패키징병렬/격리된 작업 수행
구조단일 .md 파일폴더 (SKILL.md + 리소스)단일 .md 파일
컨텍스트 로딩호출 시 즉시 전체 로딩이름/설명만 로딩 → 필요 시 전체별도 컨텍스트 윈도우
위치.claude/commands/.claude/skills/.claude/agents/
글로벌 위치~/.claude/commands/~/.claude/skills/~/.claude/agents/
인자 전달$ARGUMENTS 키워드frontmatter trigger 필드frontmatter로 역할 정의
토큰 효율호출 시 전량 소모점진적 로딩 (효율적)별도 윈도우 (메인 절약)

사용자가 직접 호출하나?YesCommandNo스크립트/파일 번들이 필요한가?YesSkillNo병렬 실행이 필요한가?YesAgentNoCLAUDE.md

이 플로우차트는 각 요소의 핵심 특징을 기준으로 구분했습니다.

요소핵심 특징
Command사용자 직접 호출, 단일 .md 파일
Agent병렬/독립 실행, 단일 .md 파일
Skill자동 실행, 폴더 단위 번들링, 점진적 로딩

Slash Commands는 사용자가 직접 트리거하는 반복 작업 단축키입니다. 저는 이걸 게임에 빗대면 "액티브 스킬"이라고 이해했습니다.

터미널에서 / 를 입력하면 자동완성 목록에 사용 가능한 명령이 나타납니다. 저는 이 블로그 프로젝트에서 이런 command를 주로 사용하고 있습니다.

text
/commit       → 커밋 메시지 생성 + 커밋
/pr           → PR 생성
/check-post   → 포스트 품질 검사

.claude/commands/ 디렉토리에 .md 파일을 생성하면 곧바로 명령어가 됩니다. 파일명이 곧 명령어 이름이에요.

directory
.claude/commands/
├── commit.md        # → /commit
├── pr.md            # → /pr
└── check-post.md    # → /check-post

글로벌 명령어는 ~/.claude/commands/에 두면 모든 프로젝트에서 사용할 수 있습니다.

$ARGUMENTS 키워드를 사용하면 명령어에 인자를 전달할 수 있습니다. (Pass Arguments to Skills)

.claude/commands/commit.md
아래 옵션에 따라 커밋을 진행해주세요.
 
옵션: $ARGUMENTS
 
- "auto": 자동으로 메시지를 생성하고 커밋
- "amend": 직전 커밋에 수정사항 추가
- 그 외: 사용자에게 메시지를 질문

이렇게 작성하면 /commit auto, /commit amend 등으로 동작을 분기할 수 있습니다.

✅ 적합한 경우

  • 코드 리뷰 요청 (/review)
  • 커밋 메시지 생성 (/commit)
  • 테스트 실행 (/test)
  • 특정 포맷으로 문서 생성

❌ 부적합한 경우

  • Claude가 자동으로 판단해야 하는 작업 → Skill
  • 여러 파일/스크립트가 필요한 복잡한 워크플로우 → Skill
  • 병렬 처리가 필요한 작업 → Subagent

Skills는 Claude가 상황에 맞게 자동으로 로딩하는 도메인 전문 지식 패키지입니다. Commands와의 핵심 차이는 두 가지예요.

  1. 자동 트리거: Claude가 description을 보고 필요하다고 판단하면 자동으로 로딩합니다.
  2. 번들링: 워크플로우, 스크립트, 템플릿, 참조 문서 등을 폴더 단위로 묶을 수 있습니다.

1의 자동 트리거의 특성 때문에 저는 Skill을 게임에 빗대면 "패시브 스킬"이라고 이해했습니다. 상황이 되면 자동으로 트리거가 되는 거죠.

추가로 2의 폴더 단위 구조는 나누고 보기 좋게 정리하는 것 뿐만 아니라, 토큰을 점진적으로 사용한다는 것에 의미를 가집니다. 이후에 더 설명하겠습니다.

모든 Skill은 SKILL.md 파일을 가집니다. YAML frontmatter에 메타데이터를, 본문에 지침을 작성합니다. (Configure Skills)

SKILL.md
---
name: supabase-operations
description: Supabase 마이그레이션, 백업, 데이터 작업 처리.
  "supabase", "migration", "백업", "DB" 언급 시 사용.
---
 
# Supabase Operations
 
## 개요
이 스킬은 Supabase 관련 모든 작업을 처리합니다.
 
## 워크플로우
- 마이그레이션: workflows/migration.md 참조
- 백업: workflows/backup.md 참조
 
## 핵심 규칙
1. DML 마이그레이션은 더블 체크 필수
2. Production 작업 전 반드시 사용자 승인
...

제가 AI 지식을 흡수할 때 많이 참고하는 정구봉님 LinkedIn에서 한 번 언급이 되었던 디렉토리 구조입니다. (링크) 한 때 SKILL이 처음 도입되고 표준 없이 각자의 디렉토리를 가지며 구성하게 되었는데요, agentskills.io에서 만든 표준 디렉토리 구조가 현재 시장의 표준으로 채택이 된 듯 합니다.

directory
my-skill/
├── SKILL.md          # Required: 지시사항 + 메타데이터
├── scripts/          # Optional: 실행 가능한 코드
│   └── validate.sh
├── references/       # Optional: 참조 문서
│   └── schema.md
└── assets/           # Optional: 템플릿, 리소스

Claude가 Skill을 선택하는 기준은 description 필드입니다.

example.md
# 좋은 예시
description: Extract text and tables from PDF files, fill forms,
  merge documents. Use when working with PDF files or when the
  user mentions PDFs, forms, or document extraction.
 
# 나쁜 예시
description: PDF 처리

Skill은 Claude Code에 의해 자동 발동됩니다. 그래서 발동해야 할 때, 발동하지 않기도 합니다. Skills 최적화 가이드에 따르면, description을 최적화하기만 해도 활성화율이 20%에서 50%로 올라갑니다. 예시를 잘 작성하면 90%까지 상승한다는 결과도 있죠. description은 잘 작성해야 합니다.

작성 팁

  • 구체적인 동작을 나열합니다 (extract, fill, merge)
  • 트리거 키워드를 포함합니다 (PDF, forms, document)
  • 언제 사용할지 명시합니다 (Use when...)

그럼에도 저는 Skill이 잘 동작하지 않는 문제를 겪었고, 명시적으로 Agent가 Skill을 검토하고 실행하도록 구조를 마련했습니다. 소개 단계인 이 글에서는 각설하고, 이후에 별도 포스트로 소개하겠습니다.

Skill의 큰 장점은 점진적 로딩입니다. (참고: 점진적 로딩)

  1. 세션 시작 시: 이름과 description만 로딩 (~200바이트)
  2. 필요할 때: SKILL.md 전체 로딩
  3. 세부 작업 시: 하위 워크플로우/참조 문서 로딩

이 구조 덕분에 Skill이 아무리 많아도 시작 시 토큰을 낭비하지 않습니다.

이는 Skill의 강점이면서도 치명적인 아킬레스건입니다.

토큰 절약의 역설, 역설적이게도 토큰을 많이 사용하는 참조 문서를 항상 읽는 것이 아니기 때문에 원하는 결과를 제대로 얻지 못하는 경우도 있습니다. Trade-Off를 고려해서 SKILL.md와 하위 폴더로 적절히 지침을 배치하는 것이 좋습니다.

  • Skill 발동 시 꼭 읽어야 하는 지침: SKILL.md
  • 기타 참고 문서 및 helper 파일: 하위 디렉토리

제가 Claude Code Skill을 처음 접했을 때 본 Youtube 영상을 소개합니다.

https://www.youtube.com/watch?v=jxzpitU9YBg

Skill은 매력적입니다. 마치 NPM처럼 커뮤니티의 Skill을 사용할 수도 있고, 반대로 내 Skill을 다른 사람에게 이식하기도 자유롭거든요. 다른 Skill끼리 강결합되는 의존성도 없습니다. 설치도 필요 없습니다. 그냥 파일과 폴더들일 뿐이에요.

Skill을 공유하는 marketplace에는 이런 곳들이 있습니다.

마켓플레이스특징
SkillsMP스마트 검색, 카테고리 필터링, 품질 지표
AgentSkills.best최초의 Claude Agent Skills 마켓플레이스
SkillHub7,000+ AI 평가 스킬
Anthropic 공식 저장소공식 Skill 컬렉션

이 중 현재는 SkillsMP가 대표적인데요, 기하급수적인 상승폭을 자랑하고 있습니다.

SkillsMP

또, 이와 관련된 재미 있는 LinkedIn 포스팅이 있어 소개합니다.

https://www.linkedin.com/posts/sangrok-jung-9ab787311_claude-code-%EC%8A%A4%ED%82%AC-%EC%A4%91%EC%97%90-%EC%B2%9C%EB%AC%B8%ED%95%99-%EC%B9%B4%ED%85%8C%EA%B3%A0%EB%A6%AC%EC%97%90%EC%84%9C-%EC%9D%BC%EB%B0%98%EC%9D%B8%EB%8F%84-%EC%93%B8-%EC%88%98-%EC%9E%88%EB%8A%94-activity-7418838555613118464-D-CI?utm_source=share&utm_medium=member_desktop&rcm=ACoAADwd3ogBhFa6advl8Q2_OHROY8KJJoLa2Xw

✅ 적합한 경우

  • PDF/Excel/Word 문서 처리
  • 특정 도메인 코딩 컨벤션 적용
  • 프로젝트별 아키텍처 가이드
  • 복잡한 워크플로우 (스크립트 포함)
  • 여러 프로젝트에서 재사용할 전문 지식

❌ 부적합한 경우

  • 단순 반복 명령 → Commands
  • 병렬 처리가 필요한 작업 → Subagents

Subagents는 별도의 컨텍스트 윈도우에서 독립 실행되는 전문 Claude 인스턴스입니다. 메인 대화의 컨텍스트를 오염시키지 않으면서, 병렬로 작업을 수행하고 결과만 돌려줍니다.

게임에 비유했을 때, 저는 "소환수"라고 생각했습니다. 사용자는 소환수에게 하나하나 명령적으로 지시하지 않습니다. 하지만, 각 소환수의 특성에 맞게 행동합니다. 사용자는 소환수 하나하나가 뭘 하는지 알지 않고 결과를 얻어올 뿐입니다.

.claude/agents/ 디렉토리에 .md 파일을 생성합니다.

.claude/agents/researcher.md
---
name: researcher
description: 코드베이스를 분석하고 관련 정보를 수집하는 리서치 전문 에이전트.
tools: Read, Glob, Edit
model: sonnet
---
 
# Researcher Agent
 
## 역할
코드베이스를 탐색하고, 관련 파일과 패턴을 분석하여
요약된 리서치 결과를 반환합니다.
 
## 규칙
- 파일을 수정하지 않습니다
- 발견한 내용을 구조화된 형태로 정리합니다
- 관련 파일 경로와 라인 번호를 포함합니다

Subagent의 핵심 가치는 두 가지입니다.

  1. 병렬 실행: 여러 Subagent를 동시에 띄울 수 있습니다. 리서치 에이전트 3개를 동시에 보내서 각각 다른 소스를 조사하는 식이죠.

  2. 컨텍스트 격리: 각 Subagent는 별도 컨텍스트 윈도우를 가집니다. 수만 줄의 코드를 분석해도 메인 대화의 컨텍스트가 줄거나 오염되지 않아요. 결과만 요약되어 돌아옵니다.

메인 대화 컨텍스트Subagent A리서치별도 context windowSubagent B코드 분석별도 context windowSubagent C테스트별도 context window결과 요약만 반환

Claude Code에는 기본 제공되는 Subagent 유형이 있습니다. (참고: Built-in subagents)

유형용도
Explore코드베이스 탐색, 파일 검색
Plan구현 전략 설계
Bash커맨드 실행 전문
general-purpose다목적 리서치 및 멀티스텝 작업

이 중 Explore는 코드베이스 탐색에서 자주 쓰입니다. 직접 Glob/Grep을 반복하는 것보다 Explore Subagent를 띄우는 것이 효율적이에요.

✅ 적합한 경우

  • 여러 소스에서 동시에 리서치
  • 대규모 코드베이스 분석 (파일별 분할)
  • 메인 컨텍스트 오염 방지
  • Plan Mode로 탐색만 하고 싶을 때
  • 토큰을 아껴야 할 때 (별도 윈도우)

❌ 부적합한 경우

  • 단순 순차 작업
  • 메인 대화와 컨텍스트 공유가 필요한 경우
  • 파일을 직접 수정해야 하는 경우 (권한 제한 가능)

Commands, Skills, Subagents를 이야기하면서 빼놓을 수 없는 것이 Hooks입니다. Hooks는 Claude Code의 특정 이벤트에 Shell 명령어를 연결하는 시스템이에요.

Agent가 Skill의 트리거 여부를 판단하고 실행하는 것과 달리, Hook은 해당 event가 발생하면 반드시 실행됩니다. 이게 Skill과의 큰 차이점입니다.

참고: Hook Events
이벤트발생 시점matcher (필터 조건)차단 가능
SessionStart세션 시작/재개 시시작 유형 (startup, resume, clear, compact)No
UserPromptSubmit프롬프트 제출 직후없음 (항상 실행)Yes
PreToolUse도구 실행 직전도구명 (Bash, Edit|Write, mcp__.*)Yes
PermissionRequest권한 다이얼로그 표시 시도구명Yes
PostToolUse도구 실행 성공 직후도구명No
PostToolUseFailure도구 실행 실패 직후도구명No
Notification알림 발생 시알림 유형 (permission_prompt, idle_prompt 등)No
SubagentStartSubagent 생성 시에이전트 유형 (Bash, Explore, 커스텀명)No
SubagentStopSubagent 완료 시에이전트 유형Yes
Stop응답 완료 시없음 (항상 실행)Yes
PreCompact컨텍스트 압축 직전트리거 유형 (manual, auto)No
SessionEnd세션 종료 시종료 사유 (clear, logout 등)No

matcher는 Hook이 실행될 조건을 필터링하는 정규표현식 문자열입니다. (Matcher patterns) 빈 문자열("")이거나 "*"이면 해당 이벤트의 모든 경우에 실행됩니다. UserPromptSubmit과 Stop은 matcher를 지원하지 않아 항상 실행됩니다.

matcher 활용 예시
// PostToolUse에서 파일 수정/생성 도구에만 반응
{ "matcher": "Edit|Write", ... }
 
// PreToolUse에서 MCP 서버의 모든 도구에 반응
{ "matcher": "mcp__.*", ... }
 
// SessionStart에서 새 세션 시작 시에만 반응
{ "matcher": "startup", ... }

차단 가능은 Hook이 exit 2 또는 JSON decision: "block" 응답으로 해당 동작을 막을 수 있는지를 뜻합니다. (종료 코드 2 동작)

  • Yes: PreToolUse → 도구 실행 차단, UserPromptSubmit → 프롬프트 차단 및 삭제, Stop → 대화 계속
  • No: 이미 발생한 이벤트이므로 차단 불가. exit 2 시 stderr만 전달

exit code 규칙: exit 0 성공(허용), exit 2 차단, 그 외 비차단 에러. ( 단순: 종료 코드)

.claude/settings.json에서 설정합니다.

.claude/settings.json
{
  ...
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/notify-discord.sh '작업 완료'"
          }
        ]
      }
    ]
  }
}

Hooks는 Command, Skill, Subagent 모두에서 발생하는 이벤트를 감지합니다. 예를 들어 Skill이 파일을 수정하면 PostToolUse 훅이 동작하고, Subagent가 작업을 마치면 Stop 훅이 동작합니다.

저의 경우, 이렇게 사용하고 있습니다.

  • 각 event마다 실행해야 하는 Shell script가 다양
    • event 대표 Shell script를 작성
    • 대표 Shell script에서 하위 Shell script 호출
  • Shell script 경로를 혼동하는 문제 발생
    • git을 활용해 최상위 경로를 찾는 방식으로 구성
.claude/settings.json
{
  ...
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$(git rev-parse --show-toplevel)/.claude/hooks/user-prompt-submit/main.sh\""
          }
        ]
      }
    ],
    ...
  }
}

가장 흔한 패턴입니다. Command는 가벼운 진입점, Skill은 실제 로직을 담당해요.

text
.claude/
├── commands/
│   └── commit.md          # 진입점: /commit, /commit auto
└── skills/
    └── git-workflow/
        └── references/
            └── commit-guide.md  # 실제 커밋 로직

Command 내용

.claude/commands/commit.md
git-workflow 스킬의 commit-guide를 참고하여 커밋을 진행하세요.
옵션: $ARGUMENTS

이 구조의 장점

  • Command는 가볍게 유지 (토큰 절약)
  • Skill은 여러 Command에서 재사용 가능
  • Skill 내부에 참조 문서, 템플릿 등을 번들링할 수 있음

제 실제 commit.md 파일입니다.

.claude/commands/commit.md
# 커밋 명령어
 
**⚠️ 필수**: 실행 전 반드시 `.claude/skills/git-workflow/references/commit-guide.md`를 읽고 절차를 정확히 따르세요.
 
`.claude/skills/git-workflow/SKILL.md`의 **커밋 절차**를 실행합니다.
 
## Auto 모드
 
- **기본 (`/commit`)**: AskUserQuestion으로 타입/메시지 확인 후 커밋
- **`/commit auto`**: 질문 없이 자동으로 타입/메시지 결정 후 바로 커밋
 
**주의**: `/commit auto` 시 Step 3의 AskUserQuestion을 생략하고 변경 내용 분석 결과를 기반으로 최적의 타입과 메시지를 자동 결정합니다.
 
---
 
**입력된 인자**: $ARGUMENTS

Subagent도 Skill에 접근할 수 있습니다. 메인 Claude가 아닌 Subagent가 Skill의 전문 지식을 활용하는 패턴이에요.

text
메인 Claude
    │
    ├── Subagent A (researcher) → security Skill 참조
    ├── Subagent B (reviewer) → code-style Skill 참조
    └── Subagent C (tester) → test-guide Skill 참조

Hook을 사용하면 사용자 입력부터 작업 완료까지 자동화 파이프라인을 구성할 수 있습니다. 제가 사용하고 있는 Hook 파이프라인 구조입니다.

사용자 프롬프트 입력UserPromptSubmit Hookskill-manager 호출Skill 자동 로딩작업 수행PostToolUse Hook린팅 / 포매팅Stop Hooksummary 저장 + Discord 알림

  1. Skills와 Commands는 공존합니다: 둘은 대체 관계가 아닙니다. Commands는 명시적 트리거, Skills는 자동 트리거로, 용도가 다릅니다.

  2. description이 활성화를 결정합니다: Claude가 Skill을 선택하는 유일한 기준입니다. 키워드와 사용 상황을 반드시 명확히 쓰세요.

  3. 점진적으로 마이그레이션하세요: 한 번에 모든 걸 Skills로 옮기지 말고, 가장 자주 쓰는 것부터 이동하세요.

  4. CLAUDE.md는 가볍게: 프로젝트 개요, 필수 명령어, 핵심 규칙만 남기세요. 나머지는 Skills로 분산하세요.

  5. Subagent는 컨텍스트가 비쌀 때: 단순 작업에는 오히려 오버헤드입니다. 병렬 처리나 컨텍스트 격리가 필요할 때만 사용하세요.

Claude Code의 확장 체계를 요약하면 다음과 같습니다.

  • Commands: 사용자가 직접 트리거하는 단축키입니다. 가볍고 빠릅니다.
  • Skills: Claude가 자동으로 선택하는 전문 지식 패키지입니다. 번들링과 점진적 로딩이 핵심이에요.
  • Subagents: 별도 컨텍스트에서 병렬 실행되는 독립 작업자입니다. 토큰 효율과 병렬성이 강점이에요.
  • Hooks: 이벤트 기반 자동화입니다. 세 요소를 연결하는 접착제 역할을 합니다.

네 가지를 적절히 조합하면, Claude Code는 단순한 코딩 도구를 넘어 프로젝트 전체를 관리하는 자동화 시스템이 됩니다.

'뭐 하나만 쓰면 안 되는거냐' 라고 하신다면 그래도 됩니다. 하지만 중용을 지키면 좋습니다. 이와 관련해 예전에 봤던 LinkedIn 포스팅 중 잘 정리되고, 공감이 된 글을 소개합니다.

적절한 자리에 두는 게 포인트입니다. - 배수정님 LinkedIn

Claude Code의 설계 주축인 Command, Skill, Subagent, Hooks에 대해 다뤄봤는데요, 이해에 도움이 되셨길 바랍니다. 다음 포스팅은 커뮤니티의 Claude Code 활용 팁, 유용한 링크, 제 Claude Code 활용 사례 등을 차례차례 풀어보겠습니다.

피드백은 언제나 환영합니다. 긴 글 읽어주셔서 감사합니다.