Claude Code 스킬 MCP CLAUDE.md 차이, 무엇을 어디에 넣나
Claude Code 를 쓰다 보면 설정할 데가 자꾸 늘어난다. 프로젝트 규칙은 CLAUDE.md 에 적으라고 하고, 반복하는 일은 스킬로 만들라고 하고, 다른 서비스는 MCP 로 붙이라고 한다. 셋 다 Claude 한테 뭔가를 더 주는 거라 처음 보면 경계가 흐리다.
Claude Code 스킬 MCP CLAUDE.md 를 가르는 기준은 두 가지다. 언제 읽히느냐, 그리고 무엇을 주느냐. CLAUDE.md 는 늘 깔려 있는 규칙이고, 스킬은 필요할 때 펼치는 절차나 참고 자료, MCP 는 바깥 서비스에 닿는 도구다. 아래는 2026년 10월 16일에 연 공식 문서 기준이고, 끝에 내 PC 에서 실제로 나눠 둔 예를 붙였다.
CLAUDE.md 는 늘 깔려 있는 규칙
메모리 문서를 보면 내 모든 프로젝트에 걸리는 ~/.claude/CLAUDE.md, 저장소에 같이 올리는 ./CLAUDE.md 가 있다. 개인 파일이랑 작업 폴더, 그 위 폴더들의 CLAUDE.md 는 세션을 시작할 때 읽혀서 매 요청에 같이 들어간다. 하위 폴더의 CLAUDE.md 는 그 안의 파일을 다룰 때 읽힌다. 여러 파일이 있으면 덮어쓰지 않고 이어 붙인다. 파일 위치 얘기는 Claude Code 와 Codex 를 같이 쓰는 글에 더 자세히 적었다.
여기 넣을 건 매번 알아야 하는 사실이다. 빌드 명령, 시험 돌리는 법, 폴더 구조, 항상 지킬 규칙 같은 것. 문서는 파일 하나를 200줄 아래로 잡으라고 한다. 길수록 맥락을 많이 먹고, 지시를 지키는 정도도 떨어진다고. @경로 로 다른 파일을 가져올 수도 있는데, 가져온 파일도 시작할 때 같이 읽히니까 길이를 줄여 주진 않는다.
문서에 이런 말도 있다. 여러 단계짜리 절차이거나 코드 일부에만 해당하는 내용이면 스킬이나 경로별 규칙(.claude/rules/)으로 옮기라는 것. CLAUDE.md 가 불어나기 시작하면 그게 신호다.
하나 더. CLAUDE.md 는 강제 설정이 아니다. Claude 가 맥락으로 읽을 뿐이라서, 무슨 일이 있어도 막아야 하는 동작은 PreToolUse 훅으로 막으라고 적혀 있다.
Claude Code 스킬은 설명만 먼저, 본문은 쓸 때
스킬 문서에 따르면 스킬은 SKILL.md 파일 하나에 지시를 적어 둔 거다. 머리 정보에 name 을 따로 안 적으면 폴더 이름이 스킬 이름이 되고, 내가 /스킬이름 으로 부르거나 Claude 가 설명을 보고 알아서 꺼낸다.
차이는 읽히는 때. 평소에는 스킬의 설명(description)만 맥락에 들어가 있고, 본문은 실제로 쓸 때 들어온다. 그래서 긴 참고 자료를 넣어 둬도 안 쓰는 동안엔 자리를 거의 안 차지한다. 대신 한 번 불러오면 본문이 대화에 남아서 그 뒤로 매 턴 자리를 먹는다. 대화가 길어져 자동으로 요약되면 그때는 정해진 한도 안에서만 다시 붙어서, 일부가 잘리거나 오래된 스킬이 빠질 수 있다. 문서가 SKILL.md 를 500줄 아래로 두고 자세한 자료는 옆 파일로 빼라고 하는 이유다.
두는 곳은 이렇다.
| 범위 | 경로 | 쓰이는 곳 |
|---|---|---|
| 개인 | ~/.claude/skills/<이름>/SKILL.md | 이 PC 의 내 모든 프로젝트 |
| 프로젝트 | .claude/skills/<이름>/SKILL.md | 그 저장소, 커밋하면 팀이 같이 씀 |
| 플러그인 | <플러그인>/skills/<이름>/SKILL.md | 플러그인을 켠 곳, /플러그인:이름 으로 |
머리 정보는 다 선택인데 description 만큼은 넣으라고 권한다. Claude 가 그걸 보고 언제 쓸지 정하니까. 배포처럼 부작용이 있는 스킬은 disable-model-invocation: true 를 넣으면 된다. Claude 가 알아서 꺼내지 않고 내가 부를 때만 돈다. 이렇게 두면 설명도 맥락에 안 올라간다.
예전 .claude/commands/ 폴더에 만들던 명령은 스킬로 합쳐졌다. .claude/commands/deploy.md 랑 .claude/skills/deploy/SKILL.md 둘 다 /deploy 를 만들고 똑같이 동작한다고 문서에 나와 있다. 원래 쓰던 명령 파일도 그대로 돈다.
MCP 는 바깥 서비스에 닿는 도구
MCP 문서는 MCP 를 AI 도구 연동을 위한 오픈 소스 표준이라고 소개한다. MCP 서버를 붙이면 Claude Code 가 데이터베이스나 슬랙, 브라우저 같은 바깥 도구를 쓸 수 있다. 앞의 둘이 Claude 가 아는 것을 늘린다면, MCP 는 할 수 있는 일을 늘리는 쪽이다.
원격 서버는 claude mcp add --transport http <이름> <주소> 로 붙인다. 내 PC 에서 프로그램으로 도는 서버는 claude mcp add <이름> -- <명령> 처럼 -- 뒤에 실행 명령을 쓴다. 둘 다 공식 문서 예시고, 이번에 직접 붙여 보진 않았다.
범위가 세 가지라 저장 위치가 갈린다.
| 범위 | 쓰이는 곳 | 저장 위치 |
|---|---|---|
| local(기본) | 지금 프로젝트, 나만 | ~/.claude.json |
| project | 지금 프로젝트, 팀과 공유 | 프로젝트 루트 .mcp.json |
| user | 내 모든 프로젝트 | ~/.claude.json |
같은 이름이 여러 곳에 있으면 local, project, user 순으로 앞쪽이 이긴다. 맥락 부담은? 기본 설정이면 적은 편이다. 도구 검색이 기본으로 켜져 있어서 시작할 때는 도구 이름이랑 서버 안내만 읽히고, 자세한 정의는 그 도구가 필요할 때 불러온다. 다만 ENABLE_TOOL_SEARCH 설정이나 서버의 alwaysLoad 설정, 쓰는 모델과 환경에 따라 정의를 처음부터 다 읽기도 한다. 연결 상태는 /mcp 로 보고, 로그인이 필요한 원격 서버 인증도 여기서 한다.
그리고 주의할 것 하나. 문서는 서버를 붙이기 전에 믿을 수 있는지부터 확인하라고 한다. 바깥 내용을 가져오는 서버는 프롬프트 인젝션 위험이 있어서다. 저장소에 들어 있는 .mcp.json 서버는 대화형 세션에선 쓰기 전에 승인을 묻는데, claude -p 같은 비대화형 실행에선 물을 수가 없어서 그냥 불러온다고 적혀 있다. 남의 저장소를 받아서 바로 돌릴 거라면 .mcp.json 부터 열어 보자.
스킬 MCP CLAUDE.md, 넣을 곳 고르는 법
기능 개요 문서에 언제 무엇을 더하라는 표가 있다. 셋이랑 훅에 해당하는 줄만 우리말로 옮기면 이렇다.
| 이럴 때 | 여기에 |
|---|---|
| 같은 규칙이나 명령을 두 번 틀린다 | CLAUDE.md |
| 같은 절차를 대화에 세 번째 붙여 넣는다 | 스킬 |
| Claude 가 못 보는 브라우저 탭에서 자료를 자꾸 옮긴다 | MCP 서버 |
| 묻지 않아도 매번 일어나야 한다 | 훅 |
같이 쓰는 경우도 많다. 문서 예로는 MCP 가 데이터베이스에 연결해 주고, 스킬에 그 데이터베이스 구조랑 조회 요령을 적어 두는 식이다. 연결은 MCP 가, 쓰는 법은 스킬이.
내 PC 에서 나눠 둔 예
내 PC 의 개인 스킬 폴더(~/.claude/skills)에는 스킬이 두 개 있다. 그중 하나는 작업을 멈추거나 넘길 때 인계 문서랑 현재 상태 문서를 정리하는 절차다. SKILL.md 는 28줄이고, 설명 칸에는 언제 쓰는지를 꽤 길게 적어 뒀다. 작업이 끝났을 때, 멈출 때, 새 세션에서 이어받을 때까지.
전역 CLAUDE.md 에는 그 절차를 다 쓰지 않았다. 짧은 규칙 몇 줄이랑 자세한 절차는 그 스킬을 따른다는 한 줄뿐이다. 매번 알아야 하는 건 규칙이고, 절차는 그 일을 할 때만 필요하니까. 문서가 말하는 나눔이랑 같은 모양이다.
게임 저장소 TEXT WAR 는 오히려 단순하다. 루트 CLAUDE.md 는 서른 줄이 안 되고, 프로젝트 스킬 폴더도 .mcp.json 도 없다. 처음부터 다 갖출 필요는 없다는 거다. 기능 개요 문서도 CLAUDE.md 부터 시작하고, 위 표 같은 일이 생길 때 하나씩 더하라고 한다.
다음엔 바이브코딩 전에 알아 둘 웹 구조, HTML 이랑 CSS, JS, 서버가 각각 무슨 일을 하는지 얘기하려고 한다.