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)에서 로드됨
...

📚 더 읽어보기:

• Claude Code: Settings & CLAUDE.md
• Claude Code: Hooks
• Claude Code: Skills
• Claude Code: Subagents

📅 작성일: 2026년 7월 | Claude Code v1.x
⚠️ Anthropic의 공식 문서를 참조함 — 기능은 변경될 수 있습니다.