Skills 제작 핸드북

슬래시 커맨드와 스킬은 반복 작업을 템플릿화하는 기능입니다. 프로젝트 규칙·자동화 워크플로우를 표준화하고, “어떻게 일해야 하는지”를 코드처럼 버전 관리할 수 있습니다.

1) 로딩 위치·스코프·우선순위 (예상 동작)

로딩 위치

• 프로젝트 스킬: {repo}/.claude/skills/<skill-name>/SKILL.md
• 개인 스킬: ~/.claude/skills/<skill-name>/SKILL.md
• 프로젝트 슬래시 커맨드: {repo}/.claude/commands/*.md
• 개인 슬래시 커맨드: ~/.claude/commands/*.md

우선순위/검색 규칙

• 프로젝트 스킬이 개인 스킬을 덮어씁니다.
• 같은 이름이면 스킬이 커맨드보다 우선합니다.
• 모노레포/대규모 저장소에서는 프로젝트 내부의 중첩된 .claude/skills 디렉토리도 자동 검색됩니다(필요한 서브트리에만 스킬을 두는 패턴이 가능).

“언제 전체 내용이 로딩되나?”

• 세션 시작 시에는 스킬의 description(설명)만 Claude의 컨텍스트에 들어가는 것이 기본입니다.
• 스킬이 실제로 호출될 때(사용자 /... 또는 모델 판단) SKILL.md 본문이 로딩됩니다.

번들 및 유틸리티 슬래시 커맨드 (v2.1.63+)

최근 버전에서 추가된 주요 슬래시 커맨드:

2) 슬래시 커맨드(Commands) 만들기

생성 방법

.claude/commands/ 디렉토리에 Markdown 파일을 만들면 /파일명 커맨드가 됩니다.

.claude/commands/
├── review.md          → /review
├── fix-issue.md       → /fix-issue
└── deploy-check.md    → /deploy-check

개인 명령은 ~/.claude/commands/에 만들면 모든 프로젝트에서 사용 가능합니다.

파일 구조 (Frontmatter)

---
allowed-tools: Read, Grep, Glob, Bash
argument-hint: <파일 경로>
description: 주어진 파일의 코드를 리뷰합니다
model: sonnet
---

$ARGUMENTS 파일을 리뷰해주세요.

## 리뷰 기준

- 보안 취약점
- 성능 문제
- 타입 안정성
- 에러 핸들링

인수 전달

사용 예:

/review src/auth/login.ts
/fix-issue 1234

3) 스킬(Skills) 기본 구조

스킬은 Claude가 자동으로 활용할 수 있는 지식/작업 묶음입니다. Claude Code에서는 .claude/skills/<skill-name>/SKILL.md에 정의합니다.

디렉토리 레이아웃

.claude/skills/
└── api-conventions/
    ├── SKILL.md
    ├── REFERENCE.md           # (선택) 상세 규칙/레퍼런스
    ├── CHECKLIST.md           # (선택) 반복 체크리스트
    └── scripts/               # (선택) 반복 작업 자동화
        └── validate.sh

4) 스킬 선언(Frontmatter) 예상 동작

SKILL.md는 YAML frontmatter로 동작을 제어할 수 있습니다.

---
name: api-conventions
description: REST API 엔드포인트를 프로젝트 컨벤션에 맞게 작성/리뷰합니다
argument-hint: <라우트 파일 경로>
allowed-tools: Read, Edit, Grep, Glob, Bash
model: sonnet
---

# API 컨벤션

## Instructions

- 라우트: /api/v1/{resource}
- 응답: { data, error, meta } 형식

주요 필드와 의미

5) 인수/변수/치환 — “스킬이 입력을 받는 방식”

인수 전달 규칙

/my-skill arg1 arg2처럼 호출하면:

• SKILL.md에 $ARGUMENTS가 있으면 해당 위치에 치환됩니다.
• $ARGUMENTS가 없으면, Claude Code가 본문 끝에 ARGUMENTS: ... 형태로 덧붙입니다.

문자열 치환(예시)

• $ARGUMENTS — 사용자가 넘긴 인수 문자열
• ${CLAUDE_SESSION_ID} — 현재 세션 ID
• ${CLAUDE_SKILL_DIR} — 스킬이 자신의 디렉토리 경로를 참조 (v2.1.69). 스킬 내부의 스크립트나 레퍼런스 파일을 상대 경로 없이 안정적으로 참조할 때 유용합니다.

6) 고급 기능들 (실전에서 “차이 나는” 포인트)

6-1. 도구 제한을 “정밀”하게 걸기 (allowed-tools)

allowed-tools: Read, Edit, Grep, Glob, Bash(gh:*), Bash(git status), Bash(git diff)

• Bash(gh:*)처럼 명령 allowlist를 걸어두면 실수로 위험한 명령을 실행하는 확률이 줄어듭니다.
• “조심스러운 스킬”은 Read, Grep, Glob만 열고, 변경이 필요할 때만 별도 스킬로 분리하는 편이 운영이 쉽습니다.

6-2. 동적 컨텍스트 주입 (로컬에서 “미리 계산”하고 넣기)

SKILL.md 본문에서 다음 구문을 쓰면, Claude에게 보내기 전에 로컬에서 실행 결과를 주입할 수 있습니다.

!`git diff --stat`

패턴:

• “현재 상태를 요약해 붙이기”: git status, git diff, rg -n ...
• “대용량 로그/결과는 절제”: 주입 출력이 길어지면 비용이 커지고 노이즈가 됩니다.

6-3. 하위 에이전트(서브에이전트)로 스킬 실행 (context: fork)

“무거운 조사/리서치 스킬”을 메인 세션과 분리하면 컨텍스트 관리가 쉬워집니다.

context: fork
agent: reviewer

6-4. 스킬 전용 훅(hooks.json)

스킬 폴더에 hooks.json을 두면 “이 스킬 실행 전후”에만 자동화 훅을 적용할 수 있습니다. 전역 훅이 많은 팀에서는 스킬 단위로 훅을 좁히는 것이 디버깅을 단순하게 만듭니다.

6-5. paths: frontmatter — 경로 기반 활성화 (v2.1.84)

스킬 frontmatter에 paths: 필드를 추가하면, 특정 파일 패턴에서만 스킬이 활성화됩니다. YAML 리스트로 glob 패턴을 지정합니다.

---
name: react-conventions
description: React 컴포넌트 컨벤션을 적용합니다
paths:
  - "src/components/**/*.tsx"
  - "src/hooks/**/*.ts"
---

6-6. 설명(description) 길이·프롬프트 예산

• 초기 릴리스에서는 스킬 설명 제한이 250자였지만, 최신 릴리스 기준 /skills와 Skill tool에 노출되는 listing cap은 1,536자까지 확장되었습니다. 너무 길면 시작 시 truncation warning이 표시됩니다. (v2.1.105)
• /skills 메뉴가 알파벳순 정렬과 함께 토큰 수 기준 정렬(t)도 지원합니다. (v2.1.86, v2.1.111)
• Skill tool에 보여지는 스킬 메타데이터 예산은 현재 **컨텍스트 윈도우의 1%**를 기준으로 동적으로 계산되며, 기본 fallback은 8,000자입니다. 필요하면 SLASH_COMMAND_TOOL_CHAR_BUDGET으로 조정할 수 있습니다. (공식 env vars 기준)
• 설명이 길거나 스킬이 많으면, Claude가 프롬프트를 줄이기 위해 일부 정보를 축약할 수 있습니다.
• /context로 실제 프롬프트 경고/예산 상태를 확인하는 습관이 도움이 됩니다.

6-7. 내장 슬래시 명령과 Skill tool의 연결 (v2.1.108)

최신 릴리스부터 모델은 Skill tool을 통해 내장 슬래시 명령도 발견하고 호출할 수 있습니다. 대표적으로 /init, /review, /security-review 같은 기본 명령을 커스텀 래퍼 스킬 없이도 오케스트레이션에 섞어 쓸 수 있습니다.

6-8. 스킬 공유/배포 (플러그인, 오픈 표준)

• 팀 내부 공유: {repo}/.claude/skills로 Git에 포함(가장 단순).
• 개인 재사용: ~/.claude/skills에 설치.
• 배포/공유: 플러그인 형태로 묶거나, Agent Skills 오픈 표준으로 공개하는 흐름이 있습니다.

플러그인 디렉토리 예:

~/.claude/plugins/<plugin-name>/
├── plugin.json
├── bin/
└── .claude/
    ├── commands/
    └── skills/

플러그인 git-subdir source type (v2.1.69)

플러그인 소스로 git-subdir 타입을 지정하면, git 리포지토리 내 특정 하위 디렉토리만 플러그인으로 가져올 수 있습니다. 대형 모노레포에서 필요한 플러그인만 선택적으로 설치할 때 유용합니다.

source: 'settings' 플러그인 소스 (v2.1.80)

settings.json에 플러그인 항목을 인라인으로 선언할 수 있습니다. 별도의 플러그인 디렉토리 없이 설정 파일만으로 플러그인을 관리하는 방식입니다.

플러그인 검증 및 관리

• claude plugin validate 명령이 스킬, 에이전트, 커맨드 frontmatter와 hooks.json까지 검증합니다. (v2.1.77)
• ref-tracked 플러그인은 로드할 때마다 자동으로 재클론되어 항상 최신 버전을 유지합니다. (v2.1.81)
• CLAUDE_CODE_PLUGIN_SEED_DIR 환경변수가 다중 seed 디렉토리를 지원합니다. (v2.1.79)
• 플러그인은 bin/ 아래에 실행 파일을 함께 배포할 수 있고, Bash 도구에서 bare command처럼 호출할 수 있습니다. (v2.1.91)
• 오프라인/불안정 네트워크 환경에서는 CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1로 git pull 실패 시 기존 마켓플레이스 캐시를 유지할 수 있습니다. (v2.1.90)

7) “대표 스킬” 소개 (공식 제공 + 실전 레시피)

7-1. 공식(Anthropic)에서 제공하는 대표 스킬들

Agent Skills 생태계에서 자주 언급되는 대표 스킬 예:

• Code execution: 코드 실행/계산/실험 자동화
• Google Drive / Gmail: 문서·메일 읽기/정리/작성 보조
• PowerPoint / Excel / Word / PDF: 오피스 문서 생성·편집·요약

7-2. Claude Code에서 자주 만드는 커스텀 스킬 레시피

아래는 팀에서 재사용 가치가 큰 “대표 스킬” 패턴입니다. (이름은 예시)

1) pr-summary — PR 요약 + 리스크 체크

• 트리거: “PR 요약해줘”, “리뷰 포인트 알려줘”
• 출력: 변경 요약, 위험도, 테스트/롤백 체크리스트
• 권장 도구: Read, Grep, Glob (+ 필요 시 제한된 Bash(git diff) 정도)

2) deep-research — 코드베이스 조사/문서화

• 트리거: “이 기능이 어디서 동작해?”, “아키텍처 맵 만들어줘”
• 고급: context: fork로 서브에이전트 분리(메인 세션 오염 방지)

3) safe-refactor — 리팩터링(테스트 우선)

• 트리거: “구조 개선”, “중복 제거”
• 룰: “테스트 먼저/동시 작성”, “동작 유지”, “작은 PR 단위”

4) incident-triage — 장애/로그 기반 원인 분석

• 트리거: “에러 로그 분석”, “재현 경로”
• 고급: 동적 컨텍스트 주입(! + 백틱 구문)으로 핵심 로그/지표만 첨부

5) repo-onboarding — 저장소 온보딩(개발 규칙/명령 정리)

• 트리거: “이 프로젝트 개발 방법”, “규칙 뭐야?”
• 레퍼런스: REFERENCE.md에 컨벤션/폴더 구조/명령을 정리해 분리

6) security-review — 읽기 전용 보안 리뷰

• 트리거: “취약점 점검”, “인증/권한 흐름 검토”
• 권장 도구: Read, Grep, Glob만 허용(쓰기 금지)

8) 디버깅/운영 팁

• 스킬의 description: frontmatter가 없으면 스킬 목록에 누락됩니다. 반드시 설명을 작성하세요. (v2.1.69 수정)
• 스킬/커맨드 로딩 문제는 claude --debug로 확인합니다.
• 같은 이름 충돌이 의심되면 “어떤 스킬이 선택되는지”부터 확인하고, 필요 시 스킬 이름을 바꿔 충돌을 제거합니다.
• 팀 공유 스킬은 {repo}/.claude/skills에 두고, 개인 실험 스킬은 ~/.claude/skills에 두는 방식이 운영이 편합니다.

9) 공식 자료 모음 (추천 읽는 순서)

• Claude Code: 스킬 확장 가이드 https://code.claude.com/docs/ko/skills (한국어)
• Claude Code: 설정/권한(allowed-tools와 같이 보면 좋음) https://code.claude.com/docs/ko/settings (한국어)
• Claude Code: 슬래시 커맨드 https://code.claude.com/docs/ko/slash-commands (한국어)
• Agent Skills(개요) https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/overview (한국어)
• Agent Skills: 작성 모범 사례 https://platform.claude.com/docs/ko/agent-skills/best-practices (한국어)
• Agent SDK에서 스킬 사용 https://platform.claude.com/docs/ko/agent-skills/agent-sdk (한국어)
• 배경(Anthropic Engineering): 에이전트용 도구 설계 https://www.anthropic.com/engineering/writing-tools-for-agents (영문)

MCP 프롬프트도 슬래시 커맨드로 노출

MCP 서버가 prompts를 제공하면, 자동으로 슬래시 커맨드가 됩니다.

형식:

/mcp__<server-name>__<prompt-name> [arguments]