Claude Code Skills 만드는 방법: 반복 프롬프트 자동화하기

Claude Code Skills는 코드 리뷰, CI 오류 분석, 릴리스 노트와 배포 전 점검처럼 반복해서 붙여 넣던 개발 프롬프트를 SKILL.md에 저장해 재사용하는 기능입니다. Claude가 설명을 보고 필요한 순간에 불러오거나 사용자가 /스킬이름으로 직접 실행할 수 있습니다. 단순 문장 저장보다 입력·순서·실패 조건·완료 보고를 검증 가능한 절차로 만드는 것이 핵심입니다.

Claude Code Skills란 무엇인가

Skill은 Claude Code가 필요할 때 불러오는 지침, 지식과 반복 워크플로 묶음입니다. 각 Skill은 폴더 안의 SKILL.md를 시작점으로 하며 템플릿, 예제, 참고 문서와 실행 스크립트를 함께 둘 수 있습니다. Skill 본문은 사용할 때만 로드되므로 모든 절차를 CLAUDE.md에 넣는 것보다 기본 문맥을 작게 유지하기 쉽습니다.

Claude Code는 Skill의 description과 현재 요청을 비교해 자동으로 선택할 수 있고, 사용자가 /skill-name 형태로 명시적으로 실행할 수도 있습니다. 기존 .claude/commands/의 사용자 명령은 계속 작동하지만 공식 문서는 지원 파일과 호출 제어가 가능한 Skills 사용을 권장합니다.

Claude 웹 Skills와 Claude Code Skills 차이

보고서·스프레드시트 등 Claude 앱의 기능을 찾는다면 Claude Skills 반복 업무 가이드를 참고하세요. 이번 글은 저장소 안에서 사용하는 Claude Code 전용 Skill 제작에 초점을 맞춥니다.

CLAUDE.md·Skills·Hooks·Subagent 차이

“모든 코드에서 pnpm을 쓴다”는 CLAUDE.md, “PR을 이 체크리스트로 검토한다”는 Skill, “파일 수정 뒤 포맷 검사를 항상 실행한다”는 Hook이 적합합니다.

Skill로 만들기 좋은 반복 프롬프트

• 변경 내용을 위험·테스트·사용자 영향으로 요약하는 PR 리뷰
• CI 로그에서 최초 실패와 재현 명령을 찾는 오류 분석
• 커밋 목록을 사용자 중심 릴리스 노트로 바꾸는 절차
• API 변경에서 호환성·권한·문서 누락을 검사하는 체크리스트
• React 화면의 로딩·빈 상태·오류·모바일·접근성 검토
• Java 서비스의 트랜잭션·예외·데이터 마이그레이션 점검
• 장애 로그와 배포 기록으로 타임라인을 만드는 작업

한 번만 쓰는 요청이나 대화 맥락에 강하게 의존하는 작업은 일반 프롬프트가 낫습니다. 판정 기준이 계속 바뀌는 업무를 너무 일찍 Skill로 고정하면 오래된 자동화가 반복될 수 있습니다.

프로젝트 Skill 폴더 만들기

mkdir -p .claude/skills/review-changes

다음 구조처럼 SKILL.md만 필수이며 나머지는 필요할 때 추가합니다.

.claude/skills/review-changes/
├── SKILL.md
├── checklist.md
├── examples/
│   └── good-review.md
└── scripts/
    └── collect-changes.sh

프로젝트 Skill은 저장소에 커밋해 팀과 공유할 수 있습니다. 외부 스크립트, 네트워크 호출과 도구 권한이 포함되면 일반 코드와 같은 리뷰·테스트·버전 관리가 필요합니다.

개인 Skill과 프로젝트 Skill 저장 위치

같은 이름이 여러 범위에 있으면 우선순위 때문에 예상과 다른 Skill이 선택될 수 있습니다. 이름에 역할과 결과를 드러내고 프로젝트에서 /이름을 실행해 실제 내용을 확인하세요.

SKILL.md 기본 작성법

---
name: review-changes
description: 현재 코드 변경에서 회귀, 테스트 누락과 사용자 영향을 검토할 때 사용합니다.
---

# 변경 검토 절차

1. 변경 파일과 목적을 확인한다.
2. 공개 API, 데이터와 권한 영향을 찾는다.
3. 정상·오류·경계 조건 테스트를 확인한다.
4. 근거가 있는 문제만 파일 경로와 함께 보고한다.

# 결과 형식

- 핵심 변경 요약
- 우선순위별 위험과 근거
- 누락된 테스트
- 실행한 명령과 결과
- 남은 미확인 사항

YAML 구분자인 ---와 파일 이름의 대소문자를 정확히 지키세요. description은 Claude가 자동 호출 여부를 판단하는 핵심 정보이므로 기능 자랑보다 사용 조건을 구체적으로 작성하는 편이 좋습니다.

좋은 description 작성 공식

description에는 ‘무엇을 처리하는지’, ‘언제 호출하는지’, ‘어떤 결과를 내는지’를 담습니다.

너무 넓은 description은 관련 없는 요청에도 Skill을 불러올 수 있고, 지나치게 좁으면 표현이 조금만 달라도 자동 호출되지 않습니다. 실제 사용자가 말할 법한 요청 5개와 호출되면 안 되는 요청 5개로 시험하세요.

반복 프롬프트를 Skill로 바꾸는 6단계

1. 두 번 이상 반복한 프롬프트에서 바뀌는 입력과 고정 절차를 분리합니다.
2. 좋은 결과를 판단하는 체크리스트와 금지 동작을 적습니다.
3. 한 Skill이 하나의 명확한 결과를 만들도록 범위를 줄입니다.
4. SKILL.md에는 핵심 절차만 두고 긴 자료는 지원 파일로 나눕니다.
5. 직접 호출로 정상·실패·빈 입력을 시험합니다.
6. 자동 호출을 허용한 뒤 오호출과 누락을 기록해 description을 수정합니다.

/skill-name으로 직접 호출하기

Skill 폴더 이름이 review-changes라면 다음처럼 직접 실행할 수 있습니다.

/review-changes

인자를 받는 Skill은 $ARGUMENTS를 본문에 넣을 수 있습니다.

---
name: explain-module
description: 지정한 모듈의 실행 흐름과 의존성을 설명할 때 사용합니다.
---

$ARGUMENTS 모듈을 조사한다.
진입점, 주요 호출 순서, 외부 의존성과 테스트 위치를 파일 경로와 함께 설명한다.

호출 예시는 /explain-module src/auth입니다. 인자를 파일 경로나 셸 명령에 그대로 이어 붙이지 말고 허용 범위와 입력 형식을 검증하세요.

자동 호출을 끄고 수동으로만 사용하기

배포, 데이터 변경과 비용이 발생하는 작업은 Claude가 문맥만 보고 자동 실행하지 않도록 설정하는 편이 안전합니다.

---
name: prepare-release
description: 검증된 릴리스 후보의 변경 목록과 배포 체크리스트를 준비합니다.
disable-model-invocation: true
---

disable-model-invocation: true를 사용하면 사용자가 직접 호출하는 흐름에 맞출 수 있습니다. 그래도 Skill 안에서 실행되는 명령과 외부 쓰기 작업에는 기존 Claude Code 권한과 사람 승인을 유지해야 합니다.

지원 파일로 SKILL.md 짧게 유지하기

공식 문서는 SKILL.md를 500줄 이내로 유지하고 긴 API 문서, 예시와 템플릿을 별도 파일로 나누는 방식을 안내합니다.

## 필요한 자료

- 검토 기준은 [checklist.md](checklist.md)를 읽는다.
- 출력 형식은 [examples/good-review.md](examples/good-review.md)를 따른다.
- 변경 수집이 필요할 때만 scripts/collect-changes.sh를 사용한다.

지원 파일이 있다는 사실만으로 Claude가 언제 읽어야 하는지 알 수 있는 것은 아닙니다. SKILL.md에 파일의 목적과 읽는 조건을 명시하고 더 이상 쓰지 않는 자료는 제거하세요.

동적 문맥 주입 사용법

Claude Code Skills는 !`명령` 형식으로 Skill 내용이 전달되기 전에 명령 결과를 주입할 수 있습니다. 예를 들어 현재 diff를 요약하는 Skill은 Git 결과를 문맥에 포함할 수 있습니다.

## 현재 변경

!`git diff --stat HEAD`

## 지침

변경 파일의 범위를 요약하고 위험도가 높은 영역부터 검토한다.

이 명령은 Claude가 내용을 보기 전에 실행됩니다. 인터넷에서 받은 Skill의 동적 명령을 검토하지 않고 실행하면 파일 읽기, 네트워크 전송이나 위험한 셸 동작이 발생할 수 있습니다. 처음에는 읽기 전용 Git 명령으로 시작하고 출력 크기와 오류도 제한하세요.

${CLAUDE_SKILL_DIR}로 스크립트 경로 고정하기

Skill 폴더에 포함된 스크립트를 현재 작업 디렉터리와 무관하게 찾으려면 ${CLAUDE_SKILL_DIR}을 사용할 수 있습니다.

필요한 입력을 확인한 뒤 다음 검증 스크립트를 실행한다.

${CLAUDE_SKILL_DIR}/scripts/validate.sh

스크립트 실행 권한, 운영체제 호환성, 입력값 인용과 오류 처리를 확인하세요. 비밀값을 인자로 전달하면 프로세스 목록이나 로그에 노출될 수 있으므로 승인된 환경 변수와 시크릿 관리 방법을 사용해야 합니다.

context: fork로 별도 문맥에서 실행하기

긴 코드 조사가 주 대화 문맥을 차지하지 않게 하려면 Skill을 Subagent 문맥에서 실행할 수 있습니다.

---
name: research-module
description: 큰 모듈의 구조와 위험을 읽기 전용으로 조사할 때 사용합니다.
context: fork
agent: Explore
---

$ARGUMENTS 범위를 조사한다.
관련 파일, 호출 관계, 테스트와 미확인 위험을 근거와 함께 요약한다.

context: fork는 Skill 본문 자체가 수행할 과제를 포함할 때 적합합니다. 단순 코딩 규칙만 넣으면 새 문맥에서 무엇을 해야 하는지 없어 의미 있는 결과가 나오지 않을 수 있습니다. 자세한 병렬 활용법은 Claude Code Subagent 가이드에서 확인할 수 있습니다.

코드 리뷰 Skill 실전 예시

Skill의 결과를 바로 버그로 확정하지 말고 실패 테스트나 실행 경로로 재현하세요. 포맷·lint처럼 기계적인 검사는 Skill 설명보다 CI와 Hook으로 실행하는 것이 더 일관됩니다.

CI 오류 분석 Skill 실전 예시

1. 실패한 작업 이름과 실행 환경을 확인합니다.
2. 연쇄 오류보다 최초 실패를 찾습니다.
3. 관련 파일과 최근 변경을 연결합니다.
4. 로컬에서 실행 가능한 최소 재현 명령을 제시합니다.
5. 원인, 가설, 확인된 사실을 구분합니다.
6. 실행하지 못한 검증과 필요한 추가 로그를 적습니다.

긴 로그를 SKILL.md에 직접 넣지 말고 호출 시 인자, 파일 또는 별도 Subagent로 전달하세요. 고객 정보, 토큰과 내부 URL은 분석 전에 제거해야 합니다.

Skill 호출 테스트 5종

Skill이 보이지 않을 때

• 폴더가 .claude/skills/이름/SKILL.md 구조인지 확인합니다.
• SKILL.md의 대소문자와 YAML 구분선을 점검합니다.
• 현재 프로젝트 또는 사용자 범위가 맞는지 봅니다.
• 같은 이름의 command·personal·managed Skill 충돌을 확인합니다.
• 세션 시작 뒤 처음으로 최상위 skills 폴더를 만들었다면 Claude Code를 다시 시작합니다.
• SDK에서는 project·user setting source와 skills 옵션이 활성화됐는지 확인합니다.

Claude Code는 기존 skills 디렉터리의 파일 변경을 현재 세션에서 감지할 수 있지만, 세션 시작 당시 최상위 디렉터리 자체가 없었다면 재시작이 필요할 수 있습니다.

Skill이 너무 자주 호출될 때

1. description에서 “모든 개발 작업” 같은 넓은 표현을 제거합니다.
2. 입력 유형과 결과물을 구체적으로 제한합니다.
3. 다른 Skill과 겹치는 트리거 표현을 비교합니다.
4. 자동 실행이 위험하면 disable-model-invocation: true를 사용합니다.
5. 대표 요청과 비호출 요청을 회귀 테스트 목록으로 관리합니다.

Hooks·MCP·Subagent와 조합하기

Skill은 작업 절차, Hooks는 정해진 이벤트의 자동 검사, MCP는 외부 도구 연결을 담당합니다. 예를 들어 장애 분석 Skill이 모니터링 MCP에서 읽기 전용 데이터를 가져오고, 종료 Hook이 결과 형식을 검사하도록 나눌 수 있습니다.

기능을 많이 결합할수록 권한과 실패 지점도 늘어납니다. 처음에는 순수 지침 Skill로 품질을 확인한 뒤 지원 파일, 읽기 전용 명령, Subagent, MCP와 Hook을 한 단계씩 추가하세요.

외부 Skill 보안 체크리스트

• SKILL.md와 모든 지원 파일을 직접 읽었는가
• 동적 문맥의 셸 명령이 읽기·쓰기·네트워크 중 무엇을 하는가
• scripts의 입력값 검증과 경로 제한이 있는가
• MCP·Subagent·Hook으로 추가되는 권한을 확인했는가
• 비밀정보와 고객 데이터가 출력·로그에 포함되지 않는가
• 삭제·배포·외부 쓰기에 사람 승인이 유지되는가
• 플러그인 업데이트 후 변경된 Skill을 다시 검토하는가

팀에서 유지하는 방법

1. 한 가지 반복 업무와 한 명의 관리 책임자를 정합니다.
2. 좋은 결과·실패 결과와 입력 예제를 함께 저장합니다.
3. Skill 변경을 코드 리뷰하고 버전 이력을 남깁니다.
4. 실제 호출률, 오호출, 수정 시간과 실패 원인을 기록합니다.
5. 프로젝트 명령·디렉터리 구조가 바뀌면 Skill도 함께 수정합니다.
6. 분기마다 중복·미사용 Skill과 오래된 참고 자료를 삭제합니다.

Skill 도입 전후 기록표

동일한 입력 5개를 기존 반복 프롬프트와 Skill에 각각 적용하세요. 결과가 일정해졌는지 다음 기준으로 직접 평가할 수 있습니다.

편집부 결론

Claude Code Skills로 반복 프롬프트를 자동화할 때 가장 중요한 것은 긴 프롬프트를 저장하는 일이 아니라 팀의 판단 절차를 재현 가능하게 만드는 것입니다. 한 업무의 입력, 순서, 실패 조건, 검증 명령과 결과 형식을 SKILL.md에 고정하고 수동 호출부터 시험하세요. 자동 호출과 외부 명령은 품질과 안전성이 확인된 뒤 단계적으로 여는 편이 좋습니다.

이 글은 2026년 9월 6일 Anthropic 공식 문서를 분석해 작성했으며 특정 팀에서 Skills 도입 전후의 생산성을 장기간 측정한 후기는 아닙니다. frontmatter 옵션과 내장 Skill은 변경될 수 있으므로 적용 직전 최신 공식 문서와 현재 Claude Code 버전을 확인하세요.

공식 문서와 함께 읽을 글

Claude Code Skills 공식 문서 보기

Claude Code Skills 모범 사례 확인하기

Claude Code CLAUDE.md에 프로젝트 공통 규칙 설정하기

Skills·Hooks·MCP를 Claude Code Plugin으로 묶어 배포하기

Claude Code Hooks로 반복 검사 자동화하기

Claude Code Skills를 Subagent에서 실행하기

Claude Code Skills에 MCP 외부 도구 연결하기

Claude 웹·앱 Skills로 문서 반복 업무 만들기

Codex Skills 제작 방식과 비교하기

자주 묻는 질문

Claude Code Skill은 어디에 만드나요?

프로젝트 전용은 .claude/skills/이름/SKILL.md, 모든 프로젝트에서 사용할 개인 Skill은 ~/.claude/skills/이름/SKILL.md에 만듭니다.

Claude Code Skill을 어떻게 실행하나요?

Claude가 description과 요청을 보고 자동 선택하거나 사용자가 /skill-name으로 직접 호출할 수 있습니다.

SKILL.md에 반드시 필요한 내용은 무엇인가요?

YAML frontmatter와 실행 지침이 필요합니다. description에는 호출 조건을, 본문에는 입력, 단계, 실패 처리, 검증과 결과 형식을 구체적으로 작성하는 것이 좋습니다.

반복 프롬프트를 그대로 SKILL.md에 붙여 넣어도 되나요?

시작은 가능하지만 바뀌는 입력을 분리하고 완료 기준, 예외, 금지 동작과 결과 형식을 추가해야 재사용 품질이 높아집니다.

Claude Code Skill의 자동 호출을 끌 수 있나요?

disable-model-invocation: true를 설정해 사용자가 직접 호출하는 작업으로 제한할 수 있습니다. 배포와 외부 쓰기처럼 위험한 절차에 적합합니다.

Skill 안에서 셸 명령을 실행할 수 있나요?

동적 문맥 주입과 실행 스크립트를 활용할 수 있습니다. 명령은 Claude가 내용을 보기 전에 실행될 수도 있으므로 외부 Skill의 코드, 경로, 네트워크와 비밀정보 접근을 먼저 검토하세요.

Claude Code Skill과 Hook은 무엇이 다른가요?

Skill은 필요할 때 불러오는 지식과 업무 절차이고 Hook은 파일 수정, 도구 호출과 작업 종료 같은 정해진 이벤트에 자동 실행됩니다.

Skill을 별도 Subagent에서 실행할 수 있나요?

Skill frontmatter에 context: fork와 실행할 agent를 지정할 수 있습니다. Skill 본문에 Subagent가 수행할 명확한 과제가 포함되어야 합니다.