스킬로 Claude 확장하기

스킬로 Claude 확장하기

스킬(Skill)은 Claude Code의 기능을 확장하는 재사용 가능한 단위입니다. SKILL.md 파일 하나에 지침을 담으면 Claude가 도구집에 추가하고, 관련 있을 때 자동 로드하거나 /스킬명으로 직접 호출할 수 있습니다. 같은 지침·체크리스트·다단계 절차를 반복해서 붙여넣게 될 때 스킬을 만들면 됩니다. CLAUDE.md와 달리 스킬 본문은 사용될 때만 로드되므로, 긴 참고 자료도 필요하기 전까지는 컨텍스트를 거의 먹지 않습니다. 스킬은 여러 AI 도구에서 동작하는 Agent Skills 오픈 표준을 따릅니다.

출처: 공식문서

본문

번들 스킬

Claude Code는 /doctor, /code-review, /batch, /debug, /loop, /claude-api 등의 번들 스킬을 포함합니다. 번들 스킬은 프롬프트 기반으로, Claude에게 상세 지침을 주고 도구로 작업을 오케스트레이션하게 합니다. / + 스킬명으로 호출하며, 일부는 관련 있을 때 자동 호출되고 /verify 등은 직접 호출해야 실행됩니다. disableBundledSkills 설정으로 끌 수 있습니다.

앱 실행·검증 3종: /run(변경이 동작함을 보기 위해 앱 실행·구동), /verify(테스트나 타입체크 대신 실제 앱을 빌드·실행해 변경이 의도대로 되었는지 확인), /run-skill-generator(/run·/verify가 프로젝트를 빌드·실행하는 법을 학습시킴). /run·/verify는 설정 없이 프로젝트 유형(CLI·서버·TUI·브라우저)과 README·package.json·Makefile에서 실행법을 추론합니다. /run-skill-generator는 깨끗한 환경에서 성공한 레시피를 .claude/skills/run-<name>/에 프로젝트별 스킬로 커밋합니다.

시작하기

첫 스킬 만들기 — .claude/skills/summarize-changes/SKILL.md처럼 ~/.claude/skills/<이름>/SKILL.md를 만듭니다. YAML 프론트매터(언제 쓸지) + 마크다운 본문(지침). 디렉토리명이 명령이 되고 description이 자동 로드 판단에 쓰입니다:

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks...

!git diff HEAD`` 줄은 동적 컨텍스트 주입으로, Claude가 스킬 내용을 보기 전 명령을 실행하고 출력을 해당 위치에 넣습니다. 테스트는 /summarize-changes로 직접 호출하거나 "What did I change?"처럼 description에 맞는 질문으로 자동 호출합니다.

스킬 위치 (어디에 저장하느냐가 로드 범위 결정):

스킬 폴더는 심링크 가능하고, 이름 synced는 예약(claude.ai 동기화용), .claude/commands/*.md는 구버전 형식(여전히 동작, 스킬 선호). 모노레포에서는 상위 디렉토리 스킬도 로드되며, 중첩 스킬은 해당 하위 파일을 읽을 때 로드됩니다. 같은 이름의 중첩 스킬이 있으면 루트 스킬이 /deploy로 실행되고 /apps/web:deploy 형식으로 중첩 스킬을 따로 호출합니다.

이름 충돌 해결: 엔터프라이즈 > 개인 > 프로젝트 순. 스킬과 번들 스킬이 겹치면 내 스킬이 번들 명령을 대체(별칭은 제외). 스킬 > .claude/commands/ 파일. 플러그인 스킬은 네임스페이스(/plugin-name:skill-name)라 함께 로드.

Cowork·클라우드 세션: ~/.claude/skills/를 읽지 않습니다. claude.ai 계정용 스킬을 로드하며, 비대화형에서 CLAUDE_CODE_SYNC_SKILLS=1 claude -p "..."로 다운로드하면 ~/.claude/skills/synced/에 저장됩니다. 동기화 스킬 이름이 다른 명령과 겹치면 그 명령이 실행됩니다.

라이브 변경 감지: ~/.claude/skills/, 프로젝트 .claude/skills/, --add-dir 디렉토리의 스킬 변경은 재시작 없이 현재 세션에서 반영됩니다. 세션 시작 시 없던 최상위 디렉토리를 만들었다면 재시작 필요.

삭제하기: 개인/프로젝트는 디렉토리 삭제, 엔터프라이즈는 관리자가 삭제, 플러그인은 /plugin uninstall, claude.ai 동기화는 계정에서 끄면 다음 동기화 때 제거, 번들은 disableBundledSkills/skillOverrides.

스킬 구성

스킬 콘텐츠 유형: 참조 콘텐츠(관례·패턴·도메인 지식 — 인라인 실행)는 컨텍스트와 함께 사용, 작업 콘텐츠(배포·커밋·코드 생성 같은 단계별 지침)는 /스킬명으로 직접 호출하는 게 일반적이며 disable-model-invocation: true로 자동 트리거를 막습니다. 본문은 간결하게 (로드 후 턴을 넘어 컨텍스트에 남으므로 모든 줄이 반복 토큰 비용).

프론트매터 레퍼런스 (전부 선택, description만 권장):

문자열 치환: $ARGUMENTS(전체 인자), $ARGUMENTS[N]/$N(0-기반 인덱스), $name(이름 인자), ${CLAUDE_SESSION_ID}, ${CLAUDE_EFFORT}, ${CLAUDE_SKILL_DIR}(스킬 디렉토리), ${CLAUDE_PROJECT_DIR}(프로젝트 루트), ${CLAUDE_PLUGIN_ROOT}·${CLAUDE_PLUGIN_DATA}(플러그인 전용). 예: /fix-issue 123가 $ARGUMENTS에 123을 전달. 다중 값은 셸스타일 따옴표로 감싸세요. $를 리터럴로 쓰려면 \$로 이스케이프.

지원 파일: 스킬 디렉토리에 여러 파일(참조 문서, 예제, 스크립트)을 넣을 수 있습니다. SKILL.md는 500줄 미만 유지.

호출 제어

• disable-model-invocation: true — 사용자만 호출 (부작용·타이밍 제어 워크플로우용, 예: /commit, /deploy)
• user-invocable: false — Claude만 호출 (명령으로 실행할 수 없는 배경 지식용)
• 두 필드 모두 미설정 시 양쪽 다 호출 가능, description은 항상 컨텍스트에 있고 전체 스킬은 호출 시 로드

스킬 콘텐츠 수명주기

호출 시 렌더링된 SKILL.md는 단일 메시지로 대화에 들어가 이후 턴에도 남습니다(권한은 아님 — allowed-tools는 다음 메시지에 해제). 자동 통합 시 스킬을 예산 내로 이월하며, 가장 최근 호출의 처음 5,000 토큰을 재부착하고 총 25,000 토큰 예산을 공유합니다. 오래된 스킬은 통합 후 사라질 수 있으니 재호출하세요.

스킬 도구 사전 승인

allowed-tools: Bash(git add *) Bash(git commit *)처럼 이 스킬을 호출한 턴 동안 승인 없이 쓸 도구를 지정합니다. 다음 메시지를 보내면 해제됩니다. 워크스페이스 신뢰와 무관하게 적용되므로, 저장소에 체크인된 스킬의 allowed-tools는 실행 전에 검토하세요.

인자 전달

$ARGUMENTS 치환으로 인자를 전달합니다. 예: /fix-issue 123 → "Fix GitHub issue 123...". 인덱스 접근 $ARGUMENTS[0]/$0도 가능. 한 메시지 시작에 스킬 여러 개를 스택할 수 있습니다 (/write-tests /fix-issue 123) — 첫 스킬 + 최대 5개 확장.

고급 패턴

동적 컨텍스트 주입: !`<command>` 문법이 스킬 내용을 Claude에게 보내기 전 셸 명령을 실행하고 그 출력으로 치환합니다:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`

줄 시작이나 공백 직후의 !만 인식됩니다. 여러 줄은 ```! 펜스드 코드 블록 사용. disableSkillShellExecution 설정으로 이 동작을 끌 수 있습니다. 실패 처리: 명령이 실패하면 해당 자리뿐 아니라 전체 스킬 호출이 중단됩니다(기본 bash에서 비-0 exit code는 실패. 검색·비교 명령의 exit 1은 정상 처리). 주입 명령은 권한 프롬프트를 띄우지 않으며, 권한 거부 시 호출이 중단됩니다. 각 명령은 Bash 도구의 기본 2분 타임아웃을 사용합니다.

서브에이전트에서 스킬 실행: context: fork를 추가하면 자체 컨텍스트의 서브에이전트에서 실행됩니다. agent 필드로 유형 선택(Explore/Plan/general-purpose/커스텀, 기본 general-purpose), 생략 시 기본. 'fork'라는 이름과 달리 대화 포크가 아니며(대화 히스토리 미상속), 백그라운드로 실행되고 결과가 완료 시 도착합니다. background: false로 그 턴에서 기다릴 수 있습니다. 백그라운드 포크의 편집은 세션 체크포인트 밖이므로 git으로 되돌려야 합니다.

Claude의 스킬 접근 제한: /permissions에서 Skill 도구를 deny하면 전부 비활성. 특정 스킬 허용·거부는 Skill(commit), Skill(review-pr *), Skill(deploy *) 규칙. 개별 숨김은 disable-model-invocation: true.

설정에서 가시성 오버라이드: skillOverrides 설정으로 SKILL.md를 편집하지 않고 제어. 값: "on", "name-only", "user-invocable-only", "off". /skills 메뉴에서 Space로 토글해 .claude/settings.local.json에 저장.

미사용 스킬 찾기: 매 턴 컨텍스트에 스킬이 추가되므로, /skill-doctor로 각 스킬의 비용·사용 빈도를 확인해 끌 것을 결정 (v2.1.252+).

평가·반복

스킬이 트리거되는 것과 의도대로 동작하는 것은 별개입니다. 몇 개의 현실적 프롬프트를 스킬 켜고/끄고 새 세션에서 각각 실행해 비교합니다. skill-creator 플러그인(/plugin install skill-creator@claude-plugins-official)이 이 비교 루프를 자동화합니다: evals/evals.json 테스트 케이스, 스킬당 서브에이전트 격리 실행, grading.json 채점, benchmark.json 벤치마크, A/B 버전 비교, description 튜닝.

스킬 공유

• 프로젝트 스킬: .claude/skills/를 버전 관리에 커밋
• 플러그인: 플러그인에 skills/ 디렉토리 생성
• 관리형: managed settings로 조직 전역 배포

시각적 출력 생성: 스킬이 어떤 언어의 스크립트든 번들·실행해 단일 프롬프트를 넘는 능력을 부여할 수 있습니다(예: 대화형 HTML 트리뷰 코드베이스 익스플로러). 스크립트 경로는 ${CLAUDE_SKILL_DIR}로 참조해 어느 위치에 설치되든 올바르게 해석되게 하세요.

더 알아보기

• 서브에이전트 — 전용 어시스턴트 정의
• 훅 — 결정적 자동화
• Agent Skills 표준
• 모범 사례 — 스킬 작성
• 명령 레퍼런스 — 내장 명령·번들 스킬