클로드코드 스킬 개념부터 팀공유까지
PR 리뷰·테스트 생성 자동화 실습
이 책은 Claude Code공식문서를 바탕으로 작성된 글입니다.
전제지식
터미널(macOS/Linux) 기본 조작
Git 기본 조작 (clone, commit, push)
Anthropic 계정(API 키 또는 Max/Pro 플랜)
⚠️ Windows 사용자 안내 본 교재의 동작 확인 기준 환경은 macOS입니다. Windows 사용자는 WSL2(Windows Subsystem for Linux) 환경을 설치한 후 진행하시면 대부분의 실습을 동일하게 따라하실 수 있습니다.
Skills란 무엇인가?
Claude Code Skills는 재사용 가능한 실행 절차를 SKILL.md라는 Markdown 파일로 정의하는 메커니즘입니다. 매번 같은 지시를 입력하는 대신, 한 번 Skill로 정의해 두면 슬래시 커맨드 하나로 호출할 수 있습니다.
일상적인 개발에서 "항상 같은 리뷰 관점으로 PR을 보고 있다", "테스트 작성 방식에 팀 규칙이 있다"는 상황을 떠올려 보세요. 이러한 것들을 구두나 사내 Wiki로 공유하는 것이 아니라, Claude가 직접 실행할 수 있는 형태로 정의하는 것이 Skills입니다.
�� 국내 활용 사례
- 사내 코딩 컨벤션 기반의 자동 코드 리뷰
- Confluence·Notion 양식에 맞는 기술 문서 자동 생성
- 장애 발생 시 사내 보고 양식에 맞는 인시던트 보고서 자동 생성
- Jira 티켓 내용을 기반으로 한 커밋 메시지 자동 생성
일반 프롬프트와의 차이점
슬래시 커맨드(commands)와의 차이점
Claude Code에는 .claude/commands/에 배치하는 "슬래시 커맨드"라는 유사한 메커니즘이 있습니다. 둘 다 /이름 형식으로 호출할 수 있어 혼동하기 쉽지만, 현재는 commands와 skills가 통합되어 있으며 .claude/commands/의 파일도 동일한 frontmatter를 지원합니다.
� 공식 문서 참고 공식 문서에서는 "commands와 skills는 통합되었다"고 명시하고 있습니다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 동일한 /deploy 커맨드가 됩니다. 기존 .claude/commands/ 파일은 그대로 동작합니다. Skills가 권장되는 이유는 보조 파일(examples/scripts)을 디렉터리로 묶어 관리할 수 있다는 점입니다.
구분 사용 기준:
"매번 직접 /를 입력해서 실행한다" → 슬래시 커맨드로 충분
"대화 흐름에서 자동으로 발화시키고 싶다", "도구 제한이나 보조 파일이 필요하다" → Skills
이 책에서는 Skills를 다룹니다. 슬래시 커맨드의 기본에 대해서는 블로그 입문편을 참고하세요.
칼럼: Agent Skills 오픈 스탠다드
Claude Code의 Skills는 Agent Skills라는 오픈 스탠다드를 준수합니다. 이는 여러 AI 도구 간에 공통 스킬 정의 형식을 정한 사양으로, Claude Code 고유의 기술이 아닙니다.
Claude Code는 이 오픈 스탠다드에 더해 아래의 독자 확장을 추가하고 있습니다:
호출 제어 (disable-model-invocation에 의한 자동 실행 비활성화)
서브에이전트 실행 (agent 필드에서의 위임)
동적 컨텍스트 주입 (!`command` 구문)
Skill 실행 방법은 2가지
1. 수동 실행 (슬래시 커맨드)
Claude Code 대화 중에 /skill-name을 입력하면 해당 Skill이 실행됩니다. name
필드가 그대로 슬래시 커맨드 이름이 됩니다.
> /pr-review
2. 자동 실행 (description 판정)
description 필드에 "언제 사용하는가"를 기술해 두면, 사용자의 지시 내용에 따라 Claude가 자동으로 해당 Skill을 선택·실행합니다.
description: "PR 리뷰를 요청받았을 때, 코드 품질·보안·성능 관점에서 리뷰한다"
Skill의 배치 위치와 스코프
Skill은 아래의 스코프로 배치할 수 있으며, 위에서부터 순서대로 우선순위가 높습니다.
동일한 이름의 Skill이 여러 스코프에 존재하는 경우, enterprise > personal > project 순으로 우선됩니다.
� 플러그인 스킬에 대하여 플러그인을 통해 제공되는 스킬은 plugin-name:skill-name 형식의 별도 네임스페이스로 관리되므로, 위의 우선순위와 충돌하지 않습니다.
파일 구성
Skill은 아래의 디렉터리 구조로 배치합니다.
.claude/skills/
pr-review/ # 폴더명 (Skill명과 동일하게 하는 것이 좋음)
SKILL.md # Skill 본체 (필수)
references/ # 참조용 문서
examples/ # 입출력 예시
scripts/ # 실행 스크립트
assets/ # 기타 보조 파일
SKILL.md가 유일한 필수 파일이며, 보조 디렉터리는 필요에 따라 추가합니다.
실습하기
1단계: 프로젝트 준비
먼저 일관 프로젝트용 디렉터리를 생성합니다.
mkdir -p ~/dev-workflow-skills
cd ~/dev-workflow-skills
git init
Skills를 배치할 디렉터리 구조를 만듭니다.
mkdir -p .claude/skills/pr-review
mkdir -p .claude/skills/test-gen
mkdir -p .claude/skills/doc-gen
예상 디렉터리 구조:
dev-workflow-skills/
.claude/
skills/
pr-review/
test-gen/
doc-gen/
2단계: 최소 Skill 작성 및 동작 확인
우선 가장 단순한 Skill을 작성하여 동작 원리를 체험합니다.
.claude/skills/pr-review/SKILL.md를 아래 내용으로 작성합니다.
---
name: pr-review
description: "PR 리뷰를 요청받았을 때"
---
# PR 리뷰
변경된 파일을 확인하고, 아래 관점에서 리뷰 코멘트를 출력하세요.
1. 코드의 정확성
2. 가독성
3. 개선 제안
3단계: Skill 동작 확인
프로젝트 디렉터리에서 Claude Code를 실행하여 Skill이 인식되는지 확인합니다.
cd ~/dev-workflow-skills
claude
Claude Code 대화 내에서 슬래시 커맨드로 실행해 봅니다.
> /pr-review
Skill이 올바르게 인식되면 SKILL.md의 내용에 기반한 응답이 반환됩니다.
인식되지 않는 경우 확인 항목:
파일 경로가 .claude/skills/pr-review/SKILL.md로 되어 있는가
frontmatter(---로 감싸인 부분)의 name이 올바르게 기재되어 있는가
Claude Code를 프로젝트(dev-workflow-skills)의 루트 디렉터리에서 실행하고 있는가
Skill 파일 작성 후 Claude Code를 실행했는가? (실행 후 파일을 추가한 경우 재시작이 필요할 수 있습니다)
�� 팁: 한글 파일명과 인코딩 SKILL.md 파일 내에 한글 내용을 작성하는 경우, 파일 인코딩이 UTF-8로 설정되어 있는지 반드시 확인하세요. VS Code에서는 우측 하단의 인코딩 표시를 클릭하여 확인하고 변경할 수 있습니다.
4단계: 3가지 Skill 요건 정리
앞으로 단계별로 완성해 나갈 3가지 Skill에 대해 요건을 정리합니다. 아래 표를 참고하여 설계 방침을 세워 두세요.
이 표는 다음 강부터 frontmatter 설계나 description 기술에 활용합니다.
5단계: 자동 실행 체험
앞서 작성한 pr-review Skill에는 description이 이미 설정되어 있습니다. 자동 실행이 어떻게 동작하는지 확인해 봅시다.
Claude Code 대화 내에서 슬래시 커맨드를 사용하지 않고 자연어로 요청합니다.
> 이 프로젝트의 코드 변경 사항을 리뷰해 줘
description의 내용과 사용자의 지시가 매칭되면, Claude가 자동으로 Skill을 선택하여 실행합니다.
� 참고 이 단계에서는 description이 간단하기 때문에 정확도가 낮을 수 있습니다. description 설계는 2장에서 자세히 학습합니다.
따라하기
Skill의 용도 판단 연습
test-gen과 doc-gen의 최소 Skill 작성
정리
Skills는 SKILL.md로 정의하는 재사용 가능한 실행 절차이며, 매번 수동 입력을 줄이고 팀 내에서 일관된 작업 품질을 실현하는 메커니즘
실행 방법은 "수동(슬래시 커맨드)"과 "자동(description 판정)" 2가지가 있으며, 용도에 맞게 구분하여 사용
Skill은 스코프(enterprise / personal / project)에 따라 배치 위치가 다르며, 우선순위가 있음 (플러그인은 별도 네임스페이스로 관리)
일관 프로젝트로서 "PR 리뷰", "테스트 생성", "문서 생성" 3가지 Skill을 단계별로 작성해 나감
©2024-2026 MDRules dev., Hand-crafted & made with Jaewoo Kim.
이메일문의: jaewoo@mdrules.dev
AI강의/개발/기술자문, AI 업무 자동화 컨설팅 문의: https://talk.naver.com/ct/w5umt5
AI 업무 자동화/에이전트/워크플로우설계 컨설팅/AI교육: https://mdrules.dev