View
Claude Code Skills & Subagents 완벽 가이드
커스텀 명령어부터 서브에이전트까지, 공식 문서 기반 정리 (2026)
TL;DR
Claude Code는 Skills(커스텀 슬래시 명령어)와 Subagents(자율 실행 에이전트) 두 가지 확장 시스템을 제공합니다. 마크다운 파일 하나로 나만의 명령어와 에이전트를 만들 수 있으며, 프론트매터 설정으로 모델 선택, 호출 제어, MCP 통합까지 가능합니다. 이 글에서는 공식 문서 기반으로 두 시스템의 구조, 설정법, 활용법을 정리합니다.
Commands에서 Skills로 — 용어 변화
초기 Claude Code는 .claude/commands/에 마크다운 파일을 두는 방식으로 커스텀 슬래시 명령어를 지원했습니다. 현재는 이 시스템이 Skills로 통합되었습니다.
공식 안내: "Custom slash commands have been merged into skills. Your existing .claude/commands/ files keep working. Skills add optional features: a directory for supporting files, frontmatter to control whether you or Claude invokes them, and the ability for Claude to load them automatically when relevant."
| 구분 | 레거시 (Commands) | 현재 (Skills) |
|---|---|---|
| 경로 | .claude/commands/name.md |
.claude/skills/name/SKILL.md |
| 구조 | 단일 파일 | 디렉토리 (보조 파일 포함 가능) |
| 프론트매터 | 미지원 | 모델, 호출 제어, 도구 권한 등 설정 가능 |
| 자동 호출 | 불가 (사용자 직접 호출만) | Claude가 맥락에 따라 자동 호출 가능 |
기존 .claude/commands/ 파일은 그대로 동작합니다. 같은 이름의 Skill과 Command가 있으면 Skill이 우선합니다.
Skill 만들기
디렉토리 구조
Skill은 디렉토리 단위로 관리됩니다. SKILL.md가 진입점이고, 같은 디렉토리에 템플릿이나 스크립트 등 보조 파일을 함께 둘 수 있습니다.
.claude/skills/
└── explain-code/
├── SKILL.md # 진입점 (필수)
├── template.md # Claude가 참고할 템플릿
├── examples/
│ └── sample.md # 출력 예시
└── scripts/
└── validate.sh # Claude가 실행할 스크립트적용 범위
| 범위 | 경로 | 설명 |
|---|---|---|
| 프로젝트 | .claude/skills/name/SKILL.md |
해당 프로젝트에서만 사용, VCS로 팀 공유 가능 |
| 개인 | ~/.claude/skills/name/SKILL.md |
모든 프로젝트에서 사용 가능 |
| Enterprise | 관리형 설정 | 조직 내 전체 사용자에게 적용 |
SKILL.md 작성 예시
---
name: code-review
description: 변경된 코드를 리뷰합니다. 코드 리뷰 요청 시 자동 호출.
argument-hint: [파일경로 또는 PR번호]
---
# Code Review
코드 리뷰 시 다음 관점에서 분석합니다:
1. **코드 품질**: 네이밍, 함수 크기, 중복
2. **보안**: SQL Injection, XSS, 민감 정보 노출
3. **성능**: N+1 쿼리, 불필요한 연산
4. **에러 처리**: 빈 catch 블록, 누락된 에러 상태
## 결과 형식
| 심각도 | 파일 | 라인 | 내용 |
|--------|------|------|------|
| Critical / Warning / Info | ... | ... | ... |프론트매터 설정
SKILL.md 상단에 YAML 프론트매터를 작성하면 Skill의 동작을 세밀하게 제어할 수 있습니다.
| 필드 | 설명 | 기본값 |
|---|---|---|
name |
표시 이름 (소문자, 숫자, 하이픈만 가능, 최대 64자) | 디렉토리명 |
description |
Skill 설명. Claude가 자동 호출 판단에 사용 | - |
argument-hint |
자동완성에 표시될 인자 힌트 | - |
model |
Skill 실행 시 사용할 모델 | 상속 |
disable-model-invocation |
true로 설정하면 사용자만 호출 가능 (Claude 자동 호출 차단) |
false |
user-invocable |
false로 설정하면 / 메뉴에 숨김 (Claude만 호출) |
true |
allowed-tools |
권한 확인 없이 사용 가능한 도구 목록 | - |
context |
fork 설정 시 별도 서브에이전트 컨텍스트에서 실행 |
- |
agent |
context: fork 시 사용할 서브에이전트 타입 |
- |
호출 제어 매트릭스
프론트매터 설정 조합에 따라 Skill의 호출 방식이 달라집니다.
| 설정 | 사용자 호출 | Claude 자동 호출 |
|---|---|---|
| (기본값) | O | O |
disable-model-invocation: true |
O | X |
user-invocable: false |
X | O |
변수 & 동적 컨텍스트
Skill 내에서 사용할 수 있는 변수와 동적 데이터 주입 방법입니다.
인자 변수
| 변수 | 설명 | 예시 |
|---|---|---|
$ARGUMENTS |
전달된 인자 전체 | /review src/auth.ts --strict → src/auth.ts --strict |
$ARGUMENTS[N] |
N번째 인자 (0부터 시작) | $ARGUMENTS[0] → src/auth.ts |
$N |
$ARGUMENTS[N] 축약형 | $0, $1, $2 |
셸 명령어 주입 — !`command`
Skill이 로드되기 전에 셸 명령어를 실행하고, 그 결과를 컨텍스트에 주입할 수 있습니다.
# PR 리뷰 Skill
## PR 컨텍스트
- PR diff: !`gh pr diff`
- PR 코멘트: !`gh pr view --comments`
- 변경 파일 목록: !`git diff --name-only HEAD~1`위 Skill을 호출하면 gh pr diff, gh pr view --comments 등이 먼저 실행되고, 결과가 해당 위치에 삽입된 상태로 Claude에게 전달됩니다.
파일 참조 — @파일경로
@ 접두사로 파일을 직접 참조할 수 있습니다. 예: @package.json과 @tsconfig.json을 분석해주세요
Subagents — 자율 실행 에이전트
Skills와는 별개로, .claude/agents/에 정의하는 Subagents가 있습니다. Subagent는 독립된 컨텍스트에서 실행되며, 모델 선택, 도구 제한, MCP 서버 연동 등을 세밀하게 설정할 수 있습니다.
Skill vs Subagent 차이
| 구분 | Skill | Subagent |
|---|---|---|
| 경로 | .claude/skills/ |
.claude/agents/ |
| 실행 컨텍스트 | 메인 대화에서 실행 (기본) | 독립된 서브프로세스에서 실행 |
| 호출 방식 | 사용자 /명령어 또는 Claude 자동 |
Claude가 Task 도구로 위임 |
| 모델 설정 | 프론트매터 model |
프론트매터 model (sonnet/opus/haiku) |
| 용도 | 명령어, 가이드, 템플릿 | 복잡한 자율 작업, 병렬 처리 |
Subagent 프론트매터
---
name: researcher
description: 코드베이스를 탐색하고 분석 결과를 반환합니다
model: haiku # 빠른 탐색용으로 경량 모델 사용
maxTurns: 15
tools:
- Read
- Glob
- Grep
- WebSearch
disallowedTools:
- Edit
- Write # 읽기 전용 에이전트
---
코드베이스를 탐색하고 분석 결과를 정리합니다.
파일을 수정하지 않고 읽기만 합니다.주요 프론트매터 필드
| 필드 | 설명 |
|---|---|
model |
sonnet, opus, haiku, inherit 중 선택 |
tools / disallowedTools |
사용 가능/불가 도구 목록 (미설정 시 전체 상속) |
maxTurns |
최대 실행 턴 수 |
permissionMode |
default, acceptEdits, dontAsk, plan |
skills |
서브에이전트에 사전 로드할 Skill 목록 |
mcpServers |
서브에이전트에서 사용할 MCP 서버 (백그라운드 실행 시 불가) |
memory |
user, project, local — 영속적 메모리 범위 |
빌트인 Subagents
Claude Code에 기본 내장된 서브에이전트입니다.
| 이름 | 모델 | 용도 |
|---|---|---|
Explore |
Haiku (경량) | 코드베이스 읽기 전용 탐색/분석 |
Plan |
상속 | 계획 모드용 리서치 |
general-purpose |
상속 | 복잡한 멀티스텝 작업 (읽기+쓰기) |
Bash |
상속 | 별도 컨텍스트에서 터미널 명령 실행 |
플러그인 시스템 (Public Beta)
Skills, Agents, Hooks, MCP 서버를 하나의 패키지로 묶어 배포할 수 있는 시스템입니다. 다른 사람이 만든 플러그인을 /plugin install로 설치할 수 있습니다.
my-plugin/
├── .claude-plugin/
│ └── plugin.json # 매니페스트 (name, version, author)
├── skills/ # 커스텀 Skills
├── agents/ # 커스텀 Subagents
├── hooks/
│ └── hooks.json # 이벤트 핸들러
├── .mcp.json # MCP 서버 설정
└── .lsp.json # LSP 서버 설정플러그인의 Skill은 네임스페이스로 구분됩니다: /plugin-name:skill-name
실전 Skill 예시
예시 1: PR 리뷰 자동화
---
name: review-pr
description: PR을 리뷰합니다
argument-hint: [PR번호]
disable-model-invocation: true
---
# PR 리뷰
## PR 정보
- diff: !`gh pr diff $0`
- 코멘트: !`gh pr view $0 --comments`
## 리뷰 기준
1. 보안 취약점
2. 성능 이슈
3. 코드 컨벤션 위반
4. 에러 처리 누락
## 출력 형식
심각도별로 분류하여 테이블로 출력합니다.예시 2: Claude가 자동 호출하는 테스트 가이드
---
name: test-guide
description: 테스트 작성 시 프로젝트 컨벤션을 적용합니다. 테스트 코드를 작성할 때 자동 호출.
user-invocable: false
---
테스트 작성 시 다음 규칙을 따릅니다:
- 테스트 파일: `__tests__/` 디렉토리에 위치
- 네이밍: `*.test.ts` 또는 `*.spec.ts`
- Given-When-Then 패턴 사용
- Mock은 최소한으로, 실제 동작 테스트 우선user-invocable: false이므로 / 메뉴에 표시되지 않습니다. 대신 Claude가 테스트 작성 맥락을 감지하면 자동으로 이 Skill을 로드합니다.
예시 3: 서브에이전트로 분리 실행
---
name: deep-analysis
description: 코드베이스 심층 분석
context: fork
agent: Explore
---
프로젝트 구조, 의존성, 아키텍처 패턴을 분석합니다.
결과를 요약하여 반환합니다.context: fork로 설정하면 메인 대화 컨텍스트를 소비하지 않고 별도 서브에이전트에서 실행됩니다. agent: Explore는 Haiku 기반 읽기 전용 에이전트를 사용합니다.
팁: Extended Thinking 활성화
Skill 내에서 확장 사고(thinking mode)를 활성화하려면 Skill 내용 어딘가에 ultrathink라는 단어를 포함시키면 됩니다. 복잡한 추론이 필요한 Skill에서 유용합니다.
정리
- Skills는
.claude/skills/name/SKILL.md에 생성합니다 (레거시.claude/commands/도 호환) - 프론트매터로 모델, 호출 제어, 도구 권한을 설정할 수 있습니다
!`command`로 셸 명령어 결과를,$ARGUMENTS로 인자를 동적으로 주입할 수 있습니다- Subagents는
.claude/agents/에 정의하며, 독립된 컨텍스트에서 자율적으로 실행됩니다 user-invocable: false로 Claude만 자동 호출하는 숨겨진 Skill을 만들 수 있습니다- 플러그인으로 Skills + Agents + Hooks를 패키지로 묶어 배포할 수 있습니다
'Tech > Tool' 카테고리의 다른 글
| AI 에이전트란? 개념·종류·활용 사례 총정리 (2026) (0) | 2026.02.26 |
|---|---|
| Cursor AI 세팅 가이드 — Rules, MCP, Agent 모드까지 (2026) (0) | 2026.02.21 |
| Claude Code 세팅 가이드 — CLAUDE.md부터 MCP, 커스텀 에이전트까지 (2026) (1) | 2026.02.20 |
