Ch7. Skills & 슬래시 커맨드

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

1) 로딩 위치·스코프·우선순위

로딩 위치

스킬을 어디에 두느냐가 누가 쓸 수 있는지를 정합니다.

슬래시 커맨드는 동일하게 ~/.claude/commands/*.md(개인)와 {repo}/.claude/commands/*.md(프로젝트)에 둘 수 있습니다.

우선순위/검색 규칙

• 같은 이름의 스킬이 여러 스코프에 있으면, 엔터프라이즈 > 개인 > 프로젝트 순으로 덮어씁니다. (즉, 개인 스킬이 프로젝트 스킬을 덮어씁니다 — 흔히 반대로 오해하기 쉬운 부분입니다.)
• 플러그인 스킬은 plugin-name:skill-name 네임스페이스를 쓰므로 다른 스코프와 충돌하지 않습니다.
• 같은 이름이면 스킬이 커맨드보다 우선합니다. (.claude/commands/의 파일은 그대로 동작하지만, 동명의 스킬이 있으면 스킬이 우선합니다.)
• 프로젝트 스킬은 시작 디렉토리부터 저장소 루트까지의 모든 부모 디렉토리 .claude/skills/에서 로딩됩니다. 또한 시작 디렉토리 하위의 파일을 다룰 때는 그 경로의 중첩된 .claude/skills 디렉토리도 필요에 따라 자동 검색됩니다(모노레포에서 패키지별 스킬을 두는 패턴이 가능).

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

• 세션 시작 시에는 기본적으로 스킬의 description(설명)만 Claude의 컨텍스트에 들어갑니다.
• 스킬이 실제로 호출될 때(사용자 /... 또는 모델 판단) SKILL.md 본문이 로딩됩니다.
• 한 번 호출된 스킬 본문은 단일 메시지로 컨텍스트에 들어가 세션 동안 유지되며, Claude Code는 이후 턴에서 파일을 다시 읽지 않습니다. 그래서 작업 내내 적용해야 하는 지침은 “1회성 단계”가 아니라 상시 지침으로 적는 편이 좋습니다.

세션 중 실시간 변경 감지(Live change detection)

Claude Code는 스킬 디렉토리의 파일 변경을 감시합니다. ~/.claude/skills/, 프로젝트 .claude/skills/, --add-dir 디렉토리의 .claude/skills/ 아래에서 스킬을 추가·수정·삭제하면 재시작 없이 현재 세션에 반영됩니다. 다만 세션 시작 시점에 없던 최상위 skills 디렉토리를 새로 만들면 감시 대상에 넣으려고 Claude Code를 재시작해야 합니다.

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

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

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로 동작을 제어할 수 있습니다. 모든 필드는 선택이며, Claude가 “언제 쓸지” 판단할 수 있도록 description만 권장됩니다.

---
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 } 형식

주요 필드와 의미

2-1) Dynamic workflows와 목표 기반 명령

v2.1.154부터는 단일 skill을 호출하는 수준을 넘어, Claude가 workflow를 만들고 여러 background agent를 조율하는 흐름이 공식 기능으로 들어왔습니다.

• /goal <condition>: 완료 조건을 선언합니다. 예: /goal tests pass and the PR description is updated
• /workflows: dynamic workflow의 실행 상태를 확인하고, 필요한 경우 pause/resume/save합니다.
• claude agents 또는 /background: workflow와 별도로 background session을 직접 관리합니다.
• ! <command> 또는 claude --bg --exec '<command>': 모델 호출 없이 shell command를 Agent View row로 실행합니다.

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

인수 전달 규칙

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

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

문자열 치환

• $ARGUMENTS — 넘긴 전체 인수 문자열(입력 그대로)
• $ARGUMENTS[N] / $N — N번째(0-based) 인수. $0이 첫 번째
• $name — arguments: frontmatter로 선언한 명명 인수
• ${CLAUDE_SESSION_ID} — 현재 세션 ID(로깅, 세션별 파일 생성 등에 유용)
• ${CLAUDE_EFFORT} — 현재 effort 레벨(low/medium/high/xhigh/max/ultra). 스킬 지침을 effort에 맞춰 조정할 때 사용
• ${CLAUDE_SKILL_DIR} — 스킬 SKILL.md가 위치한 디렉토리 경로. 플러그인 스킬의 경우 플러그인 루트가 아니라 스킬 하위 디렉토리입니다. 작업 디렉토리와 무관하게 스킬 내부 스크립트/레퍼런스 파일을 안정적으로 참조할 때 유용합니다.

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에게 보내기 전에 로컬에서 실행 결과를 주입할 수 있습니다. 이는 Claude가 실행하는 것이 아니라 **전처리(preprocessing)**이며, Claude는 최종 결과만 봅니다.

!`git diff --stat`

동작·제약:

• 각 !`<command>`는 Claude가 내용을 보기 전에 즉시 실행되고, 그 출력이 placeholder를 대체합니다.
• 치환은 원본 파일에 대해 한 번만 수행되며, 명령 출력은 평문으로 삽입되어 다시 스캔되지 않습니다(명령이 또 다른 placeholder를 내보내도 확장되지 않음).
• inline 형태(!`...`)는 !가 줄 맨 앞이거나 공백 바로 뒤에 올 때만 인식됩니다. KEY=!`cmd`처럼 다른 문자 뒤에 오면 리터럴 텍스트로 남고 실행되지 않습니다.
• 여러 줄 명령은 inline 대신 ```! 로 여는 펜스 코드 블록을 사용합니다.
• “현재 상태를 요약해 붙이기”: git status, git diff, rg -n ...
• “대용량 로그/결과는 절제”: 주입 출력이 길어지면 비용이 커지고 노이즈가 됩니다.

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

“무거운 조사/리서치 스킬”을 메인 세션과 분리하면 컨텍스트 관리가 쉬워집니다. context: fork를 추가하면 스킬 본문이 서브에이전트의 프롬프트가 되어 격리된 컨텍스트에서 실행되며, 메인 대화 히스토리에는 접근하지 않습니다. 실행 환경(모델·도구·권한)은 agent 필드로 정합니다.

context: fork
agent: Explore

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) 길이·프롬프트 예산

• 한 스킬의 description+when_to_use 합산 텍스트는 listing에서 1,536자로 잘립니다. 핵심 use case를 앞쪽에 두세요. 이 per-entry cap은 maxSkillDescriptionChars 설정으로 조정할 수 있습니다.
• 전체 스킬 listing의 메타데이터 예산은 **컨텍스트 윈도우의 1%**를 기준으로 동적으로 계산됩니다. 스킬 이름은 항상 포함되지만, 스킬이 많아 예산을 넘기면 가장 적게 호출하는 스킬의 description부터 잘려나갑니다(자주 쓰는 스킬은 전체 텍스트 유지).
• 예산을 늘리려면 skillListingBudgetFraction(예: 0.02 = 2%) 설정이나 고정 글자 수를 지정하는 SLASH_COMMAND_TOOL_CHAR_BUDGET 환경변수를 사용합니다.
• /skills 메뉴는 이름순 정렬과 토큰 수 기준 정렬(t 키)을 지원하며, Space로 스킬 노출 상태를 토글하고 Enter로 저장할 수 있습니다. (v2.1.86, v2.1.111)
• 예산이 실제로 넘치고 있는지, 어떤 스킬이 영향받는지는 **/doctor**로 확인합니다. (/context로 전체 컨텍스트 점유 현황도 함께 확인하면 좋습니다.)

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

최신 릴리스부터 모델은 Skill tool로 일부 내장 슬래시 명령도 발견하고 호출합니다. 대표적으로 /init, /review, /security-review를 커스텀 래퍼 스킬 없이도 오케스트레이션에 섞어 쓸 수 있습니다. 다만 /compact 같은 일부 명령은 Skill tool로 노출되지 않습니다.

6-8. 모델의 스킬 접근 제어 (권한 규칙 / skillOverrides)

스킬마다 frontmatter를 고치지 않고도 모델의 스킬 호출 범위를 제어할 수 있습니다.

• 전체 차단: /permissions에서 Skill을 deny 규칙에 추가하면 모든 스킬 호출이 막힙니다.
• 특정 스킬 허용/차단: 권한 규칙으로 세밀하게 지정합니다. Skill(name)은 정확히 일치, Skill(name *)는 접두 일치(임의 인수 허용)입니다.

# 허용
Skill(commit)
Skill(review-pr *)

# 차단
Skill(deploy *)

• 개별 스킬 가시성 오버라이드: skillOverrides 설정으로 SKILL.md를 건드리지 않고 가시성을 바꿀 수 있습니다(공유 저장소나 MCP 제공 스킬에 유용). /skills 메뉴에서 스킬을 고른 뒤 Space로 상태를 순환시키고 Enter로 .claude/settings.local.json에 저장합니다. 값은 "on"(이름+설명) / "name-only"(이름만) / "user-invocable-only"(모델에는 숨김, / 메뉴에는 노출) / "off"(완전 숨김)입니다. 단, 플러그인 스킬은 skillOverrides의 영향을 받지 않으며 /plugin으로 관리합니다.

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

6-9. 컴팩션(auto-compaction) 시 스킬 보존

대화가 길어져 요약(컴팩션)되면, Claude Code는 토큰 예산 안에서 호출된 스킬을 이어서 붙입니다. 각 스킬의 가장 최근 호출본을 요약 뒤에 재첨부하되 앞 5,000토큰만 유지하며, 재첨부 스킬들은 합산 25,000토큰의 공동 예산을 가장 최근 호출한 순서대로 채웁니다. 그래서 한 세션에서 많은 스킬을 호출했다면 오래된 스킬은 컴팩션 후 완전히 빠질 수 있습니다. 스킬이 크거나 이후 다른 스킬을 여럿 호출했다면, 컴팩션 후 다시 호출해 전체 내용을 복원하세요.

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

• 팀 내부 공유: {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을 생략하면 본문 첫 문단이 설명으로 쓰입니다. 다만 모델 자동 선택의 정확도가 떨어지니, 사용자가 자연스럽게 말할 트리거 키워드를 넣어 명시적으로 적으세요.
• 스킬이 자동 호출되지 않으면: 설명에 트리거 키워드가 있는지, What skills are available?로 목록에 뜨는지 확인하고, 요청 문구를 description에 가깝게 바꿔보거나 /skill-name으로 직접 호출합니다.
• 스킬이 너무 자주 호출되면: description을 더 구체적으로 좁히거나 disable-model-invocation: true로 수동 호출만 허용합니다.
• 스킬/커맨드 로딩 문제는 claude --debug(또는 세션 중 /debug)와 /doctor로 진단합니다.
• 같은 이름 충돌이 의심되면 “어떤 스킬이 선택되는지”부터 확인하고(우선순위는 엔터프라이즈 > 개인 > 프로젝트, 스킬 > 커맨드), 필요 시 스킬 이름을 바꿔 충돌을 제거합니다.
• 팀 공유 스킬은 {repo}/.claude/skills에, 개인 실험 스킬은 ~/.claude/skills에 두면 운영이 편합니다.

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

• Claude Code: 스킬 확장 가이드 https://code.claude.com/docs/ko/skills (한국어)
• Claude Code: 설정 https://code.claude.com/docs/ko/settings · 권한 https://code.claude.com/docs/ko/permissions (한국어, allowed-tools와 같이 보면 좋음)
• Claude Code: 명령어(슬래시 커맨드) 레퍼런스 https://code.claude.com/docs/ko/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]