Skills로 반복 작업 자동화 하기

들어가며

Claude Code를 사용하다 보면 같은 형태의 지시를 반복하게 되는 경우가 많습니다. "이 코드 리뷰해줘", "커밋 메시지 작성해줘", "이 이슈 해결해줘" 등 매번 비슷한 맥락을 설명하는 것은 비효율적입니다. Claude Code의 Skills(커스텀 슬래시 커맨드)를 활용하면, 자주 사용하는 워크플로우를 한번 정의해두고 /skill-name으로 즉시 호출할 수 있습니다.

이번 포스팅에서는 Skills의 개념, 생성 방법, 실전 활용 예시, 그리고 CLAUDE.md와의 차이점까지 다뤄보겠습니다.

Skills란?

Skills는 재사용 가능한 지시 세트를 마크다운 파일로 정의한 것입니다. 한번 작성해두면 /skill-name 형태로 호출하거나, Claude가 대화 맥락에 따라 자동으로 적용할 수도 있습니다.

Skills는 Agent Skills에 정리된 사양을 따르기 때문에, Claude Code에만 종속되지 않고 다른 AI 도구에서도 호환 가능합니다.

파일 구조

각 Skill은 디렉토리 단위로 관리되며 SKILL.md가 핵심 파일입니다.

.claude/skills/my-skill/
├── SKILL.md           # 메인 지시 파일 (필수)
├── template.md        # Claude가 채울 템플릿 (선택)
├── examples/          # 예시 출력 (선택)
└── scripts/           # 실행 가능한 스크립트 (선택)

SKILL.md 작성법

SKILL.md는 YAML frontmatter와 마크다운 본문 두 부분으로 구성됩니다.

// frontmatter
---
name: review
description: 코드 품질, 보안, 성능을 리뷰합니다
disable-model-invocation: true
allowed-tools: Read, Grep, Glob
---

// content
$ARGUMENTS에 해당하는 코드를 리뷰해주세요:

1. 보안 취약점 확인
2. 성능 병목 분석
3. 코드 가독성 검토
4. 개선 사항 제안

주요 frontmatter 옵션

필드	설명
name	슬래시 커맨드 이름 (예: review → /review)
description	Skill의 설명. Claude가 자동 호출 시 이 설명을 참고합니다
disable-model-invocation	true면 사용자만 호출 가능 (배포, 커밋 등 부작용 있는 작업에 권장)
user-invocable	false면 / 메뉴에서 숨김 (배경 지식용)
allowed-tools	Skill 실행 시 사용 가능한 도구 제한
context	fork로 설정하면 별도 서브에이전트에서 실행
argument-hint	자동완성 시 표시되는 인수 힌트 (예: [issue-number])

frontmatter를 잘 작성해야 하는 이유

Claude는 Skill을 호출할지 판단할 때 frontmatter의 description만 읽고 결정합니다. 본문(마크다운 body)은 실제로 Skill이 호출되기 전까지 로딩하지 않습니다.

즉, 세션이 시작되면 등록된 모든 Skill의 frontmatter(약 100토큰)만 컨텍스트에 올라가고, 본문은 호출 시점에 로딩됩니다. 이 구조 덕분에 Skill이 아무리 많아도 평소에는 토큰을 거의 소모하지 않습니다.

반대로 말하면, description이 부실하면 Claude가 적절한 상황에서도 해당 Skill을 호출하지 못합니다. 예를 들어 description: 리뷰라고만 적으면 코드 리뷰인지, PR 리뷰인지, 디자인 리뷰인지 구분할 수 없습니다.

좋은 description 예시:

# Bad
description: 리뷰

# Good
description: 코드 변경사항의 보안 취약점, 성능 병목, 가독성을 리뷰합니다. 코드 리뷰가 필요할 때 사용합니다.

description에 Skill이 하는 일과 언제 사용해야 하는지를 함께 적으면, Claude가 대화 맥락만 보고도 정확하게 자동 호출할 수 있습니다.

변수 활용

Skills에서는 호출 시 전달된 인수를 변수로 사용할 수 있습니다.

변수	설명
$ARGUMENTS	전달된 모든 인수
$0, $1, $2	위치별 인수 (0부터 시작)

예를 들어 프레임워크 마이그레이션 Skill을 만든다면:

---
name: migrate-component
description: 컴포넌트를 다른 프레임워크로 마이그레이션합니다
---
$0 컴포넌트를 $1에서 $2로 마이그레이션해주세요.
기존 동작과 테스트를 모두 유지해야 합니다.

실제 예제로는 다음과 같이 사용할 수 있습니다. /migrate-component SearchBar React Vue

동적 컨텍스트 주입

!`command` 문법을 사용하면 셸 명령어의 출력을 Skill 내용에 주입할 수 있습니다.

---
name: pr-summary
description: PR 변경사항을 요약합니다
context: fork
---

## PR 컨텍스트
- PR diff: !`gh pr diff`
- 변경 파일: !`gh pr diff --name-only`

위 내용을 기반으로 PR을 요약해주세요.

이렇게 하면 Claude는 셸 명령어가 아닌, 실제 실행 결과를 받아서 작업합니다.

적용 범위

Skills는 위치에 따라 적용 범위가 달라집니다.

위치	경로	범위
개인	~/.claude/skills/<name>/SKILL.md	모든 프로젝트
프로젝트	.claude/skills/<name>/SKILL.md	해당 프로젝트만

프로젝트 레벨 Skills는 .claude/skills/ 디렉토리를 git에 커밋하면 팀 전체가 동일한 워크플로우를 공유할 수 있습니다.

CLAUDE.md와의 차이점

	CLAUDE.md	Skills
로딩	매 세션 자동 로딩	호출 시 또는 자동 감지 시 로딩
용도	프로젝트 규칙, 코딩 컨벤션	특정 워크플로우, 도구
인수	지원 안함	$ARGUMENTS, $0 등 지원
도구 제한	불가	allowed-tools로 제한 가능
서브에이전트	불가	context: fork로 격리 실행 가능

정리하면, CLAUDE.md는 프로젝트의 규칙과 정체성을 정의하고, Skills는 프로젝트의 기능과 워크플로우를 정의한다고 생각하면 됩니다.

실전 예시

1. 커밋 Skill

---
name: commit
description: 컨벤션에 맞는 커밋을 생성합니다
disable-model-invocation: true
---

커밋 전 변경사항을 확인하고:
- TODO, FIXME 주석이 남아있지 않은지
- console.log 등 디버깅 코드가 없는지
- 주석 처리된 코드가 없는지

문제가 없다면 프로젝트 커밋 컨벤션에 맞춰 커밋을 생성해주세요.
메시지: $ARGUMENTS

2. GitHub 이슈 해결 Skill

---
name: fix-issue
description: GitHub 이슈를 분석하고 해결합니다
disable-model-invocation: true
argument-hint: [issue-number]
---

GitHub 이슈 #$0을 해결해주세요:
1. 이슈 내용을 읽고 요구사항 파악
2. 관련 코드 탐색
3. 수정 구현
4. 테스트 작성
5. 커밋 생성

사용법: /fix-issue 42

3. 읽기 전용 탐색 Skill

---
name: explore
description: 코드베이스를 읽기 전용으로 탐색합니다
allowed-tools: Read, Grep, Glob
---
$ARGUMENTS에 대해 코드베이스를 탐색하고 분석 결과를 알려주세요.
코드를 수정하지 말고 읽기만 해주세요.

작성 시 팁

• SKILL.md는 500줄 이내로 유지하고, 상세 내용은 별도 파일로 분리하세요.
• 부작용이 있는 작업(배포, 커밋, 메시지 전송)은 반드시 disable-model-invocation: true를 설정하세요.
• description을 구체적으로 작성하면 Claude가 대화 맥락에 맞춰 자동으로 Skill을 적용합니다.
• context: fork 를 활용하면 무거운 분석 작업을 메인 대화 컨텍스트와 분리할 수 있습니다.

마치며

Skills는 Claude Code를 단순한 AI 코딩 도구가 아닌, 팀의 워크플로우를 자동화하는 도구로 확장시켜 줍니다. CLAUDE.md로 프로젝트의 규칙을 정의하고, Skills로 반복 작업을 자동화하면 개발 생산성을 크게 높일 수 있습니다.