Agent Skills — Claude Code의 완전한 분류 체계 (Taxonomy)
Claude Code를 처음 사용할 때 — 우리는 흔히 "모든 것이 CLAUDE.md 안에 있다"고 이해합니다.
하지만 사용하다 보면 — 이상한 점들을 발견하기 시작합니다: /deploy가 스스로 작동하고, 파일 저장 시 감지하는 hook이 있으며, 작업을 수행하러 생성(spawn)되었다가 결과를 보고하고 돌아오는 subagent가 있습니다.
"이 명령들은 대체 어디서 오는 거지?"
Claude Code는 단순한 CLAUDE.md 파일 하나가 아니라, **계층적(layers)**인 instruction 시스템을 가지고 있습니다. 이는 서로 다른 지속성 모델(persistence model)로 작동하는 4개의 큰 그룹과 20개 이상의 메커니즘으로 구성됩니다.
4가지 지속성 모델 (Persistence Models) — 단순한 One-Shot과 Persistent가 아니다
| 모델 | 원칙 | 예시 |
|---|
| 🔒 Persistent | 한 번 설정하면 모든 세션에 유지됨 | CLAUDE.md, settings, skills |
| ... | | |
🔒 그룹 1: Persistent — 한 번 설정하면 모든 세션에 유지됨
이것은 Claude Code의 "척추"입니다 — 당신이 아무것도 하지 않아도 모든 세션에서 로드됩니다.
CLAUDE.md — 4단계
| 순서 | 위치 | 범위 (Scope) | 용도 |
|---|
| 1 | /etc/claude-code/CLAUDE.md (Linux) | 조직 전체 | 보안 정책, 회사 표준 |
| ... | | | |
원칙: 넓은 범위(scope)에서 좁은 범위로 로드됩니다 — 프로젝트 명령어가 사용자 명령어를 덮어씁니다 (override).
# ./CLAUDE.md
## Stack: Go 1.22+, PostgreSQL, chi router
## Rules:
...
Skills — 필요할 때 호출하는 명령 저장소
.claude/skills/<name>/SKILL.md
---
description: "Generate database migration files"
model: claude-haiku-4-5 # 쉬운 작업을 위해 적절한 모델 사용
...
/migration으로 호출하거나 — Claude가 컨텍스트(context)로부터 자동 감지(auto-detect)합니다.
Auto Memory — Claude가 스스로 기록함
당신은 그저 "항상 go test -race를 사용한다고 기억해 둬"라고 말하기만 하면 됩니다 — Claude는 ~/.claude/projects/<name>/memory/에 기록하며 — 다음번에 그것을 기억할 것입니다.
CLAUDE.md: 당신이 작성 | Auto Memory: Claude가 작성
CLAUDE.md: 규칙과 표준 | Auto Memory: 학습한 내용
Settings — 동작 제어
| 파일 | 범위 (Scope) |
|---|
~/.claude/settings.json | 사용자 (모든 프로젝트) |
| ... | |
{
"permissions": {
"allow": ["Bash(npm test:*)", "Read(~/*)"],
...
🔄 그룹 2: Context-Triggered — 필요할 때만 로드됨
이것은 "똑똑한" skills입니다 — 모든 세션에 로드되지 않으며 — 조건에 맞는 컨텍스트(Context)가 충족될 때만 로드됩니다.
Path-Scoped Rules
.claude/rules/api-design.md
.claude/rules/css-styling.md
Claude는 src/api/ 내의 파일과 작업할 때 api-design.md를 로드하며 — CSS를 건드리지 않는다면 css-styling.md는 로드하지 않습니다.
# .claude/rules/api-design.md
## When: working in src/api/**/*.go
- Always return JSON with `{data, error}` envelope
...
Nested CLAUDE.md
project/
├── CLAUDE.md ← 항상 로드됨
├── backend/
...
모노레포(monorepo)를 위해 사용됩니다 — 각 서브 프로젝트(sub-project)는 자신만의 컨텍스트(context)를 가집니다.
Skill Content — 호출 시 로드됨
Skills 메타데이터(이름 + 설명)는 컨텍스트에 항상 존재하지만 — skill의 **전체 내용(full content)**은 /skill 명령을 사용하거나 Claude가 자동 감지(auto-detect)할 때만 로드됩니다.
⚡ 그룹 3: Event-Driven — 이벤트 발생 시 자동 실행
이것은 가장 강력한 레이어이며 — 대부분의 사람들이 존재를 모르는 기능입니다.
Hooks — 30개 이상의 이벤트 유형 (Event Types)
| 그룹 | Events |
|---|
| 🔵 Session | SessionStart, Setup, PreCompact, PostCompact, SessionEnd |
| ... | |
Hook 예시: "Claude가 git push를 실행하기 전 — 항상 테스트를 먼저 실행하라"
{
"hooks": {
"PreToolUse": [
...
5가지 핸들러(Handler) 유형:
| Handler | 사용 시점 |
|---|
| Command | 셸 스크립트 (JSON stdin 수신) |
| ... | |
Subagents — 하위 에이전트
.claude/agents/reviewer.md
.claude/agents/tester.md
---
description: "Code reviewer — checks Go idioms and naming"
model: claude-haiku-4-5
...
Claude는 작업을 수행하기 위해 서브에이전트(subagent)를 생성(spawn)합니다 — 결과는 부모(parent)의 컨텍스트 윈도우(context window)에 포함되지 않으므로 — 토큰을 절약할 수 있습니다.
🎯 그룹 4: Session-Bound — 현재 세션에만 국한됨
| 메커니즘 | 예시 |
|---|
| CLI Flags | --model claude-opus-4-8, --permission-mode plan |
| ... | |
📊 로드 순서 — Claude Code가 시작될 때 일어나는 일
1. SYSTEM PROMPT (built-in)
└── 출력 스타일(Output style) 조정
...
📦 외부에서 Skills 설치하기 — 무엇을 얻을 수 있는가?
커뮤니티에서 흔히 볼 수 있는 인기 명령어:
npx skills@latest add mattpocock/skills
또는 다른 marketplace에서:
claude plugin install <name>@<marketplace>
무엇을 얻게 되나요? — 단순한 "skill" 그 이상입니다
mattpocock/skills (GitHub에서 ⭐ 157K)는 단순한 단일 skill 파일이 아니라, taxonomy의 모든 레이어(layer)를 한꺼번에 포함하는 Claude Code Plugin 패키지입니다:
| 얻게 되는 것 | 폴더 위치 | 레이어 유형 |
|---|
Skills (/review, /test, /plan) | .claude-plugin/ → skills | Persistent |
| ... | | |
요약: 단 한 번의 install로 skills, subagents, hooks, commands 등 모든 레이어를 모두 얻을 수 있습니다. | | |
설치된 항목 확인하기
# 1. 사용 가능한 모든 skills 확인 (plugin에서 설치된 항목 포함)
ls .claude/skills/
ls ~/.claude/skills/
...
설치 후 어디에 있나요?
mattpocock/skills (GitHub repo)
│
▼ npx skills@latest add
...
주의사항
- Plugin이 사용자의 설정을 덮어쓸 수 있습니다 (override) —
settings.json을 수정하는지 확인하세요.
- 설치 전 소스 코드를 확인하세요 — plugin은 hooks를 통해 shell commands를 실행할 권한을 가집니다.
- 테스트 프로젝트에서 먼저 시도하세요 — 실제 운영 중인 (production) 프로젝트에 바로 설치하지 마세요.
- 지속적으로 업데이트하세요 —
@latest는 최신 버전을 가져옵니다.
요약 — 올바른 레이어 선택하기
| 하고 싶은 작업... | 사용해야 할 것... | 이유... |
|---|
| Claude에게 프로젝트가 Go를 사용한다고 알리기 | ./CLAUDE.md | 모든 세션(session)에서 로드됨 |
| ... | | |
📚 더 읽어보기:
📅 작성일: 2026년 7월 | Claude Code v1.x
⚠️ Anthropic의 공식 문서를 참조함 — 기능은 변경될 수 있습니다.