Claude Skills란 무엇인가

이 글은 Skills 코스의 첫 편입니다. Claude Code의 Skills가 무엇이고, 왜 CLAUDE.md에 전부 적는 방식과 다른지, 어떤 일을 Skill로 떼어내야 하는지를 다룹니다. 읽고 나면 공식 플러그인 하나를 설치해 Skill이 있을 때와 없을 때의 결과 차이를 직접 비교할 수 있습니다.

원구연 8주 과정에서는 2주차에 "스킬·MCP·서브에이전트는 아직 설치하지 마세요"라고 막아 둡니다. 개념 없이 설치부터 하면 오류의 원인만 늘기 때문입니다. 이 글이 그 "개념" 부분입니다. 다음 편 Skills가 해결하는 과제에서 실제 문제 사례로 이어집니다.

핵심 요약

• Skill은 SKILL.md 파일 하나가 중심인 폴더이고, Claude는 관련 요청이 오면 자동으로 불러오거나 /skill-name으로 직접 실행합니다.
• 평소에는 이름과 description만 컨텍스트에 있고, 본문은 호출될 때만 로드됩니다. 이것이 CLAUDE.md와 가장 큰 차이입니다.
• CLAUDE.md는 항상 읽히는 제1지침, Skill은 필요할 때 펼치는 절차서, MCP는 외부 도구·데이터 연결입니다. 셋은 대체재가 아니라 층위가 다릅니다.
• 개인 Skill은 ~/.claude/skills/, 프로젝트 Skill은 .claude/skills/에 둡니다. 플러그인 Skill은 플러그인명:스킬명으로 구분됩니다.
• 공식 마켓플레이스의 frontend-design 플러그인을 설치하면 Skill 유무에 따른 결과 차이를 5분 안에 체험할 수 있습니다.

왜 Skills가 필요한가

Claude Code를 몇 주 쓰다 보면 같은 설명을 반복하는 자신을 발견합니다. "회의록은 이 형식으로", "배포할 때는 빌드 통과 확인 후 커밋", "고객 이름은 홍OO으로 가려라". 처음에는 채팅에 붙여 넣고, 다음에는 CLAUDE.md에 적습니다. 그런데 CLAUDE.md는 세션이 시작될 때마다 통째로 읽히는 파일입니다. 절차가 열 개, 스무 개로 늘면 매 턴마다 그 전부가 토큰을 먹고, 정작 지금 작업과 상관없는 규칙이 판단을 흐립니다.

공식 문서는 Skill을 만들 시점을 이렇게 정리합니다. 같은 지침이나 체크리스트를 채팅에 계속 붙여 넣고 있을 때, 그리고 CLAUDE.md의 한 섹션이 "사실"이 아니라 "절차"로 자라났을 때입니다. 우리 팀의 예를 들면 "운영 서버 배포 절차"가 CLAUDE.md에 열 줄로 들어앉아 있다가 Skill로 독립했습니다. 배포는 하루 한두 번 하는 일인데 그 열 줄이 모든 대화에 실려 다닐 이유가 없었기 때문입니다.

우리 관점으로 말하면 Skill은 "발표 자료가 아니라 지금 돌아가는 시스템"의 한 부품입니다. 사람 머릿속에 있던 절차를 파일로 꺼내 두면 다음 세션의 Claude도, 팀의 다른 사람도 같은 절차를 씁니다.

레시피북 비유로 보는 단계적 로딩

주방에 레시피북이 있다고 생각해 보세요. 요리사는 책의 목차만 외우고 있습니다. "김치찌개 42쪽, 된장국 57쪽" 정도입니다. 주문이 들어오면 그때 해당 쪽을 펼칩니다. 책 전체를 매 주문마다 처음부터 읽지 않습니다.

Skills가 정확히 이 구조입니다. Claude Code는 세션 시작 시 등록된 모든 Skill의 이름과 description을 목록으로 컨텍스트에 올립니다. 이것이 "목차"입니다. 사용자의 요청이 어떤 Skill의 설명과 맞으면 그때 SKILL.md 본문 전체를 읽어 옵니다. 이것이 "쪽을 펼치는" 단계입니다. Skill 폴더 안에 reference.md나 examples.md 같은 지원 파일을 두고 본문에서 "자세한 형식은 examples.md 참고"라고 적어 두면, 그 파일은 실제로 필요할 때 한 번 더 열립니다. 세 단계 로딩입니다.

목차에도 예산이 있습니다. 공식 문서 기준으로 Skill 목록의 문자 예산은 모델 컨텍스트 윈도우의 1%에서 시작하며, 항목 하나의 description은 when_to_use와 합쳐 1,536자에서 잘립니다. 목록이 예산을 넘으면 가장 적게 호출된 Skill부터 설명이 줄어듭니다. /doctor를 실행하면 목록의 컨텍스트 비용 추정치와 가장 큰 기여자를 볼 수 있고, /context의 Skills 행은 예산 적용 후의 실제 크기를 보여 줍니다.

호출된 Skill의 본문은 그 세션 내내 컨텍스트에 남습니다. 그래서 공식 문서는 본문을 간결하게, "어떻게·왜"보다 "무엇을 할지"로 쓰라고 권합니다. 대화가 자동 압축될 때는 Skill마다 처음 5,000토큰이 다시 붙고, 다시 붙는 Skill 전체가 25,000토큰 예산을 나눠 씁니다.

Skill은 어떻게 생겼나

Skill 하나는 폴더입니다. 폴더 이름이 곧 /뒤에 입력하는 명령 이름이 되고, 안에 SKILL.md가 반드시 있어야 합니다. 나머지 파일은 선택입니다.

meeting-notes/
├── SKILL.md          # 필수. frontmatter + 지침
├── template.md       # 선택. Claude가 채울 양식
└── examples/
    └── sample.md     # 선택. 기대 출력 예시

SKILL.md는 위쪽 YAML frontmatter와 아래쪽 마크다운 본문으로 나뉩니다. 우리 8주 과정 1주차 실습인 "녹음을 회의록으로 바꾸기"를 Skill로 만들면 이렇게 됩니다.

---
name: meeting-notes
description: 녹음 전사 텍스트를 회의록 양식으로 정리합니다. 사용자가 "회의록 만들어", "전사본 정리", "녹음 정리" 라고 요청할 때 사용합니다.
---

전사 텍스트를 받으면 다음 순서로 정리합니다.

1. 참석자·일시·안건을 먼저 표로 뽑는다.
2. 결정 사항과 담당자, 기한을 번호 목록으로 쓴다.
3. 고객 실명은 홍OO 형태로 가린다.
4. 형식은 [template.md](template.md)를 따른다.

공식 문서 기준으로 frontmatter의 모든 필드는 선택이며 description만 권장됩니다. description을 빼면 본문 첫 문단이 대신 쓰입니다. name은 목록에 보이는 표시 이름이고 기본값은 폴더 이름입니다. 파일을 저장하면 재시작 없이 현재 세션에 반영됩니다. 다만 세션 시작 시 없던 최상위 skills 폴더를 새로 만든 경우에는 한 번 재시작해야 합니다.

Skill이 사는 위치는 네 곳입니다.

Windows에서는 ~가 C:\Users\<사용자> 폴더입니다. 같은 이름이 겹치면 조직이 개인을, 개인이 프로젝트를 덮습니다. 플러그인 Skill은 플러그인명:스킬명 네임스페이스라 충돌하지 않습니다.

CLAUDE.md·MCP와 무엇이 다른가

세 가지를 자주 섞어 부르는데, 역할이 다릅니다.

CLAUDE.md는 제1지침입니다. 원구연 과정 2주차에 "정책자금 컨설턴트다, 모든 문서는 존댓말로, 고객 실명은 홍OO으로" 같은 3줄로 시작하는 그 파일입니다. 세션마다 무조건 읽히므로 "언제나 참인 사실과 금지 규칙"을 둡니다. 절차를 여기에 쌓기 시작하면 위에서 말한 비용 문제가 생깁니다.

Skill은 절차서입니다. "회의록 정리 순서", "배포 절차", "채점 루프" 같은 다단계 작업을 담고, 필요할 때만 펼쳐집니다. 지원 파일과 스크립트를 함께 묶을 수 있다는 점도 CLAUDE.md와 다릅니다.

MCP는 도구 연결입니다. 6주차 교재의 비유로 CLI가 운전대라면 MCP는 내비게이션입니다. 노션·구글드라이브·데이터베이스처럼 Claude 바깥에 있는 데이터와 기능을 꽂아 주는 통로이지, 지식이나 절차를 담는 곳이 아닙니다. Skill 본문 안에서 "이 작업은 노션 MCP로 조회한다"라고 MCP를 지시할 수는 있습니다.

정리하면, CLAUDE.md는 "누구인가·무엇을 하지 않는가", Skill은 "어떤 순서로 하는가", MCP는 "무엇에 손이 닿는가"입니다.

어떤 일이 Skill이 되어야 하나

판단 기준은 세 가지면 충분합니다.

1. 세 번 이상 같은 설명을 했는가. 채팅에 같은 절차를 세 번 붙여 넣었다면 Skill 후보입니다.
2. 단계가 있는가. "빌드 확인, 커밋, 서버에서 pull, 재시작, 헬스체크"처럼 순서가 있으면 Skill입니다. 순서 없는 한 줄 규칙은 CLAUDE.md가 맞습니다.
3. 지금 작업과 무관할 때 읽힐 필요가 없는가. 배포 절차는 글쓰기 작업 중에 읽힐 이유가 없습니다. 그런 지식은 Skill로 빼서 컨텍스트를 아낍니다.

우리 팀이 실제로 쓰는 Skill 두 가지를 일반화해서 소개합니다. 하나는 채점 루프 Skill입니다. 만든 화면이나 문서를 레퍼런스와 나란히 놓고 다른 모델에게 0~100점으로 채점시킨 뒤, 지적 사항을 반영하고 다시 채점하기를 목표 점수까지 반복합니다. 캡처 방법, 채점 프롬프트 뼈대, "3회 중앙값으로 확정" 같은 수렴 규칙이 본문에 들어 있습니다. 다른 하나는 배포 Skill입니다. 운영 서버 주소, 빌드·재시작 순서, 실패 시 어느 로그의 어느 줄을 읽을지가 적혀 있습니다. 둘 다 사람이 매번 설명하기에는 길고, 매 세션 읽히기에는 무거운 지식입니다.

반대로 Skill로 만들지 말아야 할 것도 있습니다. "존댓말로 써라"처럼 항상 적용되는 규칙, 한 번만 할 일, 그리고 외부 서비스 연결 자체입니다.

플러그인으로 Skills 효과 체험하기

직접 만들기 전에 잘 만들어진 Skill이 무엇을 바꾸는지 보는 편이 빠릅니다. Anthropic 공식 마켓플레이스의 frontend-design 플러그인을 씁니다. 설명은 "일반적인 AI 미학을 피한, 구별되는 프로덕션급 프런트엔드 인터페이스를 생성한다"입니다.

플러그인이란

플러그인은 Skill·서브에이전트·훅·MCP 서버를 한 묶음으로 배포하는 단위입니다. 공식 문서 기준으로 .claude/에 직접 두는 독립 구성은 /hello처럼 짧은 이름을 쓰고 개인용에 맞고, 플러그인은 /플러그인명:hello처럼 네임스페이스가 붙는 대신 팀·커뮤니티 공유와 버전 관리에 맞습니다. 원구연 과정 2주차에 설치하는 OMC도 플러그인입니다.

설치 절차

공식 마켓플레이스 claude-plugins-official은 Claude Code를 처음 대화형으로 실행할 때 자동 등록됩니다. Claude Code 안에서 한 줄씩 입력합니다.

/plugin install frontend-design@claude-plugins-official
/reload-plugins

플러그인을 못 찾는다고 나오면 마켓플레이스가 오래된 것입니다. /plugin marketplace update claude-plugins-official을 먼저 실행합니다. 설치 화면에서는 범위를 고릅니다. 사용자 범위는 내 모든 프로젝트, 프로젝트 범위는 이 저장소의 모든 협업자, 로컬 범위는 이 저장소에서 나만입니다. macOS와 Windows 모두 같은 명령입니다.

비교 검증: 플러그인 유무로 어떻게 달라지나

"정지 규칙은 증거"라는 우리 원칙대로, 느낌이 아니라 결과물을 비교합니다.

1. 새 세션을 열고 플러그인 없이 요청합니다. "무료 특강 신청 페이지를 HTML 한 장으로 만들어 줘."
2. 결과 파일을 before.html로 저장합니다.
3. 플러그인을 설치하고 /reload-plugins 후 새 세션에서 같은 문장으로 요청합니다.
4. 결과를 after.html로 저장하고 브라우저에서 나란히 엽니다.

공식 문서도 Skill 평가는 새 세션에서 Skill 있음·없음을 기준선 비교하라고 권합니다. 세션을 새로 여는 이유는 앞선 대화의 잔여 컨텍스트가 차이를 가려 버리기 때문입니다. 보통 서체 선택, 색 팔레트, 여백 체계, 첫 화면 구성에서 차이가 납니다. 어느 쪽이 좋다고 느끼는지보다 "무엇이 달라졌는지"를 세 줄로 적어 두세요. 그 세 줄이 곧 여러분이 다음에 만들 Skill의 description 재료가 됩니다.

/skills 커맨드로 쓸 수 있는 Skills 확인하기

/skills를 입력하면 현재 세션에서 쓸 수 있는 Skill 목록이 뜹니다. 이름을 입력해 필터링할 수 있습니다. 어떤 Skill이 목차에서 자리를 많이 차지하는지 여기서 보입니다. 항목에서 Space를 누르면 "Claude에게 보임 / 이름만 / 사용자 메뉴만 / 끔"의 네 상태를 순환하고 Esc로 저장됩니다. 이 값은 .claude/settings.local.json의 skillOverrides에 기록됩니다. 플러그인 Skill은 여기서 끌 수 없고 /plugin에서 관리합니다.

정리

• Skill은 SKILL.md가 중심인 폴더이고, 목차(이름·설명)만 상시 로드되며 본문은 호출 시에만 읽힙니다.
• CLAUDE.md는 항상 참인 제1지침, Skill은 필요할 때 펼치는 절차서, MCP는 외부 연결입니다.
• 세 번 이상 반복 설명했고, 단계가 있고, 평소엔 읽힐 필요가 없는 지식이 Skill 후보입니다.
• frontend-design 플러그인으로 새 세션 전후 비교를 해 보면 Skill이 결과물을 어떻게 바꾸는지 눈으로 확인됩니다.
• /skills와 /doctor로 목록의 컨텍스트 비용을 주기적으로 점검합니다.

자주 묻는 질문