Claude Code Skills 운용, 이렇게 하면 정답 — 슬래시 명령어 통합 이후의 새 상식과 실전 레시피 6선

들어가며: CLAUDE.md 비대화와 커맨드 둘 곳 때문에 고민하고 있지 않나요

"CLAUDE.md에 규칙을 계속 덧쓴 결과, 매번의 대화에서 컨텍스트를 압박하고 있다" "2026년 1월에 커스텀 슬래시 명령어가 Skills로 통합됐다고 들었는데, 기존 .claude/commands/ 는 어떻게 하면 좋을지 모르겠다" "편리한 절차서를 개인적으로 만들었지만, 팀에 배포하는 방법과 통제 방식이 정해져 있지 않다"

Claude Code를 몇 달 쓴 팀은 대개 이 세 가지 과제에 다다릅니다. 결론부터 말하면, 이 셋은 전부 Agent Skills(이하 Skills)로 해결됩니다. Skills는 작업별 절차서를 파일로 Claude Code에 쥐여 두고, 필요할 때만 읽어 들이게 하는 공식 기능입니다. CLAUDE.md는 쓴 내용 전문이 매번 읽히지만, Skills는 컨텍스트(Claude가 한 번에 읽어 들일 수 있는 정보의 틀)를 거의 쓰지 않아요. 그래서 절차서를 수십 개라도 쥐여 둘 수 있습니다.

이 글에서는 슬래시 명령어 통합 이후의 "새 상식"을 정리한 뒤, 복붙으로 움직이는 자작 스킬 레시피와 팀 배포·통제까지 다룹니다. 사양 설명은 전부 Anthropic 공식 문서(Claude Code Skills 레퍼런스)에, 동작 설명은 전부 실기 검증에 근거를 뒀습니다(검증 환경은 글 말미에 기재).

이 글을 읽으면 얻는 것

• Skills의 구조(3단계 읽기)와 CLAUDE.md·Hooks·서브에이전트와의 구분법
• 슬래시 명령어 통합으로 바뀐 것·기존 .claude/commands/ 의 취급
• 커밋 메시지 규약·문체 체크·읽기 전용 감사 등 그대로 쓸 수 있는 스킬 레시피
• 서브에이전트 분리 실행(context: fork)·발동 범위 한정(paths) 등 2026년에 추가된 신기능의 쓸 자리
• Git 공유·조직 설정을 통한 팀 배포와, 외부 제작 스킬을 도입할 때의 감사 관점

1. 기초 지식: Agent Skills란 무엇인가

1-1. CLAUDE.md의 한계와 "단계적 읽기"

Skills의 실체는 SKILL.md라는 이름의 Markdown 파일을 넣은 폴더입니다. 여기에 절차서를 써 두면 Claude가 필요하다고 판단했을 때만 읽어 들입니다. 2025년 10월 16일에 claude.ai·Claude Code·Claude API 세 곳에서 동시 출시됐고, 2025년 12월에는 오픈 표준(agentskills.io)이 되었습니다. 오픈 표준이란 어느 회사의 툴에서든 쓸 수 있는 공통 작성법을 말해요. 현재는 VS Code나 Codex CLI 등 Anthropic 외의 툴도 같은 SKILL.md를 읽을 수 있어서, 한 번 쓴 절차서는 오래가는 자산이 됩니다.

CLAUDE.md와의 가장 큰 차이는 컨텍스트를 쓰는 방식입니다. Skills는 필요해질 때까지 상세를 읽지 않는 단계적 읽기(공식 문서에서는 progressive disclosure)라는 3단계 설계로 되어 있습니다.

스킬(Skill) 로딩 단계별 컨텍스트 소비

토큰 기준치는 공식 문서(Agent Skills Overview)의 기재에 근거합니다. 토큰은 Claude가 읽고 쓰는 문장량의 단위입니다(한국어에서는 대략 1~2자에 1토큰). 예를 들어 절차서 10개·합계 2만 토큰 분량을 CLAUDE.md에 직접 쓰면 매번 2만 토큰이 읽힙니다. Skills로 만들면 평소 읽히는 것은 1개당 약 100토큰(이름과 설명문)뿐이라, 합계로도 대략 1,000토큰이면 되는 계산입니다.

1-2. 슬래시 명령어 통합의 새 상식(2026년 1월~)

Claude Code에서는 오랫동안 .claude/commands/*.md 에 커스텀 슬래시 명령어를 두는 방식이 쓰여 왔지만, 2026년 1월 말(v2.1.3)에 커스텀 슬래시 명령어가 Skills로 통합되었습니다. 챙겨야 할 사실은 네 가지입니다.

1. 기존 .claude/commands/ 는 지금도 동작합니다. 이전은 필수가 아닙니다.
2. .claude/commands/review.md 와 .claude/skills/review/SKILL.md 는 둘 다 같은 /review 커맨드를 만듭니다. 동명으로 공존할 경우 Skills 쪽이 우선됩니다.
3. 구 commands도 "자동 발동"하게 되었습니다. 통합 전에는 기본적으로 직접 /이름 을 쳤을 때만 움직였습니다. 통합 후에는 스킬의 설명문=description(설명문이 없는 파일에서는 본문 1행째가 설명문 취급)에 대화 내용이 맞으면, 부탁하지 않아도 Claude가 자동으로 실행합니다.
4. 보조 파일 동봉·발동 제어·서브에이전트 연계 같은 신기능은 Skills 쪽에만 추가됩니다. 새로 만드는 것은 Skills로 쓰세요.

3번이 실무상 가장 큰 주의점입니다. 배포나 파일 생성처럼 멋대로 실행되면 곤란한 절차에는, frontmatter(파일 첫머리를 --- 로 감싸 쓰는 스킬 설정란)에 disable-model-invocation: true 를 붙이세요. 이렇게 하면 직접 불렀을 때만 움직이는 상태로 돌릴 수 있습니다(작성법은 2장에서 설명).

참고로 웹판 Claude(claude.ai)에도 Word와 Excel을 다루는 "Skills"가 있습니다. 사양은 같은 표준에 기반하지만, 플랫폼 간에 스킬은 동기화되지 않습니다. 이 글은 Claude Code에서 자작하는 스킬로 좁힙니다.

1-3. CLAUDE.md·Hooks·서브에이전트와의 구분법

Skills의 역할은 "필요할 때만 읽는 절차서"입니다. 비슷한 기능이 그 밖에도 있으니 구분을 정리합니다. 서브에이전트는 메인 대화와 별도로 세워지는 또 하나의 Claude를 말합니다.

Claude Code 주요 기능 비교

Skills는 어디까지나 LLM에 대한 지시라 확실한 강제는 못 합니다. 확실히 멈추고 싶은 처리는 Hooks와 조합합니다(3-5 레시피에서 실연).

2. 구현 단계: 첫 스킬을 10분 만에 만든다

스킬 만드는 법은 "파일을 둔다 → 발동을 설계한다 → 보조 파일을 더한다"의 3단계입니다. 예시로 커밋 메시지 규약 스킬을 만듭니다.

어떤 스킬인지 먼저 설명할게요. 커밋 전에 /commit-msg 라고 치면, Claude가 스테이징된 변경(git add 한 변경)의 내용을 읽고, 팀의 서식 규약(1행째는 "종류: 요약", 본문에 변경 이유를 1~2행)에 맞춘 커밋 메시지 안을 돌려줍니다. 사람은 돌아온 안을 확인해 그대로 커밋에 쓰기만 하면 됩니다. 커밋 메시지 서식은 사람마다 흔들리기 쉽고 규약을 매번 떠올리기도 귀찮으니, 절차서로 만들어 둘 가치가 있어요.

먼저 2-1에서 이 스킬을 완성합니다. 이어지는 2-2와 2-3에서는 나머지 두 단계(발동 설계·보조 파일 동봉)의 사고방식을 설명합니다.

2-1. 최소한의 SKILL.md를 둔다

프로젝트 바로 아래에 다음 폴더와 파일을 만들기만 하면 /commit-msg 커맨드를 쓸 수 있게 됩니다.

.claude/
└── skills/
    └── commit-msg/
        └── SKILL.md

---
name: commit-msg                                  # 목록에 표시되는 표시명(커맨드명은 폴더명으로 정해진다)
description: 스테이징된 변경에서 커밋 메시지 안을 작성한다   # 스킬 설명문(자동 발동 스킬에서는 발동 판정에 쓰인다)
disable-model-invocation: true                    # 자동 발동을 금지하고 /commit-msg 전용으로 만든다
argument-hint: "[보충하고 싶은 변경 의도(선택)]"        # /commit-msg 를 골랐을 때 입력란에 뜨는 기입 예시
---

## 참조 정보

- 스테이징된 변경 사항(diff) 개요: !`git diff --staged --stat`

## 태스크

위 변경 사항을 바탕으로, 다음 규약에 맞춰 커밋 메시지를 하나 제안해 주세요.
변경 내용의 상세가 필요하면 `git diff --staged` 로 확인해 주세요.

- 1행째: `종류: 요약`(종류는 feat / fix / docs / refactor 중 하나. 1행째는 50자 이내)
- 본문: 왜 그 변경을 했는지를 1~2행으로 쓴다
- 사용자의 보충: $ARGUMENTS

파일 구조는 2부 구성입니다. 첫머리의 --- 로 감싼 부분이 frontmatter(스킬의 동작 방식을 정하는 설정란), 그 아래가 스킬 발동 시 Claude에 넘겨지는 지시 본문입니다. frontmatter 각 필드의 의미는 코드 안 주석과 같고, 이후 레시피도 전부 이 구조로 씁니다.

이 레시피에는 스킬의 기본 요소가 4가지 들어 있습니다.

• !커맨드(앞에 ! 를 붙이고 백쿼트로 감싸는 작성법)를 통한 커맨드 출력 삽입: 본문이 Claude로 보내지기 직전에 셸 커맨드가 실행되고, 쓴 자리가 실행 결과로 바뀝니다. 변경 사항이나 브랜치명 등 "지금의 상태"를 절차서에 자동으로 끼워 넣을 수 있습니다.
• $ARGUMENTS: "/commit-msg 티켓 번호를 넣어 줘"처럼 쳤을 때, 커맨드명 뒤에 쓴 문자(=인수)가 그대로 들어가는 자리입니다. 인수를 하나씩 꺼내고 싶을 때는 $0 $1 이라고 씁니다. 번호는 0부터 세므로 "/commit-msg 123 수정"이라면 $0 이 123, $1 이 수정입니다. frontmatter의 arguments 로 인수에 이름을 붙이는 방식도 있습니다(arguments: [issue, branch] 라고 정의하면 본문에서 $issue $branch 라고 쓸 수 있습니다).
• argument-hint: 입력란에서 /commit-msg 를 골랐을 때, 뒤에 뭘 쓰면 되는지의 기입 예시로 흐리게 표시되는 문자열입니다. 스킬 동작은 바꾸지 않고 쓰는 사람에게 안내만 합니다.
• disable-model-invocation: true: 커밋 메시지 작성은 원치 않는 타이밍에 자동 실행되면 방해가 되므로, 명시 호출 전용으로 해 뒀습니다.

2-2. 자동 발동을 설계한다(description 작성법)

자동 발동시키고 싶은 스킬에서는 반대로 disable-model-invocation 을 붙이지 않고 description 작성법을 공들여 다듬습니다. Claude는 각 스킬의 description만 보고 "지금 이 절차서가 필요한가"를 판단하기 때문입니다.

• "무엇을 하는 스킬인가"에 더해 "언제 쓰는가"를 쓴다(예: "~할 때 쓴다"). 보조 필드 when_to_use 도 병용할 수 있습니다
• 스킬 목록에서는 description과 when_to_use의 합계가 1,536자에서 잘리므로, 중요한 쓸 자리를 앞머리에 씁니다

또한 disable-model-invocation: true 를 붙인 스킬은 description조차 상주하지 않게 되므로, 컨텍스트 절약 관점에서도 "자동 발동이 불필요한 것에는 반드시 붙인다"가 새 상식입니다.

2-3. 보조 파일과 스크립트를 동봉한다

스킬 폴더에는 SKILL.md 외의 파일도 둘 수 있습니다. 공식이 권장하는 구성은 다음과 같습니다.

skill-name/
├── SKILL.md          # 절차의 본체(500행 미만 권장)
├── reference.md      # 상세한 사양·규약(필요 시 Claude가 읽는다)
├── examples.md       # 입출력 실례
└── scripts/
    └── collect.py    # 집계 등 정해진 처리

포인트는, 참조 파일은 Claude가 필요하다고 판단해 읽었을 때만 컨텍스트에 들어가고, 스크립트는 실행 결과 출력만 들어간다는 점입니다. 매번 같은 절차면 되는 처리는 스크립트로 만들어 두면 컨텍스트를 쓰지 않고 결과도 매번 같아집니다. 이 사용법은 3장 레시피에서 실연합니다.

3. 응용·발전: 실용 레시피집과 팀 운용

여기서부터가 이 글의 중심입니다. 용도별 레시피를 소개합니다. 모두 실제로 돌려서 동작을 확인했습니다(검증 환경은 글 말미에 기재).

3-1. 레시피 1: 문체 체크 /review-style(참조 파일 동봉)

사내 문장 규약을 references/에 넣어 두고, 문서 집필 시 자동 발동시키는 스킬입니다.

---
name: review-style                # 목록에 표시되는 표시명
description: 블로그 글과 대외 문서의 문체를 체크한다. 문장의 리뷰·퇴고를 부탁받았을 때 쓴다   # "무엇을 하는가+언제 쓰는가"로 자동 발동시킨다
---

대상 문장을 references/style-guide.md 의 규약에 비추어 리뷰하고,
위반 부분을 "원문 → 수정안 → 근거가 되는 규약 번호" 형식으로 나열해 주세요.

규약 전문(수천 자여도 가능)은 references/style-guide.md 에 둡니다. 이 참조 파일은 1-1에서 보인 단계적 읽기의 **레벨 3(보조 파일)**에 해당해 필요해졌을 때만 읽힙니다. 그래서 CLAUDE.md에 쓰는 것과 달리 코딩 작업 중의 컨텍스트를 일절 소비하지 않아요. 실제로 /review-style 이라 치지 않아도 "이 문장을 퇴고해 주세요"라고 부탁하기만 하면 이 스킬이 자동 발동해 규약 번호가 붙은 지적이 돌아옵니다. description에 "언제 쓰는가"를 쓴 효과입니다(2-2 참조).

3-2. 레시피 2: 읽기 전용 보안 감사 /security-audit(쓰기·실행계 툴 제외)

disallowed-tools 를 쓰면 스킬 실행 중 Claude가 쓸 수 있는 툴(파일 편집·커맨드 실행 등의 조작 수단)을 줄일 수 있습니다. 쓰기·실행계 툴을 빼 두면 "조사는 하되 변경은 하지 않는다"를 구조로 보장할 수 있어요.

---
name: security-audit                # 목록에 표시되는 표시명
description: 리포지토리 내 기밀 정보 혼입과 위험한 설정을 점검한다   # 설명문
disable-model-invocation: true      # 감사는 명시적으로 실행한다
disallowed-tools: Edit, Write, NotebookEdit, Bash, PowerShell   # 이 스킬 실행 중에는 쓰기·실행계 툴을 못 쓰게 한다
---

리포지토리를 다음 관점으로 점검하고, 위험도가 높은 순으로 보고해 주세요. 수정은 하지 마세요.

1. API 키나 패스워드로 보이는 문자열이 하드코딩(코드 안에 직접 기술)되어 있지 않은가
2. .env 등 기밀 파일이 .gitignore 에서 빠져 있지 않은가
3. 설정 파일에서 필요 이상으로 넓은 권한이 허용되어 있지 않은가

프롬프트에 "수정하지 마"라고 쓰는 것만으로는 Claude가 지시를 잘못 읽었을 때 못 막습니다. 툴을 못 쓰는 상태로 해 두면 잘못 읽어도 쓸 방법이 없어요. 실제로 이 스킬 실행 중에 Write 툴로 쓰기를 시도하게 해도, 권한 오류로 거부되어 파일은 만들어지지 않습니다. 참고로 뺄 툴은 환경에 맞춰 고릅니다. Windows에는 Bash 와 별개로 PowerShell 툴(PowerShell 커맨드를 직접 실행하는 툴)이 활성화된 환경이 있습니다(공식 툴 레퍼런스에 목록이 있습니다). 이 환경에서 Bash 만 빼면 PowerShell 경유 셸 실행이라는 빠져나갈 길이 남습니다. 위 예시에 PowerShell 을 포함해 둔 것은 이 때문입니다.

한 가지 주의가 있습니다. 비슷한 이름의 allowed-tools 는 "나열한 툴을 확인 없이 쓸 수 있게 미리 허가해 두는" 필드이고, 그 외의 툴을 못 쓰게 하는 효과는 없습니다. 툴을 못 쓰게 하는 것은 disallowed-tools 입니다. 여기를 헷갈리면 읽기 전용인 줄 알았던 감사 스킬이 실제로는 쓰기 가능한 상태로 움직입니다.

3-3. 레시피 3: 주간 보고 초안 /weekly-report(스크립트 동봉)

집계는 스크립트에 맡기고 Claude에게는 문장화만 시키는 분업형 레시피입니다.

---
name: weekly-report                 # 목록에 표시되는 표시명
description: 이번 주 커밋 이력에서 주간 보고 초안을 작성한다   # 설명문
disable-model-invocation: true      # 주간 보고는 명시적으로 실행한다
---

1. `python ${CLAUDE_SKILL_DIR}/scripts/collect_commits.py` 를 실행해 주세요
2. 출력된 커밋 목록을 "이번 주 한 일/다음 주 할 일/과제"의 3부 구성으로 정리해 주세요

# scripts/collect_commits.py
import subprocess

# 자신의 Git 사용자명을 가져온다
name = subprocess.run(
    ["git", "config", "user.name"], capture_output=True, text=True
).stdout.strip()

# 최근 7일치 자신의 커밋을 "날짜 메시지" 형식으로 가져온다
log = subprocess.run(
    ["git", "log", "--since=7.days", f"--author={name}",
     "--pretty=format:%ad %s", "--date=short"],
    capture_output=True, text=True,
)

print(log.stdout)   # 표준 출력 내용만 Claude의 컨텍스트에 들어간다

${CLAUDE_SKILL_DIR} 는 "이 스킬의 폴더"를 가리키는 변수입니다. 이걸 써 두면 스킬을 어디에 두어도 스크립트를 올바르게 찾습니다. 스크립트 본체 코드는 컨텍스트에 들어가지 않으니, 집계 처리가 아무리 길어져도 컨텍스트 소비는 늘지 않습니다.

3-4. 레시피 4: 조사를 서브에이전트로 분리 /deep-research(context: fork)

2026년에 추가된 context: fork 를 쓰면 스킬을 서브에이전트(메인 대화와 별개의 Claude)로 실행할 수 있습니다. 조사에서 대량의 파일을 읽어도, 읽은 내용은 서브에이전트 쪽에 쌓이므로 메인 대화의 컨텍스트를 소비하지 않습니다.

---
name: deep-research    # 목록에 표시되는 표시명
description: 지정 테마에 대해 코드베이스를 철저히 조사한다   # 설명문
context: fork          # 메인 대화에서 분리한 서브에이전트로 실행
agent: Explore         # 실행에 쓸 에이전트 종류(읽기 특화 Explore)
---

$ARGUMENTS 에 대해 다음 순서로 조사해 주세요.

1. 파일명 검색(Glob 툴)과 본문 검색(Grep 툴)으로 관련 파일을 찾아낸다
2. 주요 파일을 읽고 구현을 파악한다
3. 파일 경로와 행 번호를 붙여 발견 사항을 요약해 보고한다

agent 에는 Explore 외에 Plan·general-purpose·자작 서브에이전트명을 지정할 수 있습니다. 중간 경과는 필요 없고 결론만 원하는 조사에 알맞습니다.

3-5. 레시피 5: Hooks와 조합한 가드레일 딸린 배포

절차서(스킬 본문)는 Claude에 대한 부탁이라, 잘못 읽거나 예외로 깨질 가능성이 남습니다. 깨지면 사고가 되는 금지 사항은 1-3에서 정리했듯 Hooks(정한 처리를 반드시 실행하는 구조)에 맡깁니다. 이 레시피에서는 "배포 절차"를 스킬에, "main 브랜치 외에서의 배포 금지"를 Hooks에 분담시킵니다.

먼저 스킬 본체는 절차서에 전념시킵니다.

---
name: deploy-staging                      # 목록에 표시되는 표시명
description: 스테이징 환경으로 배포한다   # 설명문
disable-model-invocation: true            # 배포는 반드시 사람이 기동한다
---

다음 순서로 스테이징에 배포해 주세요.

1. 테스트를 실행하고, 실패가 있으면 중단하고 보고한다
2. `./deploy.sh staging` 을 실행한다
3. 배포 후 헬스 체크 결과를 보고한다

다음으로 브랜치 검증 훅 스크립트를 .claude/hooks/check-branch.sh 에 둡니다.

#!/bin/bash
# main 브랜치가 아니면 exit 2 를 반환해 툴 실행 자체를 차단한다
branch=$(git rev-parse --abbrev-ref HEAD)   # 현재 브랜치명을 가져온다
if [ "$branch" != "main" ]; then
  echo "차단: main 브랜치 외에서는 배포할 수 없습니다(현재: $branch)" >&2
  exit 2                                    # exit 2 가 차단 신호
fi
exit 0                                      # main 이면 통과

마지막으로 이 스크립트를 .claude/settings.json 의 Hooks에 등록합니다.

해설용(주석 포함. JSON은 주석 불가라 이대로는 못 씁니다):

{
  "hooks": {
    "PreToolUse": [            // 툴 실행 직전에 끼어드는 이벤트
      {
        "matcher": "Bash",     // Bash 툴 실행만 대상으로 한다
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/check-branch.sh" }   // exit 2 면 차단
        ]
      }
    ]
  }
}

붙여넣기용(.claude/settings.json 에 그대로 쓸 수 있습니다):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "bash .claude/hooks/check-branch.sh" }
        ]
      }
    ]
  }
}

실제로 develop 브랜치에서 /deploy-staging 을 실행하면, 순서 1의 테스트 실행에 들어가기 전에 Hooks가 차단해 "차단: main 브랜치 외에서는 배포할 수 없습니다(현재: develop)"라고 표시됩니다. main 브랜치에서는 그대로 통과합니다. 스킬만으로는 "부탁" 수준이던 금지 사항이 Hooks와의 조합으로 확실한 강제가 됩니다.

참고로 이 예시의 matcher는 Bash 전체를 대상으로 하기 때문에, main 외의 브랜치에서는 배포와 무관한 커맨드 실행도 멈춥니다. 배포 전용 리포지토리 외에서 쓸 경우에는 훅 스크립트 쪽에서 "커맨드에 deploy.sh 가 포함될 때만 차단한다"처럼 조건을 좁히세요. 또 3-2에서 설명한 PowerShell 툴이 활성화된 환경에서는 matcher가 Bash 뿐이면 PowerShell 경유 커맨드 실행을 못 막습니다. 둘 다 대상으로 하려면 "matcher": "Bash|PowerShell" 이라고 씁니다.

공식 문서에는 스킬의 frontmatter에 hooks 를 써서 "그 스킬 실행 중에만 유효한 Hooks"를 동봉하는 방식(스킬 한정 Hooks)도 기재되어 있습니다. 검증 환경(글 말미)에서 따로 떼어 검증해 본 결과, 이 방식으로도 등록한 커맨드 자체는 실행되지만 종료 코드 2에 의한 차단은 통하지 않았습니다(완전히 같은 내용을 settings.json에 쓰면 차단됩니다). 한편 커맨드 출력을 JSON 형식 판정(permissionDecision: "deny")으로 바꾸면 스킬 한정 Hooks에서도 차단되는 것을 확인했습니다. 다만 환경에 따라 스킬 한정 Hooks 자체가 안 돈다는 보고도 공식 리포지토리에 여럿 있으므로(예: anthropics/claude-code Issue #39468), 확실히 멈추고 싶은 용도에서는 이 레시피처럼 settings.json 쪽에 두는 것이 안전합니다.

3-6. 레시피 6: paths 로 발동 범위를 디렉터리 한정

모노레포(하나의 리포지토리에 여러 앱과 서비스를 모은 구성)에서는 프런트엔드 규약 스킬이 백엔드 작업 중에도 발동 후보에 올라 버립니다. paths 를 지정하면 조건에 맞는 파일을 다룰 때만 스킬이 자동 발동 대상이 되어 이 낭비를 없앨 수 있습니다.

---
name: component-conventions   # 목록에 표시되는 표시명
description: React 컴포넌트 구현 규약. 컴포넌트 신규 작성·수정 때 쓴다   # 설명문
user-invocable: false        # 사용자가 / 로 부를 필요 없는 배경지식형 스킬
paths:                       # 합치하는 경로를 나열(자동 발동 범위 한정)
  - "src/components/**"      # 이 경로 아래를 다룰 때만 발동 후보가 된다
---

컴포넌트를 작성·수정할 때는 다음 규약을 따라 주세요.

- 하나의 파일에는 하나의 컴포넌트만 쓴다
- 색과 여백 등 스타일은 전용 CSS 파일에 쓰고, 컴포넌트 안에 직접 쓰지 않는다

user-invocable: false 를 더하면 / 목록에서 사라져 사람은 부를 수 없게 됩니다. Claude가 해당 폴더의 파일을 다룰 때만 자동으로 참조되는, 무대 뒤에서 일하는 규약 스킬이 되는 거죠. 실제로 src/components/ 아래 파일 수정을 상의하면 Claude가 이 스킬의 규약 2가지를 먼저 꺼내 듭니다. 무관한 파일 상담에서는 발동하지 않습니다.

3-7. 기존 .claude/commands/ 의 목록 점검과 이전 판단

통합 후의 동작 변화(1-2)를 감안하면, 갖고 있는 기존 commands 파일은 다음 기준으로 하나씩 확인해 가는 것이 효율적입니다.

기존 파일 상태별 Skills 전환 가이드

이전 작업 자체는 .claude/commands/review.md 를 .claude/skills/review/SKILL.md 로 옮기기만 하면 됩니다. 동명 공존 중에는 Skills 쪽이 우선되므로 이전 기간 중 이중 실행될 걱정은 없습니다.

3-8. 팀 배포와 통제

개인이 만들어 다듬은 스킬을 팀으로 넓히는 경로는 세 가지입니다.

1. Project 스킬(.claude/skills/)을 Git에 커밋한다: 리포지토리를 clone한 전원에게 같은 스킬이 배포됩니다. 우선은 이걸로 충분합니다
2. Plugin으로 배포한다: 여러 리포지토리에서 공통으로 쓰는 스킬 묶음은 플러그인화해 마켓플레이스 경유로 배포합니다
3. managed settings(조직 관리자 설정)로 배포한다: 전사 필수 스킬을 관리자가 일괄 배포합니다. 동명 스킬의 우선순위는 "Enterprise > Personal > Project"입니다

managed settings를 쓰려면 조직 플랜 도입이 전제가 됩니다.

배포뿐 아니라 좁히는 쪽 기능도 있습니다. 자작 스킬이라면 frontmatter에 disable-model-invocation: true 를 쓰면 자동 발동을 멈출 수 있습니다. 그러나 관리자나 플러그인에서 배포된 스킬은 SKILL.md를 직접 편집할 수 없습니다(편집해도 배포처 갱신으로 되돌아갑니다). 그때 쓰는 것이 settings.json의 skillOverrides 입니다. 스킬 본체를 건드리지 않고 받는 쪽에서 스킬별 보이는 방식을 4단계(on=보통 / name-only=이름만 / user-invocable-only=사람만 부를 수 있음 / off=무효)로 바꿀 수 있습니다. 더 강하게 멈추고 싶다면 Permission 규칙의 Skill(이름) 을 쓰면 실행 자체를 허가·거부할 수 있습니다. skillOverrides 가 "어떻게 보일까", Permission 규칙이 "실행시킬까"의 담당입니다.

해설용(주석 포함. JSON은 주석 불가라 이대로는 못 씁니다):

{
  "skillOverrides": {                         // 키에 스킬명을 쓰고 그 스킬에만 적용한다
    "deploy-staging": "user-invocable-only",  // 자동 발동을 금지하고 사람만 / 로 부를 수 있는 상태로 만든다
    "legacy-notes": "off"                     // 스킬을 완전히 무효화한다
  }
}

붙여넣기용(.claude/settings.json 에 그대로 쓸 수 있습니다):

{
  "skillOverrides": {
    "deploy-staging": "user-invocable-only",
    "legacy-notes": "off"
  }
}

스킬 본문의 !커맨드 실행 자체를 조직 차원에서 금지하고 싶다면, managed settings에서 disableSkillShellExecution: true 를 설정합니다.

3-9. 보안: 외부 제작 스킬은 "소프트웨어 설치"로 취급한다

스킬은 셸 실행과 파일 접근을 동반하기 때문에, Anthropic 공식도 "신뢰할 수 있는 소스(자작 또는 Anthropic 제공)의 스킬만 쓸 것"이라고 명확히 주의를 환기하고 있습니다. GitHub에 공개된 스킬 모음을 도입할 경우에는 최소한 다음을 감사하세요.

• SKILL.md 본문·스크립트에 외부 URL로 데이터를 보내는 처리가 포함되어 있지 않은가
• !커맨드 나 scripts/ 가 스킬 목적과 무관한 파일(인증 정보 등)에 접근하고 있지 않은가
• description이 실제 처리 내용과 일치하는가(목적을 위장한 스킬은 툴의 목적 외 이용으로 이어집니다)

스킬은 기밀 정보를 포함한 리포지토리에서도 동작합니다.

외부에서 가져온 데이터에 악의적인 지시가 섞이는 문제는 스킬에 국한되지 않는, AI 에이전트 전반의 공통 과제입니다.

4. 정리와 결론

• Skills는 "필요할 때만 읽히는 절차서". 상주는 스킬당 약 100토큰의 메타데이터뿐으로, CLAUDE.md 비대화 문제를 구조적으로 해결합니다
• 슬래시 명령어 통합 후의 새 상식은 두 가지. 새로 만드는 것은 Skills로 통일하고, 부작용 있는 절차에는 disable-model-invocation: true 를 반드시 붙입니다(구 commands도 자동 발동하게 되었으므로)
• 2026년 확장 기능으로 용도가 넓어졌습니다. context: fork 로 조사를 분리하고, paths 로 발동 범위를 좁히고, disallowed-tools 로 쓰기·실행계 툴을 뺀 읽기 전용 감사도 만들 수 있습니다. 깨지면 곤란한 금지 사항은 Hooks와 조합해 강제합니다
• 팀 전개는 Git 커밋 → Plugin → managed settings의 3단계. skillOverrides 와 Permission 규칙으로 통제하고, 외부 제작 스킬은 도입 전에 반드시 감사합니다

도입 전 체크리스트

☐ Claude Code를 2026년 1월 말(v2.1.3) 이후 버전으로 업데이트했다 ☐ 기존 .claude/commands/ 를 점검하고, 부작용 있는 것에 disable-model-invocation: true 를 붙였다 ☐ 자동 발동시킬 스킬의 description에 "무엇을 하는가+언제 쓰는가"를 썼다 ☐ 긴 규약·참고 자료는 SKILL.md 본문이 아니라 references/ 로 분리했다 ☐ 감사계 스킬은 disallowed-tools 로 쓰기·실행계 툴을 뺐다 ☐ 팀 공유할 스킬을 .claude/skills/ 에 두고 Git에 커밋했다 ☐ 외부 제작 스킬을 도입하기 전에 스크립트와 외부 통신 유무를 감사했다

검증 환경: 본문의 동작 설명은 모두 다음 환경에서의 실기 검증에 근거합니다. 원칙적으로 특정 환경에 의존하는 동작은 아니지만(환경에 따라 차이가 있는 사항은 3-2 본문과 3-5 보충에 명기), 사실로서 이번에 검증한 환경을 기재합니다.

• Claude Code v2.1.204
• OS: Windows 11
• 검증일: 2026년 7월 8일~10일

Skills는 사양 갱신이 빠른 기능이므로(frontmatter 필드에는 버전 의존적인 것이 있습니다), 최신 사양은 공식 문서에서 확인하세요.