아래 글은 built-in tools이 아닌 extension layer(CLAUDE.md, Skills, subagents, hooks, MCP, plugins)의 사용에 대한 글이다.
1. Overview
CLAUDE.md - 클로드가 모든 세션에서 참고하는 persistent context
Skills - 재사용 가능한 지식과 호출 가능한 워크플로우
MCP - 외부 서비스와 연결
Subagents - isolated context로 각자 실행하고, 요약을 반환
Hooks - agentic loop 바깥에서 결정론적 스크립트 실행
Plugins & marketplace - 이 기능들을 패키징하고 배포하는 것
Skills는 가장 유연한 방식이다.
스킬은 지식, workflows, instructions들을 담은 markdown 파일이다.
스킬은 슬래시 명령어로 직접 호출할 수도 있고, 상황이 맞다고 판단하면 Claude 가 자동으로 로드할 수도 있다.
그리고 현재 대화에서 사용할 수도 있고, subagent의 격리된 환경에서도 사용할 수 있다.
2. Match features to your goal
(여기서 말하는 features는 extension layer의 기능들을 말한다.)
기능들은 매 세션마다 Claude가 항상 보는 context 부터 필요할 때 쓰는 on-demand, 그리고 특정 event에서만 자동으로 호출되는 것까지 다양한 범위를 가진다.
| 기능 | 역할 | 사용하면 좋은 경우 | 예시 |
|---|---|---|---|
| CLAUDE.md | 매 대화마다 로드되는 영구 컨텍스트 | 프로젝트 규칙, “항상 지켜야 하는” 규칙 | “npm이 아니라 pnpm을 사용한다. 커밋 전에 테스트를 실행한다.” |
| Skill | Claude가 사용할 수 있는 지침, 지식, 워크플로우 | 재사용 가능한 내용, 참고 문서, 반복 작업 | /review로 코드 리뷰 체크리스트 실행; 엔드포인트 패턴을 담은 API 문서 스킬 |
| Subagent | 요약 결과만 반환하는 격리된 실행 컨텍스트 | 컨텍스트 분리, 병렬 작업, 전문 작업자 | 여러 파일을 읽고 핵심 내용만 요약하는 리서치 작업 |
| MCP | 외부 서비스와 연결 | 외부 데이터 접근 또는 실제 동작 수행 | 데이터베이스 조회, Slack에 메시지 전송, 브라우저 제어 |
| Hook | 이벤트에 의해 실행되는 결정론적 스크립트 | 예측 가능한 자동화, LLM 개입 불필요 | 파일 수정 시마다 ESLint 실행 |
Plugins 같은 경우는 스킬, 훅, MCP 서버를 하나로 묶은 설치 가능한 단위이다.
만약 여러 repo에서 같은 설정을 재사용하고 싶거나, 다른 사람에게 배포하고 싶을 때 플러그인을 사용하면 된다.
2-1. Compare similar features
Skill vs Subagent
Skill
- 정의 : 어떤 context에 붙일 수 있는 재사용 가능한 것
- 장점 : 여러 context에서 공유 가능
- 용도 : 참고 자료, 호출 가능한 작업(action)
- 추가 설명 : “이런 상황엔 이렇게 해”를 Claude에게 가르치는 것
Subagent
- 정의 : 메인 대화와 독립된 workers
- 장점 : 메인 컨텍스트와 독립적으로 작동해서 메인 context의 사이즈를 줄일 수 있음
- 용도 : 병렬적으로 작업할 필요 있을 때, 정말 많은 파일 읽을 때, 메인과 독립적인 전문 작업이 필요할 때
- 추가 설명 : subagent는 각각 고유의 instruction과 스킬을 사용할 수 있음
subagent는 리서치 할 때 필요함. 왜냐하면 많은 양의 문서를 읽어야하고 실제 main context는 리서치하는 과정은 필요 없고 결과만 필요하기 때문
CLAUDE.md vs Skill
CLAUDE.md
- 항상 하는 것
- 용도 : 코딩 컨벤션, 프로젝트 구조, 절대 하면 안되는 규칙 등
Skill
- 가끔 참고하는 것
- 용도 : 가끔만 필요로 하는 참고 자료(API 문서, 스타일 가이드 등), /<이름> 형식으로 직접 실행시키는 워크플로
Rule of thunmb
CLAUDE.md는 500줄 이하로 유지하고, 그게 더 커지기 시작한다면 reference content를 스킬로 옮길 것!
MCP vs Skill
MCP는 외부 서비스와 연결하고 Skill은 클로드의 지식을 확장시켜주는 역할이라 아예 다르다.
같이 쓰는 방식
MCP - DB에 연결
Skill - 스키마 설명, 자주 쓰는 쿼리 패턴 등 저장
2-2. Understand how features layer
feature들은 여러 level로 정의 될 수 있다.
-
사용자 전역(user-wide)
→ 내 계정 전체에 적용 -
프로젝트 단위(per-project)
→ 특정 레포에서만 적용 -
플러그인(via plugins)
→ 재사용/배포용 패키지 -
관리 정책(managed policies)
→ 조직/관리자가 강제 적용
CALUDE.md의 경우 - additive
- 현재 작업 디렉토리 + 상위 디렉토리의 CLAUDE.md가 로드된다.
- 작업 중에 하위 디렉토리로 들어가면 그 안의 CLAUDE.md도 추가 로드된다.
- 만약 충돌할 경우 CLAUDE가 판단해서 조정한다. 이때 구체적인 지침이 일반적인 지침보다 살아남는다.
Skill과 Subagent의 경우 - override by name
- 여러 레벨들에 같은 이름이 있을 경우 아래 우선순위로 overried 된다.
(managed > user > project for skills; manaed >CLI flag > project > user > plugin for subagents). - 플러그인은 중복을 피하기 위해 namespace가 있다.
MCP - override by name
- local > project > user
Hooks - merged
- 이벤트가 맞으면 전부 실행된다.
gpt가 말하는 calude.md 사용법
그래서 실전에서는 이렇게 쓴다 (중요)
🔹 홈 디렉터리 CLAUDE.md
• 전역 원칙
• 습관
• 안전 규칙
예:
• “항상 변경 전에 요약을 먼저 제시”
• “파괴적 명령은 반드시 확인 요청”
⸻
🔹 레포 루트 CLAUDE.md
• 프로젝트 규칙
• 스택
• 빌드/테스트 방식
⸻
🔹 서브디렉터리 CLAUDE.md
• 모듈/도메인 특화 규칙
• API 계약
• 레거시 주의사항
2-3 combine features
feature들은 모두 각기 다른 문제를 풀기 때문에 조합해서 사용하는 것이 좋다
| 패턴 | 동작 방식 | 예시 |
|---|---|---|
| Skill + MCP | MCP가 외부 시스템과의 연결을 제공하고, Skill이 그 연결을 어떻게 잘 사용하는지를 Claude에게 알려준다 | MCP로 데이터베이스에 연결하고, Skill에 스키마와 쿼리 패턴을 문서화 |
| Skill + Subagent | Skill이 여러 Subagent를 생성해 병렬 작업을 수행하게 한다 | /review 스킬이 보안, 성능, 스타일 서브에이전트를 각각 격리된 컨텍스트에서 실행 |
| CLAUDE.md + Skills | CLAUDE.md에는 항상 적용되는 규칙을 두고, Skill에는 필요할 때 로드되는 참고 자료를 둔다 | CLAUDE.md에는 “우리 API 규칙을 따를 것”을 명시하고, Skill에는 전체 API 스타일 가이드를 포함 |
| Hook + MCP | Hook이 이벤트를 감지해 MCP를 통해 외부 동작을 트리거한다 | Claude가 중요 파일을 수정하면 post-edit Hook이 Slack 알림을 전송 |
3. Understand context costs
모든 feature는 결국 claude를 통해서 실행되기 때문에 context를 사용한다.
너무 많이 추가하면 context가 금방 가득 차고, 노이즈가 늘어나 성능이 떨어지기도 한다.
(스킬이 잘못 써지거나, claude가 컨벤션을 잃거나...)
이런 상황을 방지하기 위해 feature 별 cost를 이해해야 한다.
3-1. Context cost by feature
| 기능 | 로드 시점 | 로드되는 내용 | 컨텍스트 비용 |
|---|---|---|---|
| CLAUDE.md | 세션 시작 | 전체 내용 | 모든 요청마다 |
| Skill | 세션 시작 + 사용 시 | 시작 시에는 설명만, 사용 시 전체 내용 | 낮음 (설명만 매 요청마다 로드)* |
| MCP 서버 | 세션 시작 | 모든 도구 정의와 스키마 | 모든 요청마다 |
| Subagent | 생성될 때 | 지정된 스킬을 포함한 새로운 컨텍스트 | 메인 세션과 격리됨 |
| Hook | 트리거될 때 | 없음 (외부에서 실행) | 없음 (단, 훅이 추가 컨텍스트를 반환하면 예외) |
스킬의 기본은 세션 시작 시 설명을 불러오는 거지만,
스킬의 frontmatter에 disable-model-invocation: true를 설정하면, 사용자가 수동으로 호출하기 전까지 Claude에게 그 스킬을 완전히 숨길 수 있다.
즉, context cost를 0으로 만드는 것이다.
3-2. Understand how features load
CLAUDE.md
로드 시점 (When)
• 세션 시작 시
로드되는 내용 (What loads)
• 모든 CLAUDE.md 파일의 전체 내용
(관리 정책, 사용자 레벨, 프로젝트 레벨 포함)
상속 / 탐색 방식 (Inheritance)
• Claude는 현재 작업 디렉터리부터 루트 디렉터리까지의 CLAUDE.md를 모두 읽는다.
• 작업 중 하위 디렉터리에 접근하면, 그 안에 있는 CLAUDE.md도 추가로 발견하여 로드한다.
• 자세한 동작은 How Claude looks up memories 문서를 참고.
권장 사항
• CLAUDE.md는 약 500줄 이하로 유지하는 것이 좋다.
• 참고용 자료나 자주 필요하지 않은 내용은 Skill로 옮겨라. (Skill은 필요할 때만 로드됨)
Skill
개념
- Skill은 Claude의 도구 상자에 추가되는 확장 기능이다.
- API 스타일 가이드 같은 참고 자료일 수도 있고, /deploy처럼 /이름으로 실행하는 워크플로일 수도 있다.
- 일부는 기본 제공되며, 사용자가 직접 만들 수도 있다.
- Claude가 상황에 맞게 자동으로 사용하기도 하고, 사용자가 직접 호출할 수도 있다.
로드 시점 (When)
- 기본적으로 세션 시작 시 - 스킬의 이름과 설명, 실제 사용 시 - 전체 내용
- disable-model-invocation: true가 설정된 사용자 전용 스킬은 수동 호출 전까지 아무것도 로드되지 않음
로드되는 내용 (What loads)
- 모델이 선택할 수 있는 스킬의 경우 - 모든 요청에서 이름과 설명을 본다
- /이름 으로 호출하거나 자동 로드되면 전체 내용이 컨텍스트에 들어온다
Claude가 스킬을 선택하는 방식
- Claude는 사용자의 작업을 스킬 설명과 매칭해 어떤 스킬이 관련 있는지 판단한다.
- 설명이 모호하거나 서로 겹치면, 잘못된 스킬을 선택하거나 유용한 스킬을 놓칠 수 있다.특정 스킬을 확실히 쓰게 하려면 /\으로 직접 호출해라.
- disable-model-invocation: true가 설정된 스킬은 호출 전까지 Claude에게 보이지 않는다.
컨텍스트 비용 (Context cost)
- 사용 전까지는 낮음
- 수동 전용 스킬은 호출 전까지 비용 0
서브에이전트에서의 동작
- 서브에이전트에서는 스킬이 온디맨드 로드되지 않는다.
- 서브에이전트에 전달된 스킬은 시작 시 전부 미리 로드된다.
- 메인 세션의 스킬을 자동으로 상속하지 않으며, 명시적으로 지정해야 한다.
권장 사항
- 부작용이 있는 스킬(배포, 삭제 등)은 disable-model-invocation: true를 사용해라.
MCP Servers
로드 시점 (When)
- 세션 시작 시
로드되는 내용 (What loads)
- 연결된 모든 MCP 서버의 도구 정의 JSON 스키마
컨텍스트 비용 (Context cost)
- 기본적으로 도구 탐색 기능이 활성화되어 있으며 MCP 도구가 컨텍스트의 최대 10%까지 로드되고 나머지는 필요할 때 지연 로드된다.
신뢰성 관련 주의사항
- MCP 연결은 세션 도중 조용히 끊길 수 있는데, 이때 서버가 끊기면 해당 도구는 경고 없이 사라진다.
- Claude가 더 이상 존재하지 않는 도구를 사용하려 할 수 있다.
- 이전에 되던 MCP 도구가 갑자기 안 되면 /mcp로 연결 상태를 확인해라.
운영 팁
- /mcp 명령으로 서버별 토큰 비용을 확인할 수 있다. 사용하지 않는 서버는 연결 해제해라.
Subagents
로드 시점 (When)
- 필요할 때 (사용자 또는 Claude가 생성할 때)
로드되는 내용 (What loads)
- 시스템 프롬프트 (캐시 효율을 위해 부모와 공유)
- skills: 필드에 지정된 스킬의 전체 내용
- CLAUDE.md와 git 상태 (부모로부터 상속)
- 리드 에이전트가 프롬프트로 전달한 컨텍스트
컨텍스트 비용 (Context cost)
- 메인 세션과 완전히 격리됨
- 메인 대화 기록이나 호출된 스킬을 상속하지 않는다
권장 사용처
- 전체 대화 맥락이 필요 없는 작업
- 파일을 많이 읽거나, 광범위한 검색이 필요한 작업
- 메인 세션이 비대해지는 것을 막고 싶을 때
Hooks
로드 시점 (When)
- 트리거 발생 시
- 예) 도구 실행 전/후, 세션 시작, 컨텍스트 압축 전, 기타 라이프사이클 이벤트 등
로드되는 내용 (What loads)
- 기본적으로 없음 : Hook은 외부 스크립트로 실행된다
컨텍스트 비용 (Context cost)
- 기본적으로 0
- 단, Hook이 출력 결과를 메시지로 반환하면 그만큼 추가됨
권장 사용처
- 린트, 로깅 같은 부작용 작업
- Claude의 사고 과정이나 컨텍스트에 영향을 줄 필요가 없는 자동화
