스킬

확인 날짜 안내

확인 날짜가 섞인 페이지다. 대부분은 공식 문서(원본 날짜 미상, 수집 2026-10-18) 기준이다. 공식 스킬 문서 Claude Code 스킬이 같은 내용을 확인해 준 블로그 문장은 2026-10-18 기준으로 적었고, 블로그 Steering Claude Code에만 근거한 문장에는 "(2026-06-18 기준)"을 남겼다. 블로그 비용 등급 Low는 "(블로그 평가)"라 날짜 계산에서 뺀다. 번들 /code-review의 동작은 2026-10-26 수집한 공식 Commands 문서 Claude Code 명령어 레퍼런스 기준으로 갱신했다(--fix로 고칠 수 있음, 블로그 문장은 이력). 페이지 확인 날짜는 2026-06-18로 남는다. "다른 도구의 스킬 위치: Antigravity CLI" 절의 "설치 중 직접 만든 스킬과 설치한 스킬을 자동으로 가져온다"가 Gemini CLI 저장소 공지(2026-06-18)에만 근거하고, 이전 문서와의 상충이 아직 열려 있기 때문이다(Gemini CLI에서 Antigravity CLI로 옮기기 4단계).

정의#

지식, 워크플로, 지시를 담은 마크다운(용어 사전) 파일이다. /deploy 같은 명령으로 직접 부르거나, 관련 있을 때 Claude가 자동으로 불러온다. 현재 대화에서 돌 수도 있고 서브에이전트를 통해 격리된 컨텍스트에서 돌 수도 있다. 원본은 스킬을 "가장 유연한 확장"이라 부른다. Claude Code 확장 기능 개요

공식 스킬 문서는 이렇게 정의한다. 지시를 담은 SKILL.md를 만들면 Claude가 도구 모음에 더하고, 관련 있을 때 쓰거나 /skill-name으로 직접 부른다. Claude Code 스킬

• 기존 커스텀 명령은 스킬에 합쳐졌다. .claude/commands/deploy.md와 .claude/skills/deploy/SKILL.md는 둘 다 /deploy를 만들고 똑같이 동작한다. 스킬은 여기에 보조 파일 디렉터리, 누가 부를지 정하는 frontmatter, 관련 있을 때 자동 로드를 더한다. 새 작업에는 스킬을 권한다. Claude Code 스킬
• Claude Code 스킬은 여러 AI 도구에서 통하는 Agent Skills (새 창) 개방형 표준을 따르고, 호출 제어·서브에이전트 실행·동적 컨텍스트 주입 같은 기능을 더한다. 표준 밖에서(claude.ai 업로드, Skills API) 쓸 수 있는 frontmatter는 name, description, license, compatibility, metadata, allowed-tools 여섯 개이고, 다른 필드를 넣으면 업로드가 오류로 실패한다. Claude Code 스킬

언제 스킬을 만드는가#

• 같은 지시, 체크리스트, 여러 단계 절차를 채팅에 계속 붙여 넣고 있을 때, 또는 CLAUDE.md의 한 절이 사실이 아니라 절차로 자랐을 때. CLAUDE.md와 달리 스킬 본문은 쓸 때만 로드되므로 긴 참고 자료도 필요하기 전까지 비용이 거의 없다. Claude Code 스킬
• 같은 프롬프트를 계속 쳐서 작업을 시작한다면 사용자가 부르는 스킬로 저장한다. Claude Code 확장 기능 개요
• 같은 플레이북이나 여러 단계 절차를 세 번째로 채팅에 붙여 넣고 있다면 스킬로 담는다. Claude Code 확장 기능 개요
• 손으로 계속 고쳐 쓰는 워크플로는 스킬을 한 번 더 손볼 때라는 신호다. Claude Code 확장 기능 개요
• (2026-06-18 기준) 블로그 글은 CLAUDE.md에 30줄짜리 절차가 있다면 옮길 신호라고 구체적인 기준을 든다. Steering Claude Code

만드는 절차: 업무 절차를 스킬로 만들기 · 점진적 셋업에서의 위치: Claude Code 셋업 점진적으로 키우기

두 종류: 참고형과 실행형#

• 참고형(reference): 세션 내내 Claude가 쓰는 지식. 예: API 스타일 가이드. Claude Code 확장 기능 개요 공식 스킬 문서는 관례, 패턴, 스타일 가이드, 도메인 지식을 예로 들고, 이 내용은 대화 맥락과 함께 쓰이도록 인라인으로 돈다고 한다. Claude Code 스킬
• 실행형(action, 공식 스킬 문서는 task content): 특정 일을 하게 하는 단계별 지시. 예: 배포 워크플로를 돌리는 /deploy. Claude Code 확장 기능 개요 배포, 커밋, 코드 생성처럼 Claude가 정하게 두기보다 직접 부르고 싶은 경우가 많아 disable-model-invocation: true를 단다. Claude Code 스킬
• context: fork는 명시적 지시가 있는 실행형에만 의미가 있다. "이 API 관례를 써라" 같은 지침만 있고 할 일이 없으면 서브에이전트가 실행할 프롬프트 없이 지침만 받아 쓸 만한 결과 없이 돌아온다. Claude Code 스킬

번들 스킬#

Claude Code에는 설정 없이 쓰는 번들 스킬(/code-review, /batch, /debug 등)이 들어 있고, 직접 만들 수도 있다. Claude Code 확장 기능 개요

공식 스킬 문서 기준(2026-10-18) 세부: Claude Code 스킬

• 예: /doctor, /code-review, /batch, /debug, /loop, /claude-api. 번들 스킬은 프롬프트 기반이라 Claude에게 자세한 지시를 주고 도구로 작업을 조율하게 한다. 대부분의 내장 명령은 고정된 로직을 직접 실행한다는 점이 다르다.
• 일부는 Claude가 관련 있을 때 자동으로 부르고, /verify처럼 시간과 토큰이 드는 긴 점검은 사용자가 부를 때만 돈다.
• /doctor는 설치 상태, 확장 기능(안 쓰는 스킬·MCP 서버·플러그인을 컨텍스트 비용과 비교, 느린 훅), CLAUDE.md, 권한을 점검하고 바꾸기 전에 확인을 받는다. 항상 로드되는 지침을 필요할 때 로드되는 스킬과 하위 CLAUDE.md로 옮기자고 제안한다. → CLAUDE.md 작성·구성
• /run·/verify·/run-skill-generator는 테스트만이 아니라 실제로 앱을 띄워 변경을 확인한다. /run-skill-generator는 깨끗한 환경에서 앱을 띄운 방법을 .claude/skills/run-<name>/ 프로젝트 스킬로 기록해, 이후 /run·/verify와 다른 에이전트가 같은 방법을 따르게 한다.
• 세션 시작 때 verify나 simplify라는 이름의 스킬(사용자가 만든 것)이 있으면, 문서·테스트 변경을 빼고 커밋 직전마다 그 스킬을 돌리라는 지시가 Claude에게 들어간다. v2.1.286 이상이며, 번들·플러그인·claude.ai 스킬은 해당하지 않는다.
• 번들 스킬을 끄려면 disableBundledSkills 설정을 쓴다.
• (2026-10-26 기준) 공식 Commands 문서는 명령 표에서 번들 스킬에 Skill, 번들 워크플로에 Workflow 표시를 단다. 번들 스킬 예: /code-review, /batch, /debug, /doctor, /loop, /simplify, /verify, /run, /run-skill-generator, /claude-api, /fewer-permission-prompts, /update-config. 번들 워크플로는 일을 여러 서브에이전트로 펼쳐 백그라운드에서 도는 동적 워크플로이고 예는 /deep-research다. /verify와 /deep-research는 지금은 사용자가 부를 때만 돈다(각각 v2.1.215·v2.1.218 이전에는 Claude가 스스로도 시작할 수 있었음). 명령 전체와 작업 흐름별 고르기는 Claude Code 슬래시 명령. Claude Code 명령어 레퍼런스
• (2026-10-21 기준) 내장 명령과 번들 스킬의 경계 예: /auto-mode-setup은 번들 스킬이 아닌 내장 명령이라 disableBundledSkills로 꺼지지 않지만, skillOverrides의 "auto-mode-setup": "off" 항목은 적용돼 명령과 제안 대화상자를 함께 끈다. Claude Code 자동 모드 설정 → Claude Code 자동 모드 설정하기

어디에 두는가 (2026-10-18 기준)#

어디에 저장하느냐가 어느 세션에서 로드되는지를 정한다. Claude Code 스킬

근거: Claude Code 스킬 (원본 "Choose where skills load" 표)

• 프로젝트 스킬은 시작한 디렉터리와 그 위로 저장소 루트까지의 .claude/skills/에서 로드된다. 그래서 packages/frontend/에서 시작해도 루트 스킬을 쓴다. Claude Code 스킬
• 이름이 겹치면: Enterprise > Personal > Project. 내 스킬이 같은 이름의 번들 스킬을 대체하고, 로컬 터미널 세션에서는 같은 이름의 내장 명령도 대체한다. 어느 쪽이든 그 별칭(alias)은 대체하지 않는다. 스킬과 .claude/commands/ 파일이 겹치면 스킬이 이긴다. 플러그인 스킬은 네임스페이스가 붙어 함께 로드된다. Claude Code 스킬 → Claude Code 확장 기능 고르기
• 세션 중에 ~/.claude/skills/, 프로젝트 .claude/skills/, --add-dir 디렉터리의 .claude/skills/에서 스킬을 더하거나 고치거나 지우면 재시작 없이 반영된다. 세션 시작 때 없던 최상위 스킬 디렉터리를 새로 만들었으면 /reload-skills를 실행한다. Claude Code 스킬
• 폴더 이름 synced와 anthropic-skills는 claude.ai 동기화 스킬용으로 예약돼 있다. Claude Code 스킬

claude.ai에서 동기화되는 스킬과 Cowork·클라우드 세션#

• Cowork 세션과 클라우드 세션(루틴 포함)은 내 기기의 ~/.claude/skills/를 읽지 않는다. claude.ai 계정에서 켠 스킬을 세션 시작 때 동기화해 로드하고, 클라우드 세션은 클론한 저장소의 .claude/skills/도 로드한다. 개인 스킬을 거기서 쓰려면 claude.ai 계정에서 켜거나(클라우드 세션이라면) 저장소에 커밋한다. Claude Code 스킬 → Claude Cowork
• 터미널에서 claude.ai 계정으로 로그인하면 계정 스킬을 ~/.claude/skills/synced/로 내려받는다(v2.1.273 이상). 내려받기만 하고 올리지 않으므로, 그 폴더의 파일을 고쳐도 계정에 저장되지 않고 다음 동기화가 덮어쓸 수 있다. 바꾸려면 claude.ai에서 고친다. Claude Code 스킬
• 내 기기의 다른 세션에서는 동기화 스킬 본문의 !`명령`을 실행하지 않는다. Cowork 데스크톱 세션에서는 그 줄을 정책 차단 문구로 바꾼다. Claude Code 스킬
• (2026-09-16 기준) Cowork와 채팅을 하나의 Claude로 합친 발표 글은 Cowork가 하던 일을 이미 가진 스킬·커넥터와 함께 어느 대화에서나 쓸 수 있고, 기존 Cowork 사용자의 스킬이 그대로 남는다고 말한다. 통합 뒤 대화에서 스킬이 어디서 어떻게 로드되는지(위 동기화 규칙이 그대로인지)는 공지에 없다. Claude Cowork와 채팅 통합 공지 → Claude Cowork 같은 날 수정된 Help Center 문서는 스킬을 "작업 방식을 가르치면 그 작업이 나올 때마다 그 단계를 따르는 것"으로 소개하고, 기존 Cowork 사용자의 스킬이 넘어온다고 말한다. 로드 위치는 이 문서에도 없다. Claude Cowork와 채팅 통합 도움말

다른 도구의 스킬 위치: Antigravity CLI (2026-10-18 기준)#

Antigravity CLI 공식 이전 문서는 Gemini CLI에서 옮길 때 스킬 경로가 바뀐다고 말한다. 원본은 전역 공유 스킬이 사용자 홈 디렉터리에 남는다고 하면서, 워크스페이스 스킬의 폴더 경로가 바뀌었다고 설명한다. Gemini CLI에서 Antigravity CLI로 이전 Google의 전환 공지(2026-05-19)도 Antigravity CLI가 Gemini CLI의 핵심 기능으로 Agent Skills를 유지한다고 말한다. Gemini CLI의 Antigravity CLI 전환 공지 Gemini CLI 저장소 공지(2026-06-18)는 설치 중에 직접 만든 스킬과 설치한 스킬을 자동으로 가져온다고 말한다. 워크스페이스 스킬을 직접 옮겨야 한다는 이전 문서와의 차이는 Gemini CLI에서 Antigravity CLI로 옮기기에 상충으로 나란히 두었다. Gemini CLI 개인 계정 요청 처리 중단 공지

• 워크스페이스 스킬이 .gemini/skills/에 있으면 .agents/skills/로 직접 이름을 바꾸거나 옮겨야 Antigravity 에이전트가 활성 슬래시 명령으로 인식한다(원본 표시 "Action required"). Gemini CLI에서 Antigravity CLI로 이전 → Gemini CLI에서 Antigravity CLI로 옮기기
• agy plugin import gemini는 예전 확장의 명령(commands)을 스킬로 바꾼다(원본 예상 출력 "legacy commands converted to skills"). Gemini CLI에서 Antigravity CLI로 이전 편집자 해석: 위 정의 절의 "커스텀 명령은 스킬에 합쳐졌다"는 Claude Code 설명과 같은 방향으로 볼 수 있다. Claude Code 스킬
• (2026-10-21 기준) Antigravity 공식 Rules 문서는 규칙과 스킬을 이렇게 나눈다: 제약과 불변 조건(예: "검증에는 항상 zod", "패키지 사이에 internal/을 import하지 마라")은 규칙으로, 여러 단계 워크플로(예: DB 마이그레이션 실행 방법)는 스킬로 쓴다. 같은 문서의 model_decision 규칙은 경로와 설명만 먼저 넣고 필요할 때 전체를 읽는 점진적 공개 방식이다. Antigravity 규칙 문서 → 스키마 파일
• (2026-10-21 기준) Antigravity 공식 서브에이전트 문서는 사용자 서브에이전트 frontmatter에 skills 필드(스킬 경로 목록, 예: skills/my-helper-skill)를 둔다. 원본 예시는 보안 감사 서브에이전트에 skills/security-checklist를 붙인다. 그 스킬이 언제 로드되는지는 원본이 말하지 않는다. Antigravity 서브에이전트 문서 → 서브에이전트
• Claude Code 프로젝트 스킬 위치(.claude/skills/)와 Antigravity CLI 워크스페이스 스킬 위치(.agents/skills/)는 다르다. 두 원본 모두 상대 도구의 경로를 말하지 않는다. Claude Code 스킬, Gemini CLI에서 Antigravity CLI로 이전

어떻게 로드되는가#

• 기본값: 세션 시작 때 이름과 설명만 로드되고, 쓸 때 전체 내용이 로드된다. Claude Code 확장 기능 개요, Claude Code 스킬
• 스킬은 .claude/skills/에 지시·스크립트·리소스를 담은 폴더로 살고, 각 스킬의 SKILL.md에 frontmatter(이름·설명 등)와 본문이 있다. 본문은 슬래시 명령이나 작업 자동 매칭으로 호출할 때 로드된다. Steering Claude Code, Claude Code 스킬 블로그 글(2026-06-18)은 이 비용 등급을 Low로 적는다(블로그 평가). Steering Claude Code
• Claude는 작업을 스킬 설명과 맞춰 보고 어떤 스킬을 쓸지 정한다. 설명이 모호하거나 겹치면 엉뚱한 스킬을 부르거나 도움이 될 스킬을 놓칠 수 있다. 특정 스킬을 확실히 쓰게 하려면 /<name>으로 직접 부른다. Claude Code 확장 기능 개요
• 스킬 목록(이름과 설명)은 매 턴 컨텍스트에 더해진다. 목록은 모델 컨텍스트 창의 1% 문자 예산 안에 들어가야 하고, 넘치면 가장 덜 쓰는 스킬의 설명부터 빠진다. 스킬 하나의 description+when_to_use는 1,536자에서 잘리므로 핵심 용도를 앞에 쓴다. Claude Code 스킬 → 컨텍스트 비용
• 서브에이전트 안에서는 다르다. 서브에이전트의 skills: 필드에 적힌 스킬은 시작할 때 전체가 미리 로드된다. 적히지 않은 프로젝트·사용자·플러그인 스킬도 Skill 도구로 찾아 부를 수 있다. Claude Code 확장 기능 개요 공식 스킬 문서도 미리 로드된 스킬은 시작 때 전체 내용이 주입된다고 확인한다. Claude Code 스킬
• (2026-10-18 기준) 공식 서브에이전트 문서가 더하는 조건: 미리 로드는 목록 앞쪽 서로 다른 이름 32개까지다. 이 필드는 미리 로드할 스킬을 정할 뿐 접근을 막지 않으므로, 서브에이전트가 스킬을 아예 못 부르게 하려면 tools에서 Skill을 빼거나 disallowedTools에 넣는다. disable-model-invocation: true 스킬(번들 /verify 포함)은 미리 로드할 수 없고, 없거나 정책으로 꺼진 스킬은 건너뛰고 디버그 로그에 경고가 남는다. Claude Code 서브에이전트 → 서브에이전트 정의 파일 레퍼런스

자세한 비용 비교: 컨텍스트 비용

누가 부르는가#

기본값은 사용자와 Claude 둘 다 부를 수 있다. frontmatter 두 필드로 제한한다. Claude Code 스킬

근거: Claude Code 스킬

• disable-model-invocation: true: 부작용이 있거나 시점을 직접 정하고 싶은 워크플로(/commit, /deploy, /send-slack-message)용. 원본의 말로 "코드가 준비돼 보인다고 Claude가 배포를 정하게 두고 싶지 않다". Claude가 그래도 부르려 하면 Claude Code가 막고 다른 방법으로 배포 단계를 재현하지 말라고 지시한다. 이 설정은 서브에이전트 미리 로드와, 그 스킬을 프롬프트로 하는 예약 작업 실행도 막는다. Claude Code 스킬 확장 기능 개요 문서도 부작용이 있는 스킬에 이 설정을 권하고, 부르기 전까지 비용이 0이라고 한다. Claude Code 확장 기능 개요 공식 컨텍스트 창 문서의 예: disable-model-invocation: true인 /commit-push 스킬은 시작 때 스킬 목록에 없어 부르기 전까지 컨텍스트를 전혀 쓰지 않다가, 부르는 순간 전체 내용이 로드된다. 원본은 커밋·배포·메시지 전송처럼 부작용 있는 스킬에 이 설정을 두라고 한다(2026-10-18 기준). Claude Code 컨텍스트 창
• user-invocable: false: 명령으로는 의미 없는 배경 지식용. 예: 옛 시스템이 어떻게 돌아가는지 설명하는 legacy-system-context. 이 설정은 / 메뉴에서만 숨긴다. Claude가 Skill 도구로 부르지 못하게 하려면 disable-model-invocation: true를 쓴다. Claude Code 스킬
• 메시지 맨 앞에 /deploy staging처럼 쓰면 스킬이 바로 돈다. 일반 문장 뒤에 /deploy를 쓰면 바로 돌지 않고, 그 메시지에서 Claude가 스킬을 돌려도 된다는 허락으로만 쓰인다. 허락 없이 스킬 이야기만 하려면 슬래시를 뺀다. Claude Code 스킬
• 직접 쓰지 않은 스킬(공유 저장소에 체크인된 것 등)은 파일을 고치지 않고 설정의 skillOverrides로 가시성을 바꾼다. 값은 "on", "name-only"(이름만), "user-invocable-only", "off" 네 가지이고, /skills 메뉴에서 Space로 바꾸면 .claude/settings.local.json에 저장된다. 플러그인 스킬에는 적용되지 않는다. Claude Code 확장 기능 개요, Claude Code 스킬
• 권한 규칙으로도 막는다. Skill 도구를 deny하면 모든 스킬이 꺼지고, Skill(commit)(정확히), Skill(deploy *)(접두어)로 개별 허용·거부한다. Claude Code 스킬 → 권한 모드

불러온 뒤: 대화 안에서의 수명#

• 호출된 스킬의 렌더된 SKILL.md는 메시지 하나로 대화에 들어가 이후 턴에도 남는다. Claude Code는 이후 턴에 파일을 다시 읽지 않는다. 그래서 작업 내내 적용할 지침은 일회성 단계가 아니라 상시 지시로 쓴다("테스트를 돌려라" 대신 "편집할 때마다 테스트를 돌려라"). Claude Code 스킬
• 본문은 짧게 쓴다. 남아 있는 모든 줄이 반복되는 토큰 비용이기 때문이다. 어떻게·왜를 늘어놓지 말고 무엇을 할지 쓴다. Claude Code 스킬
• 같은 내용을 다시 부르면 두 번째 사본 대신 이미 로드됐다는 짧은 메모만 붙는다. 인자가 바뀌거나 동적 컨텍스트 출력이 달라 내용이 다르면 전체가 다시 붙는다. Claude Code 스킬
• allowed-tools로 준 도구 권한은 스킬 내용과 달리 다음 메시지를 보내면 사라진다. Claude Code 스킬

컴팩션 뒤 (2026-10-18 기준)#

컴팩션 때 Claude Code는 호출된 스킬을 총 예산 안에서 다시 붙인다. 한 세션에서 스킬을 많이 호출했다면 오래된 것부터 빠질 수 있다. Steering Claude Code 공식 스킬 문서가 같은 동작을 숫자로 확인한다. 스킬마다 가장 최근 호출의 앞 5,000토큰을 요약 뒤에 다시 붙이고, 다시 붙인 스킬 전체가 25,000토큰 예산을 나누며, 가장 최근에 호출한 스킬부터 채운다. 그래서 가장 중요한 지시는 SKILL.md 위쪽에 두고, 컴팩션 뒤 Claude가 스킬을 덜 따르면 다시 호출해 전체 내용을 복원한다. Claude Code 스킬 → 장기 작업 컨텍스트 관리, 스킬 문제 해결

공식 컨텍스트 창 문서도 같은 한도(스킬당 5,000토큰, 합계 25,000토큰, 오래된 것부터 빠짐)와 "잘릴 때 앞부분이 남으므로 중요한 지시를 위쪽에"를 확인하고, 한 가지를 더 밝힌다. 스킬 설명 목록은 다른 시작 내용과 달리 /compact 뒤에 다시 주입되지 않고, 실제로 호출한 스킬만 보존된다. Claude Code 컨텍스트 창

본문에 쓸 수 있는 장치 (2026-10-18 기준)#

• 보조 파일: 스킬 디렉터리에 reference.md, examples.md, scripts/를 두고 SKILL.md에서 무엇이 어디 있는지 링크한다. 큰 참고 문서는 필요할 때만 로드되고, 스크립트는 로드되지 않고 실행된다. SKILL.md는 500줄 이하로 유지하라는 팁이 있다. Claude Code 스킬
• 인자: $ARGUMENTS(전체), $ARGUMENTS[N]·$N(위치), arguments frontmatter로 선언한 $name. 받을 자리가 없으면 끝에 ARGUMENTS: <입력>이 붙는다. Claude Code 스킬
• 경로 변수: ${CLAUDE_SKILL_DIR}(스킬 폴더), ${CLAUDE_PROJECT_DIR}(프로젝트 루트), ${CLAUDE_SESSION_ID}, ${CLAUDE_EFFORT}. 이 중 ${CLAUDE_SKILL_DIR}와 ${CLAUDE_PROJECT_DIR}는 본문과 allowed-tools의 Bash 규칙 양쪽에서 치환되므로(플러그인 스킬은 ${CLAUDE_PLUGIN_ROOT}·${CLAUDE_PLUGIN_DATA}도), 같은 변수를 두 곳에 쓰면 번들 스크립트를 권한 확인 없이 돌릴 수 있다. Claude Code 스킬
• 동적 컨텍스트 주입: 줄 맨 앞(또는 공백 뒤)의 !`명령`이나 ```! 블록은 Claude가 보기 전에 실행되고 출력으로 바뀐다. 명령 하나가 실패하면 그 호출 전체가 중단되고, 권한 확인을 묻지 않고 규칙에 비춰 허용되지 않으면(자동 모드 밖) 중단된다. 설정 disableSkillShellExecution으로 끌 수 있다. Claude Code 스킬
• 실행 옵션: model은 그 턴 동안만 모델을 덮어쓰고(다음 프롬프트부터 세션 모델로 돌아감), effort는 스킬이 활성인 동안 세션 effort를 덮어쓴다. context: fork + agent는 서브에이전트에서 돌린다. hooks는 스킬을 부른 뒤 세션 끝까지 도는 훅을 등록한다. paths는 맞는 파일을 다룰 때만 자동 로드한다. Claude Code 스킬

전체 frontmatter 표와 예시: 업무 절차를 스킬로 만들기

다른 기능과의 경계#

근거: Claude Code 확장 기능 개요, 표의 "보고 조종" 구분은 Steering Claude Code

• vs 출력 스타일 (2026-10-18 기준): 릴리스 체크리스트나 리뷰 절차처럼 한 종류 작업의 지시는 스킬에 둔다. 스킬은 부르거나 작업이 맞을 때만 로드돼 관련 없는 응답을 바꾸지 않는다. 출력 스타일은 세션의 모든 응답에 적용된다. Claude Code 출력 스타일

• 훅과의 경계는 공식 스킬 문서도 같은 방향으로 말한다. 스킬에서 매번 지켜져야 하는 규칙을 Claude가 건너뛴다면 그 규칙을 훅으로 옮기고, 스킬과 함께 두고 싶으면 스킬의 hooks frontmatter에 정의한다. Claude Code 스킬 → 훅

• (2026-10-18 기준) 공식 훅 가이드도 스킬 frontmatter 훅의 범위를 "스킬을 부른 뒤 세션 끝까지"로 적는다. 사용자가 입력한 명령이 프롬프트로 펼쳐질 때 실행되는 UserPromptExpansion 훅은 스킬·명령 이름을 matcher로 받고 그 확장을 막을 수 있다. Claude Code 훅 가이드 → Claude Code 훅 설정 레시피

• (2026-10-18 기준) 공식 훅 레퍼런스가 더하는 것: Skill 도구에 맞춘 PreToolUse 훅은 Claude가 도구를 부를 때만 돌고, 사용자가 /skillname을 직접 입력하면 PreToolUse를 거치지 않는다. 그 경로는 UserPromptExpansion이 받는다. UserPromptSubmit 훅은 펼친 스킬 내용이 아니라 입력한 줄(예: /deploy staging)을 받고, 그 훅이 막으면 스킬의 !`<command>` 셸 주입도 돌지 않는다. 스킬 frontmatter 훅에는 첫 성공 뒤 지우는 once: true를 둘 수 있다. SessionStart 훅이 스킬 디렉터리에 스킬을 설치하면 탐색이 이미 끝났을 수 있으므로 reloadSkills: true로 같은 세션에서 다시 스캔하게 한다. ConfigChange의 skills matcher는 .claude/skills/의 스킬 파일 변경에 돈다. Claude Code 훅 레퍼런스 → 훅 이벤트 레퍼런스

.claude/rules/의 규칙 파일과도 경계가 있다. 규칙은 매 세션 또는 맞는 파일을 열 때 로드되고, 스킬은 부르거나 Claude가 프롬프트와 관련 있다고 판단할 때만 로드된다. 그래서 공식 메모리 문서는 항상 컨텍스트에 있을 필요가 없는 작업별 지시나 여러 단계 절차는 스킬로 두라고 한다. Claude Code 메모리 → CLAUDE.md 작성·구성

조합#

• 스킬은 context: fork로 격리된 컨텍스트에서 돌 수 있고, 서브에이전트는 skills: 필드로 스킬을 미리 실을 수 있다. Claude Code 확장 기능 개요 공식 스킬 문서는 두 방향을 이렇게 구분한다. Claude Code 스킬

  방식	시스템 프롬프트	할 일	함께 로드
  context: fork 스킬	agent 유형의 것	SKILL.md 내용	그 agent의 시작 컨텍스트에 따른 CLAUDE.md
  skills 필드를 단 서브에이전트	서브에이전트 마크다운 본문	Claude의 위임 메시지	미리 로드된 스킬 + CLAUDE.md

  세부: 서브에이전트

• 스킬 + 서브에이전트: /audit 스킬이 보안·성능·스타일 서브에이전트를 띄워 병렬로 일하게 한다. Claude Code 확장 기능 개요

• 스킬 + MCP: MCP가 DB에 연결하고, 스킬이 스키마와 쿼리 패턴을 문서화한다. Claude Code 확장 기능 개요

• CLAUDE.md + 스킬: CLAUDE.md에는 "API 관례를 따르라", 스킬에는 전체 API 스타일 가이드. Claude Code 확장 기능 개요

• 스킬 + 스크립트: 스킬은 어떤 언어의 스크립트든 묶어 돌릴 수 있다. 원본 예는 코드베이스 구조를 접고 펼 수 있는 HTML 트리로 만드는 스크립트이고, 같은 패턴을 의존성 그래프, 테스트 커버리지 보고서, DB 스키마 시각화에 쓸 수 있다. 스크립트가 일을 하고 Claude는 조율을 맡는다. Claude Code 스킬

절차형 지시는 CLAUDE.md가 아니라 스킬에 둔다. 공식 스킬 문서도 CLAUDE.md의 한 절이 사실이 아니라 절차로 자라면 스킬을 만들라고 한다(2026-10-18 기준). Steering Claude Code, Claude Code 스킬 (2026-06-18 기준) 블로그 글의 예: 배포 워크플로, 릴리스 체크리스트, 리뷰 절차. Steering Claude Code → Claude Code 확장 기능 고르기

(2026-10-26 기준) 번들 스킬 /code-review는 현재 diff나 넘긴 PR 번호·브랜치·경로를 정확성 버그 기준으로 리뷰하고, --fix를 주면 찾은 문제를 Claude가 적용한다. --comment는 결과를 GitHub PR·GitLab merge request에 올리고, ultra는 클라우드에서 깊게 리뷰한다. /review는 별칭이다. Claude Code 명령어 레퍼런스 → Claude Code 슬래시 명령

(2026-06-18 기준) 스킬과 훅은 멈춤 조건을 만날 때까지 반복하는 에이전트 루프를 설계하는 구성 요소이기도 하다. Steering Claude Code

평가와 공유 (2026-10-18 기준)#

• 스킬이 트리거되는 것을 봤다는 건 Claude가 찾았다는 뜻일 뿐 의도대로 일했다는 뜻이 아니다. 부를 프롬프트에서 부르는지와, 불렀을 때 결과가 기대와 맞는지를 따로 잰다. Claude Code 스킬 → 업무 절차를 스킬로 만들기
• 공유 범위: 프로젝트 스킬은 .claude/skills/를 버전 관리에 커밋, 플러그인은 플러그인의 skills/ 디렉터리, 조직 전체는 managed settings로 배포. Claude Code 스킬 → 플러그인
• 조직 통제(2026-10-18 기준): managed strictPluginOnlyCustomization은 user·project 출처의 스킬을 막을 수 있고(true면 스킬·에이전트·훅·MCP 넷 다, 배열이면 지정한 것만), syncClaudeAiSkills는 어느 관리자 출처든 false면 claude.ai 스킬 동기화를 끈다. 개발자의 user·local 설정의 false도 끄며, 이 키는 끄기만 할 수 있다. Claude Code managed settings 배포 → managed settings
• (2026-10-21 기준) settings reference의 스킬 키: disableSkillShellExecution: true는 user·project·플러그인·추가 디렉터리 스킬과 커스텀 명령의 인라인 셸을 실행하지 않고 [shell command execution disabled by policy]로 바꾼다. managed의 true는 다른 파일의 false로 덮지 못하고, 번들 스킬과 managed로 배포한 스킬은 영향을 받지 않는다. disableBundledSkills는 번들 스킬·워크플로를 없애고 /init 같은 내장 명령은 입력은 되지만 모델에 숨긴다. 목록 예산 skillListingBudgetFraction 기본값은 0.01(컨텍스트 창 1%), 스킬당 설명 상한 skillListingMaxDescChars 기본값은 1536으로 스킬 문서와 같다. syncClaudeAiSkills는 Scope가 User, local, or managed(와 --settings)라 공유 .claude/settings.json으로는 끌 수 없고, user·managed에서 끄면 이미 받은 스킬을 ~/.claude/skills/.trash/로 옮긴다. managed allowManagedPermissionRulesOnly가 켜지면 v2.1.282 이상은 저장소·사용자·--add-dir 출처 스킬의 allowed-tools를 무시한다. Claude Code 설정 키 전체 레퍼런스 → Claude Code 설정 키 레퍼런스
• 직무별 플러그인 안의 스킬(2026-10-18 기준): Anthropic의 Knowledge Work Plugins README는 스킬이 도메인 전문성, 모범 사례, 단계별 워크플로를 담고 관련 있을 때 Claude가 자동으로 쓴다고 설명하고, 같은 플러그인 안의 commands/(직접 부르는 명령)와 구분한다. 회사에 맞추려면 스킬 파일에 회사 용어, 조직 구조, 프로세스를 넣고 스킬 지시를 팀의 실제 방식에 맞게 고친다. Knowledge Work Plugins 저장소 → 업무 플러그인 설치·맞춤화
• 목록의 모든 스킬은 쓰든 안 쓰든 매 턴 컨텍스트를 더한다. /skill-doctor(v2.1.252 이상)가 스킬별 비용과 사용 빈도를 보여 주고, 한 번도 호출되지 않은 스킬과 끌 위치를 알려 준다. Claude Code 스킬

문제가 생겼을 때: 스킬 문제 해결