Claude Code Skills

• Claude Code의 기능을 확장하는 커스텀 명령어 시스템
• SKILL.md 파일에 지시사항을 작성하면, Claude가 자동으로 도구로 인식
• 상황에 맞게 Claude가 자동 호출하거나, 사용자가 /skill-name으로 직접 호출
• Agent Skills 오픈 스탠다드를 따르며, 여러 AI 도구에서 호환

해당 개념이 필요한 이유

• 반복 작업 자동화: 커밋, 배포, PR 생성 등 반복적인 워크플로우를 한 번 정의하고 재사용
• 팀 컨벤션 공유: 프로젝트 스킬을 Git에 커밋하면 팀 전체가 동일한 워크플로우 사용
• Claude의 맥락 확장: 도메인 지식, API 패턴, 코딩 규칙 등을 스킬로 정의하여 Claude가 자동으로 참조
• 안전한 실행 제어: 누가 언제 스킬을 호출할 수 있는지 세밀하게 제어 가능

AS-IS

# 매번 수동으로 동일한 지시를 반복 입력
User: "이 PR 리뷰해줘. 코드 스타일 확인하고,
       보안 취약점 체크하고, 테스트 커버리지도 봐줘.
       결과는 체크리스트 형태로..."

# 다음 번에도 동일한 내용을 또 입력
User: "이 PR 리뷰해줘. 코드 스타일 확인하고..."

TO-BE

# .claude/skills/review-pr/SKILL.md (한 번만 정의)
---
name: review-pr
description: PR을 코드 스타일, 보안, 테스트 관점에서 리뷰
---
PR $ARGUMENTS를 다음 관점에서 리뷰하라:
1. 코드 스타일 및 컨벤션
2. 보안 취약점
3. 테스트 커버리지
결과는 체크리스트 형태로 출력.

# 이후에는 한 줄이면 끝
/review-pr 123

스킬 파일 구조

모든 스킬은 디렉토리 단위로 구성되며, SKILL.md가 진입점(entrypoint)이다:

my-skill/
├── SKILL.md           # 메인 지시사항 (필수)
├── template.md        # Claude가 채울 템플릿
├── examples/
│   └── sample.md      # 기대 출력 예시
├── references/
│   └── api-docs.md    # 상세 참조 문서
└── scripts/
    └── helper.py      # Claude가 실행할 스크립트

SKILL.md는 500줄 이하를 권장하며, 상세 내용은 별도 파일로 분리한다.

SKILL.md 작성법

SKILL.md는 두 부분으로 구성된다:

1. YAML Frontmatter (--- 사이): 스킬의 메타데이터와 동작 설정
2. Markdown Content: Claude가 따를 지시사항

---
name: fix-issue
description: GitHub 이슈를 수정한다
disable-model-invocation: true
allowed-tools: Read, Grep, Bash
---
 
GitHub 이슈 $ARGUMENTS를 수정하라:
1. 이슈 설명 읽기
2. 요구사항 파악
3. 수정 구현
4. 테스트 작성
5. 커밋 생성

Frontmatter 필드 레퍼런스

필드	필수	설명
name	No	스킬 이름 (= slash command명). 생략 시 디렉토리명 사용
description	권장	스킬 용도. Claude가 자동 호출 판단에 사용
argument-hint	No	자동완성 시 표시할 인수 힌트 (예: [issue-number])
disable-model-invocation	No	true: Claude 자동 호출 차단, 사용자만 /name으로 호출
user-invocable	No	false: / 메뉴에서 숨김. Claude만 자동 호출 가능
allowed-tools	No	스킬 활성 시 승인 없이 사용 가능한 도구 목록
model	No	스킬 실행 시 사용할 모델
context	No	fork: 격리된 subagent 컨텍스트에서 실행
agent	No	context: fork 시 사용할 subagent 유형
Hooks	No	스킬 라이프사이클에 스코핑된 훅

스킬 저장 위치와 적용 범위

위치	경로	적용 범위
Enterprise	Managed settings	조직 전체
Personal	~/.claude/skills/<name>/SKILL.md	내 모든 프로젝트
Project	.claude/skills/<name>/SKILL.md	해당 프로젝트만
Plugins	<plugin>/skills/<name>/SKILL.md	플러그인 활성화된 곳

우선순위: Enterprise > Personal > Project. 동명 스킬은 상위가 우선.

모노레포에서는 하위 디렉토리의 .claude/skills/도 자동 탐색된다.

호출 제어 매트릭스

Frontmatter 설정	사용자 호출	Claude 자동 호출	컨텍스트 로딩
(기본값)	O	O	description 항상 로드, 호출 시 전체 로드
disable-model-invocation: true	O	X	컨텍스트에 미포함
user-invocable: false	X	O	description 항상 로드, 호출 시 전체 로드

스킬 콘텐츠의 두 가지 유형

Reference 스킬 (지식 주입형)

현재 작업에 적용할 지식을 제공한다. 컨벤션, 패턴, 스타일 가이드 등.

---
name: api-conventions
description: 이 코드베이스의 API 설계 패턴
---
API 엔드포인트 작성 시:
- RESTful 네이밍 규칙 사용
- 일관된 에러 형식 반환
- 요청 유효성 검사 포함

Task 스킬 (작업 실행형)

특정 작업의 단계별 지시사항을 제공한다. 배포, 커밋, 코드 생성 등.

---
name: deploy
description: 프로덕션 배포
disable-model-invocation: true
context: fork
---
배포 수행:
1. 테스트 스위트 실행
2. 애플리케이션 빌드
3. 배포 타겟에 푸시

문자열 치환 (String Substitution)

스킬 내용에서 동적 값을 사용할 수 있다:

변수	설명
$ARGUMENTS	호출 시 전달된 모든 인수
$ARGUMENTS[N]	N번째 인수 (0-based)
$N	$ARGUMENTS[N]의 축약형
${CLAUDE_SESSION_ID}	현재 세션 ID

---
name: migrate-component
description: 컴포넌트를 다른 프레임워크로 마이그레이션
---
$0 컴포넌트를 $1에서 $2로 마이그레이션하라.

/migrate-component SearchBar React Vue
# → "SearchBar 컴포넌트를 React에서 Vue로 마이그레이션하라."

동적 컨텍스트 주입 (!command“)

셸 명령의 출력을 스킬 콘텐츠에 삽입하는 전처리 기능이다. Claude가 보기 전에 명령이 실행되어 결과로 대체된다.

---
name: pr-summary
description: PR 변경사항 요약
context: fork
agent: Explore
---
## PR 컨텍스트
- PR diff: !`gh pr diff`
- PR 코멘트: !`gh pr view --comments`
- 변경 파일: !`gh pr diff --name-only`
 
## 작업
이 PR을 요약하라...

실행 흐름:

1. 각 !`command`가 즉시 실행됨
2. 출력이 스킬 콘텐츠의 해당 위치를 대체
3. Claude는 실제 데이터가 삽입된 최종 프롬프트를 수신

Subagent에서 실행 (context: fork)

context: fork를 설정하면 스킬이 **격리된 subagent**에서 실행된다. 메인 대화 히스토리에 접근하지 않으며, 스킬 콘텐츠가 subagent의 프롬프트가 된다.

---
name: deep-research
description: 주제를 깊이 조사
context: fork
agent: Explore
---
$ARGUMENTS를 철저히 조사하라:
1. Glob과 Grep으로 관련 파일 탐색
2. 코드 분석
3. 파일 참조와 함께 요약

agent 필드에 사용 가능한 값: Explore, Plan, general-purpose, 또는 .claude/agents/의 커스텀 에이전트.

권한 제어

스킬에 대한 접근을 3가지 방법으로 제어할 수 있다:

# 1. 모든 스킬 비활성화 (/permissions의 deny rules)
Skill
 
# 2. 특정 스킬만 허용/차단
Skill(commit)         # 정확히 'commit'만 허용
Skill(review-pr *)    # 'review-pr'로 시작하는 것 허용
Skill(deploy *)       # 'deploy'로 시작하는 것 차단
 
# 3. 개별 스킬에 disable-model-invocation: true 설정

트러블슈팅

문제	해결 방법
스킬이 트리거되지 않음	description에 사용자가 자연스럽게 말할 키워드 포함. /skill-name으로 직접 호출 시도
스킬이 너무 자주 트리거됨	description을 더 구체적으로 수정. disable-model-invocation: true 설정
Claude가 모든 스킬을 인식 못함	스킬이 많으면 character budget 초과 가능. /context로 확인. SLASH_COMMAND_TOOL_CHAR_BUDGET 환경변수로 한도 조정

참고 문서

• Claude Code Skills 공식 문서
• Subagents - 작업을 위임하는 하위 에이전트
• Plugins - 스킬/에이전트/훅을 패키징하여 배포
• Hooks - 도구 이벤트에 반응하는 자동화
• Memory (CLAUDE.md) - 영구 컨텍스트 관리
• Permissions - 도구 및 스킬 접근 제어