클로드 코드 스킬, 서브에이전트, 훅 차이: 실체는 파일과 폴더

Claude Code(클로드 코드)는 터미널에서 대화하며 파일을 읽고 명령을 실행하는 도구입니다. 같은 프로젝트에서 같은 설명과 절차를 반복하기 시작하면 대화창 밖에 규칙과 작업 방법을 남겨둘 자리가 필요해집니다.

예를 들어 프로젝트 규칙은 파일에 고정할 수 있습니다. 반복 절차는 한 명령으로 부를 수 있고, 자료 조사 같은 부작업은 별도 컨텍스트에 맡길 수 있습니다. 특정 이벤트나 시간에 명령이 실행되게 만들 수도 있습니다. 이때 사용하는 CLAUDE.md, 플러그인, 스킬, 서브에이전트, 훅은 서로 맡는 일이 다릅니다.

처음 보면 모두 어려운 이름처럼 보입니다. 하지만 실제 형태는 대부분 마크다운 파일, 폴더, 설정 파일입니다. 공식 개요는 CLAUDE.md와 스킬, 훅을 사용자 정의 방법으로 묶어 소개하고, 서브에이전트는 별도 항목에서 다룹니다. 플러그인은 확장하기 문서에서 별도로 설명합니다. 이 레슨에서는 각 기능의 역할과 형태를 먼저 확인하고, 어떤 순서로 배우면 좋은지까지 정리합니다.

앞 트랙에서 터미널을 처음 열고 Claude Code를 설치해 첫 질문을 던지고 MCP까지 연결해 봤다면, 이제 대화창 밖에 놓인 기능의 역할과 형태를 구분할 차례입니다.

사용자 정의 (Customization)

사용자 정의는 Claude Code가 프로젝트 규칙을 따르고, 반복 절차를 불러오고, 일부 작업을 나눠 처리하고, 정해진 시점에 명령을 실행하도록 만드는 방식입니다. CLAUDE.md와 SKILL.md는 마크다운 파일이고, 서브에이전트도 마크다운 파일이며, 훅은 settings.json의 hooks 항목입니다. 플러그인은 이런 요소를 묶어 설치하는 패키지입니다.

사용자 정의 기능 비교: 역할과 파일 형태

이름부터 외우기보다 각 기능이 무엇을 대신하고 어디에 놓이는지 먼저 보면 구분이 쉬워집니다. 아래 표는 역할, 실제 형태, 사용 신호, 이 트랙에서 다루는 순서를 한 번에 보여줍니다.

표에서 플러그인만 역할의 층위가 다릅니다. CLAUDE.md, 스킬, 서브에이전트, 훅은 내가 규칙과 절차를 정하거나 일을 나눠 맡기는 기능입니다. 플러그인은 스킬, 훅, 서브에이전트, MCP 서버를 하나의 설치 단위로 묶어 남이 만든 기능을 가져오는 패키지입니다.

이 기능들을 처음부터 모두 만들 필요는 없습니다. 같은 규칙을 두 번 놓쳤을 때 CLAUDE.md를 찾고, 같은 절차를 반복할 때 스킬을 찾으면 됩니다. 대화창이 검색 결과로 가득 차거나 정해진 시점마다 사람이 시작 버튼을 눌러야 할 때 다음 기능으로 넘어가면 됩니다.

CLAUDE.md: 프로젝트 규칙 고정

CLAUDE.md는 Claude Code가 세션을 시작할 때 읽는 프로젝트 또는 개인 규칙 파일입니다. 코딩 표준, 작업 방식, 검토 기준처럼 여러 세션에서 반복해서 지켜야 할 내용을 맡깁니다.

형태는 프로젝트 루트의 ./CLAUDE.md, 프로젝트 안 .claude/CLAUDE.md, 개인 홈의 ~/.claude/CLAUDE.md 같은 마크다운 파일입니다. 적용 범위와 AGENTS.md를 함께 읽게 하는 방법은 CLAUDE.md 작성법 레슨에서 확인합니다.

플러그인: 이미 만든 기능 설치

플러그인은 다른 사람이 만든 여러 확장 요소를 하나의 설치 단위로 묶은 패키지입니다. 스킬, 서브에이전트, 훅, MCP 서버처럼 Claude Code의 작업 범위를 넓히는 요소를 가져오는 역할을 합니다.

형태는 마켓플레이스에서 발견하고 설치하는 패키지입니다. 마켓플레이스 등록과 플러그인 설치, 비활성화, 삭제는 플러그인 설치 레슨에서 확인합니다.

스킬: 반복 절차를 파일로 저장

스킬은 반복 절차와 참고 지침을 SKILL.md에 담아 Claude Code가 필요할 때 불러 쓰는 확장 단위입니다. 같은 순서의 작업을 다시 설명하는 일을 줄이는 역할을 합니다.

형태는 이름을 가진 폴더와 그 안의 SKILL.md 파일이며, 프로젝트용은 .claude/skills/<이름>/SKILL.md, 개인용은 ~/.claude/skills/<이름>/SKILL.md에 둡니다. 파일 작성과 호출 방법은 스킬 만들기 레슨에서 확인합니다.

서브에이전트: 부작업을 따로 맡기기

서브에이전트는 특정 작업을 별도 컨텍스트에서 처리하는 독립 에이전트 설정입니다. 검색 결과와 로그가 주 대화에 쌓이지 않게 부작업을 나누고 결과만 돌려받는 역할을 합니다.

형태는 .claude/agents/ 또는 ~/.claude/agents/에 두는 마크다운 파일입니다. 위임 범위와 컨텍스트 사용 방법은 서브에이전트 레슨에서 확인합니다.

훅과 예약: 이벤트와 시간에 맞춰 실행

훅은 세션 시작이나 파일 편집 뒤처럼 특정 이벤트에 셸 명령을 연결하는 자동화 기능이고, 예약은 정한 시각에 작업을 실행하는 방식입니다. 사람이 시작 버튼을 누르지 않아도 되게 만드는 역할은 같지만, 하나는 이벤트에 다른 하나는 시간에 반응합니다.

훅의 형태는 settings.json의 hooks 항목이고, 예약은 클라우드 루틴, 데스크톱 예약 작업, /loop 같은 별도 실행 설정입니다. 이벤트와 예약 조건, 안전한 범위는 훅과 예약 레슨에서 확인합니다.

배우는 순서: CLAUDE.md부터 자동화까지

이 트랙은 CLAUDE.md, 플러그인, 스킬, 서브에이전트, 훅과 예약 순서로 진행합니다. 먼저 프로젝트 규칙을 파일에 고정한 뒤 남이 만든 기능을 설치하고, 그다음 내 절차를 스킬로 만들고, 부작업을 별도 컨텍스트에 맡기고, 마지막에 시작 시점까지 자동으로 넘깁니다.

기능을 만드는 부담만 보면 플러그인 설치가 가장 가볍고 자동화가 가장 무겁습니다. 그러나 이 트랙에서 CLAUDE.md를 먼저 다루는 이유는 뒤 레슨의 스킬, 서브에이전트, 자동화가 그 파일의 규칙을 가져다 쓰기 때문입니다. 배우는 순서는 기능의 무게만으로 정하지 않고 다음 레슨에서 쓸 재료까지 고려해 정했습니다.

.claude 폴더 확인: 실제 파일 위치

앞에서 본 기능은 화면에만 있는 메뉴가 아닙니다. 프로젝트 폴더의 .claude/와 내 컴퓨터 홈 폴더의 ~/.claude/에 파일과 폴더로 놓입니다. 프로젝트 .claude/에는 settings.json, settings.local.json, skills/, agents/, rules/, commands/ 같은 항목이 들어갈 수 있고, 훅은 별도 폴더가 아니라 settings.json의 hooks 항목입니다. 홈에는 개인 CLAUDE.md와 자동 메모리가 쌓이는 projects/도 있습니다.

저는 이 확인을 한참 뒤에야 했습니다. 처음 열어본 .claude/에는 이미 파일이 들어 있었고, 그게 신기해서 자동으로 관리되는 줄 알았습니다. 프로젝트마다 만들어 쓰면서도 안을 들여다보지 않았습니다.

그러다 어느 날, 한참 쓰던 프로젝트의 폴더가 비어 있고 만들어둔 줄 알았던 스킬도 제대로 만들어져 있지 않다는 걸 발견했습니다. 저만 잘 되고 있는 줄 알았던 겁니다. 그때 폴더 구조부터 배워야겠다고 처음 느꼈습니다. 위의 명령어 두 줄이 그때 아쉬웠던 확인을 대신해 줍니다.

MCP: 외부 서비스 연결 기능

MCP(Model Context Protocol)는 Claude Code와 데이터베이스나 Slack(슬랙) 같은 외부 서비스 사이를 연결하는 공통 규격입니다. 앞에서 본 기능들이 Claude Code가 어떤 규칙을 따르고 어떤 절차를 실행할지 정한다면, MCP는 Claude Code가 바깥 서비스의 데이터와 기능에 닿게 합니다.

그래서 MCP는 이 레슨에서 다루는 사용자 정의 기능에 포함하지 않습니다. 트랙 ②(연결하기)에서 MCP라는 공통 규격을 설명했고, 트랙 ③(CLI 트랙)에서 claude mcp add로 실제 연결까지 해봤습니다. 여기서 같은 내용을 반복하지 않고 앞 트랙으로 연결합니다.

자주 묻는 질문

Claude Code(클로드 코드) 스킬과 서브에이전트는 뭐가 다른가요?▸

스킬은 반복 절차와 참고 지침을 담은 폴더이고, 서브에이전트는 그 절차를 포함해 별도 컨텍스트에서 작업하는 파일입니다. 스킬을 부르면 내용이 주 대화의 컨텍스트에 더해지지만, 서브에이전트는 작업 과정과 중간 파일을 따로 처리하고 요약만 주 대화로 돌려줍니다. 많은 파일을 읽거나 결과 요약만 필요한 부작업에는 서브에이전트를 쓰고, 주 대화에서 계속 참고할 절차에는 스킬을 씁니다. 둘은 함께 사용할 수도 있습니다.

Claude Code(클로드 코드) 자동화에서 훅과 예약은 어떻게 다른가요?▸

훅은 세션 시작이나 파일 편집 뒤처럼 특정 이벤트가 일어날 때 실행되고, 예약은 정한 시각이 되면 실행됩니다. 훅은 settings.json의 hooks 항목에 등록하고, 예약은 클라우드 루틴, 데스크톱 예약 작업, /loop처럼 별도의 실행 방식으로 설정합니다. 이벤트에 반응해야 하면 훅을, 정한 시간에 반복해야 하면 예약을 고르면 됩니다.

Claude Code(클로드 코드) 플러그인은 스킬과 뭐가 다른가요?▸

스킬은 반복 절차 하나를 담은 폴더이고, 플러그인은 스킬과 훅, 서브에이전트, MCP 서버 같은 요소를 묶어 설치하는 패키지입니다. 스킬 하나만 필요하면 직접 만들거나 개인 또는 프로젝트 위치에 두면 됩니다. 여러 기능을 한 번에 설치하거나 다른 사람이 만든 기능을 가져오고 싶을 때 플러그인을 씁니다.

.claude 폴더가 비어 있는데 정상인가요?▸

정상입니다. 프로젝트의 .claude 폴더는 미리 모든 기능이 들어 있는 폴더가 아니라 실제로 스킬이나 서브에이전트, 권한 설정을 만들 때 채워지는 자리입니다. 아무것도 만든 적이 없다면 폴더 자체가 없거나 settings.local.json 하나만 있을 수 있습니다. ls -a .claude와 ls ~/.claude로 프로젝트와 홈 폴더를 각각 확인해 보세요.

MCP는 이 기능 중 어디에 속하나요?▸

MCP는 사용자 정의 기능 중 하나가 아닙니다. CLAUDE.md, 스킬, 서브에이전트, 훅, 플러그인은 Claude Code(클로드 코드)가 어떤 규칙과 절차로 일할지 정하는 기능이고, MCP는 Claude Code(클로드 코드)를 데이터베이스나 Slack(슬랙) 같은 외부 서비스에 연결하는 공통 규격입니다. 방향이 다르므로 MCP는 트랙 ②와 트랙 ③에서 다룹니다.

Sources (7)펼쳐서 전체 출처 보기▸

• Claude Docs, "개요": 지침, skills 및 hooks로 사용자 정의하는 공식 표현 (2026-08-25 확인)
• Claude Docs, "Claude Code 확장하기": CLAUDE.md, 스킬, 서브에이전트, 훅, MCP, 플러그인 비교표와 '시간이 지남에 따라 설정 구축하기' 트리거 표, 플러그인이 스킬, 훅, 서브에이전트, MCP 서버를 묶는 패키징 계층이라는 설명 (2026-08-22 확인)
• Claude Docs, "`.claude` 디렉토리 살펴보기": 프로젝트 `.claude/`와 홈 `~/.claude/`의 구조, settings.json, skills/, agents/, rules/, commands/ 각 폴더의 역할과 로드 시점 (2026-08-22 확인)
• Claude Docs, "Skills로 Claude 확장하기": 스킬의 정의, 개인/프로젝트/플러그인 스킬 위치와 우선순위, 스킬과 서브에이전트의 결합 방식 (2026-08-22 확인)
• Claude Docs, "서브에이전트": 서브에이전트 정의, 컨텍스트 격리 개념, `.claude/agents/`와 `~/.claude/agents/` 범위 (2026-08-22 확인)
• Claude Docs, "훅으로 작업 자동화하기": 훅의 정의, 라이프사이클 이벤트, 설정 위치별 범위(`~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`) (2026-08-22 확인)
• Claude Docs, "마켓플레이스에서 미리 만들어진 플러그인 발견 및 설치하기": 플러그인과 마켓플레이스의 관계, 공식 마켓플레이스 자동 추가, `/plugin install` 사용법 (2026-08-22 확인)