클로드코드 스킬 만들기 — 반복 작업을 레시피로 저장하는 법

클로드코드 스킬은 자주 반복하는 작업 절차를 SKILL.md 파일 하나에 레시피처럼 저장해두고, 필요할 때 /스킬명으로 부르거나 Claude가 알아서 꺼내 쓰게 하는 기능입니다.

2026년 7월 기준으로, 같은 지시를 채팅에 반복해서 붙여넣고 있다면 그건 스킬로 만들 때가 됐다는 신호입니다.

이 글을 읽으면 스킬이 정확히 뭔지, CLAUDE.md 지침과 뭐가 다른지, 그리고 첫 스킬을 3단계로 직접 만드는 법까지 한 번에 정리됩니다.

CLAUDE.md는 늘 켜져 있는 규칙집이고, 스킬은 필요할 때 꺼내 쓰는 작업 레시피입니다. 반복되는 절차를 스킬로 옮기면 매번 설명하지 않아도 되고, 안 쓸 때는 컨텍스트도 거의 차지하지 않습니다.

스킬은 대체 뭔가

스킬은 Claude의 능력을 확장하는 방법입니다.

SKILL.md라는 파일에 "이런 상황에서는 이렇게 처리해라"를 적어두면, Claude가 그걸 자기 도구함에 추가합니다.

공식 문서(code.claude.com)는 스킬을 두고 Claude에게 새 레시피 한 장을 건네주는 것에 가깝다고 설명합니다.

단골식당에서 "늘 먹던 걸로"라고 말하는 상황을 떠올리면 쉽습니다.

주인이 그 말을 알아듣고 정해진 메뉴를 내오듯, Claude도 상황을 알아채고 저장해둔 절차를 그대로 실행합니다.

부르는 방법은 두 가지입니다.

하나는 사용자가 /스킬명을 직접 입력하는 수동 호출이고, 다른 하나는 Claude가 요청 내용을 보고 스스로 맞는 스킬을 꺼내 쓰는 자동 발동입니다.

정식 명칭은 "Agent Skills(에이전트 스킬)"이며, agentskills.io라는 오픈 표준을 따라 여러 AI 도구에서 호환됩니다.

CLAUDE.md 지침과 스킬은 뭐가 다른가

이 둘을 헷갈리는 사람이 많습니다.

가장 쉬운 구분법은 "항상 켜져 있어야 하는가"입니다.

CLAUDE.md는 프로젝트의 사실과 규칙을 담는 곳입니다.

주방 벽에 붙은 "우리 집 요리 규칙" 같은 것이라, 세션 내내 Claude의 머릿속에 상주합니다.

반면 스킬은 서랍 속 레시피 카드입니다.

그 요리를 할 때만 꺼내고, 안 쓸 때는 서랍에 들어가 있습니다.

공식 문서도 "CLAUDE.md의 한 섹션이 '사실'이 아니라 '절차'로 커졌다면 스킬로 옮기라"고 안내합니다.

구분	CLAUDE.md 지침	스킬(SKILL.md)
담는 것	늘 지켜야 할 사실·규칙	필요할 때 실행하는 절차·레시피
로드 시점	세션 시작부터 항상	발동될 때만
컨텍스트 비용	내용 전체가 항상 차지	쓰기 전엔 이름·설명만 차지
호출	자동(항상 적용)	자동 발동 + /스킬명 수동

여기서 스킬의 큰 장점이 하나 나옵니다.

공식 문서 표현으로 "CLAUDE.md 콘텐츠와 달리, 스킬 본문은 쓰일 때만 로드되므로 긴 참조 자료를 둬도 필요하기 전까지는 비용이 거의 들지 않는다"는 점입니다.

스킬을 아무리 많이 깔아도, 발동되기 전에는 이름과 설명만 차지합니다.

이런 방식을 "점진적 공개(progressive disclosure)"라고 부릅니다.

레시피 카드의 앞면(제목)만 보고 있다가, 그 요리를 실제로 할 때 뒷면(재료·순서)을 펼치는 구조라고 보면 됩니다.

선행 편인 CLAUDE.md 지침 글을 함께 읽으면, 무엇을 지침에 남기고 무엇을 스킬로 옮길지 감이 더 잡힙니다.

슬래시 커맨드랑 스킬은 다른 건가

결론부터 말하면, 예전엔 둘로 나뉘어 있었지만 지금은 커맨드가 스킬로 통합됐습니다.

공식 문서는 "커스텀 커맨드는 스킬로 통합되었다(merged into skills)"고 명시합니다.

.claude/commands/deploy.md 파일과 .claude/skills/deploy/SKILL.md 스킬은 둘 다 /deploy를 만들고 똑같이 작동합니다.

기존 .claude/commands/ 파일도 그대로 계속 작동하니 급히 옮길 필요는 없습니다.

다만 앞으로 새로 만든다면 공식 권장은 스킬 쪽입니다.

스킬은 보조 파일용 폴더를 가질 수 있고, 누가 호출할지 제어하는 설정이 있으며, Claude가 알아서 불러오는 자동 발동까지 되기 때문입니다.

같은 이름의 커맨드와 스킬이 동시에 있으면 스킬이 우선합니다.

커뮤니티 글 중에는 아직도 "둘은 별개"라고 설명하는 오래된 글이 있는데, 공식 문서 기준으로는 '통합됨'이 정답입니다.

개인적으로는 이 변화가 반갑습니다. 커맨드와 스킬을 언제 뭘 쓰는지 고민하던 게 사라졌고, 이제는 그냥 "스킬 하나 만든다"로 정리되니까요.

SKILL.md는 어떻게 생겼나

스킬 파일 하나는 크게 두 부분으로 이뤄집니다.

맨 위의 설정 영역(frontmatter)과, 그 아래 실제 지침을 적는 본문입니다.

설정 영역은 --- 두 줄 사이에 넣고, 여기에 name과 description을 씁니다.

이 중 실질적으로 중요한 건 description입니다.

name은 생략하면 폴더 이름을 대신 쓰기 때문에 없어도 되지만, description이 있어야 Claude가 "언제 이 스킬을 꺼낼지" 판단할 수 있습니다.

name은 최대 64자에 소문자·숫자·하이픈만 쓸 수 있고, "anthropic"이나 "claude"는 예약어라 쓸 수 없습니다.

---
name: meeting-notes
description: 회의록 원문을 받아 결정사항·할 일·담당자로 정리한다. 사용자가 회의록 정리·요약을 요청할 때 사용.
---

받은 회의록을 아래 형식으로 정리한다:
1. 핵심 결정사항 (불릿 3개 이내)
2. 할 일 목록 (담당자 + 기한)
3. 다음 회의 안건

위 예시는 개념을 보여주기 위해 각색한 것으로, 공식 예시 그대로는 아닙니다.

보다시피 코드가 한 줄도 없습니다.

스킬은 "AI에게 반복해서 시키던 지시"를 파일에 옮겨 적는 것이라, 비개발자도 만들 수 있습니다.

저장 위치는 두 가지를 기억하면 됩니다.

위치	경로	적용 범위
개인(전역)	~/.claude/skills/스킬명/SKILL.md	내 모든 프로젝트
프로젝트	.claude/skills/스킬명/SKILL.md	이 프로젝트만

첫 스킬을 3단계로 만들어보기

이론은 이쯤 하고, 실제로 하나 만들어봅니다.

공식 문서의 "첫 스킬 만들기" 예제를 따라, 커밋하지 않은 변경 내용을 요약해주는 작은 스킬을 만듭니다.

개발자가 아니어도 흐름만 보면 됩니다. 회의록 정리든 블로그 초안이든 원리는 똑같습니다.

1단계 — 스킬 폴더 만들기

먼저 스킬이 들어갈 폴더를 만듭니다.

mkdir -p ~/.claude/skills/summarize-changes

✅ 폴더 이름이 곧 명령어가 됩니다. 이 폴더를 만들면 나중에 /summarize-changes로 부를 수 있습니다.

2단계 — SKILL.md 작성하기

방금 만든 폴더 안에 SKILL.md 파일을 만들고 아래처럼 채웁니다.

---
description: 커밋하지 않은 변경을 요약하고 위험한 부분을 표시한다. 사용자가 무엇이 바뀌었는지 묻거나, 커밋 메시지를 원하거나, diff 검토를 요청할 때 사용.
---

## 현재 변경 내용

!`git diff HEAD`

## 지침

위 변경을 두세 개의 불릿으로 요약한 뒤, 위험 요소를 목록으로 정리한다.

여기서 !`git diff HEAD` 부분이 조금 특별합니다.

Claude가 파일을 읽기 전에 이 명령을 먼저 실행해서, 그 결과를 자리에 끼워 넣어줍니다.

실행 결과를 미리 넣어두는 기능이라고만 이해하면 충분합니다.

3단계 — 두 가지 방법으로 테스트하기

스킬이 제대로 작동하는지 두 가지로 확인합니다.

먼저 "내가 뭘 바꿨지?"처럼 description에 적은 상황에 맞는 말로 물어봅니다.

이때 Claude가 스킬을 스스로 꺼내 쓰면 자동 발동이 잘 되는 것입니다.

다음으로 /summarize-changes를 직접 입력해 수동 호출도 되는지 봅니다.

✅ 세션 중에 SKILL.md를 고치면 재시작 없이 바로 반영됩니다.

⚠️ 단, skills 폴더 자체를 처음 새로 만든 경우에는 한 번 재시작이 필요합니다.

스킬을 잘 쓰는 팁

스킬의 성패는 description을 얼마나 잘 쓰느냐에 크게 달렸습니다.

이게 바로 단골식당에서 "늘 먹던 걸로"를 알아듣는 귀에 해당합니다.

규칙은 간단합니다. "무엇을 하는지"와 "언제 쓰는지"를 둘 다 넣고, 사용자가 실제로 칠 법한 단어를 포함하는 것입니다.

예를 들어 "문서 관련 도움"처럼 뭉뚱그리면 Claude가 언제 꺼낼지 몰라 자동 발동이 흐려집니다.

"PDF에서 텍스트와 표를 추출하고 양식을 채운다. 사용자가 PDF나 양식을 언급할 때 사용" 정도로 구체적이어야 정확히 반응합니다.

본문은 짧게 쓰는 편이 좋습니다.

공식 권장은 500줄 이하이며, "Claude는 이미 똑똑하다"를 전제로 Claude가 모르는 것만 적으라고 안내합니다.

상세한 API 문서나 예제, 유틸리티는 scripts/나 references/ 폴더에 따로 두고 SKILL.md에서 링크만 걸면 됩니다.

스크립트는 실행된 뒤 결과만 컨텍스트에 들어가고 코드 본문은 들어가지 않아, 무거운 작업을 붙여도 부담이 적습니다.

이름은 processing-pdfs처럼 동작이 드러나는 형태가 좋고, helper·utils·tools 같은 모호한 이름은 피합니다.

남이 만든 스킬을 깔 때의 보안

스킬 생태계가 커지면서 "베스트 스킬 모음" 같은 큐레이션 글도 부쩍 늘었습니다.

편리한 만큼 조심할 지점도 생깁니다.

공식 문서는 "신뢰할 수 있는 출처의 스킬만 써라 — 직접 만든 것, 또는 Anthropic에서 받은 것"이라고 명확히 경고합니다.

스킬은 지침과 코드로 Claude에 새 능력을 주기 때문에, 악성 스킬은 겉보기 목적과 다르게 도구를 쓰거나 코드를 실행하도록 Claude를 유도할 수 있습니다.

그래서 남이 만든 스킬을 설치할 때는 소프트웨어를 하나 설치한다는 마음으로, SKILL.md와 scripts/ 안 파일을 반드시 열어봐야 합니다.

특히 외부 URL에서 데이터를 가져오는 스킬은 그 내용에 악성 지침이 섞일 수 있어 더 주의가 필요합니다.

이 위험을 더 깊게 다룬 내용은 AI 스킬 공급망 위험을 정리한 별도 글에서 이어집니다.

자주 묻는 질문

스킬은 자동으로 실행되나요?

description이 요청과 맞으면 Claude가 자동으로 발동합니다.

물론 /스킬명으로 직접 부를 수도 있습니다.

/deploy나 /commit처럼 타이밍을 사람이 통제해야 하는 스킬은 설정으로 자동 발동을 꺼서 수동 전용으로 만들 수도 있습니다.

CLAUDE.md에 다 적으면 안 되나요?

사실과 규칙이면 CLAUDE.md가 맞습니다.

하지만 여러 단계로 이뤄진 절차나 체크리스트라면 스킬이 낫습니다.

항상 켜둘 필요가 없어 토큰을 아끼고, 필요할 때만 정확히 불러올 수 있기 때문입니다.

비개발자도 만들 수 있나요?

네, 만들 수 있습니다.

스킬의 본질은 "AI에게 매번 반복해서 시키던 지시"를 파일 하나에 옮겨 적는 것입니다.

회의록 정리, 블로그 초안, 월간 실적 요약처럼 평소 말로 시키던 일을 그대로 적으면 됩니다.

정리하면

스킬은 반복 작업을 레시피로 저장해두는 기능이고, 필요할 때만 꺼내 쓰는 게 핵심입니다.

CLAUDE.md가 늘 켜진 규칙집이라면, 스킬은 서랍 속 레시피 카드입니다.

슬래시 커맨드와의 관계는 이제 "통합됨"으로 정리됐으니, 새로 만들 거라면 스킬로 시작하면 됩니다.

개인적으로는 스킬의 진짜 가치가 새로운 기능이 많아서가 아니라, 일하는 방식을 안정적으로 반복하게 해주는 데 있다고 봅니다.

거창하게 시작할 필요는 없습니다. 매번 비슷하게 시키던 일 하나부터 스킬로 옮겨보면 감이 옵니다.

스킬 공식 문서를 직접 보고 싶다면 아래에서 확인할 수 있습니다.

📄 클로드코드 스킬 공식 문서 보기 →

다음 편에서는 스킬보다 한 걸음 더 나아간 서브에이전트를 다룹니다.

하나의 작업을 여러 전문 에이전트에게 나눠 맡기는 방식이라, 스킬을 이해했다면 자연스럽게 이어집니다.

 

 

참고한 자료

Claude Code 공식 문서(Extend Claude with skills), Claude Platform의 Agent Skills overview와 best practices 문서, 그리고 Anthropic 엔지니어링 블로그(Equipping agents for the real world with Agent Skills)를 참고했습니다. 모델·기능 세부 사항은 발행 전 공식 문서 확인이 필요합니다.