Claude Code · 확장점: Skills (점진적 공개 패키지)

한 줄 요약

Skills는 “Claude에게 특정 작업을 하는 방법을 적어둔 폴더”로, 평소엔 설명 한 줄만 기억하다가 필요한 순간에만 본문 전체를 펼쳐 읽는 장치다. 왜 배우나 — 같은 지침을 매번 복붙하거나 CLAUDE.md가 절차로 비대해질 때, 방대한 절차 지식을 컨텍스트를 낭비하지 않고 Claude에 붙이는 표준 방법이기 때문이다.

그림

flowchart TD
    A["세션 시작: skills 발견"] --> B["이름+설명만 컨텍스트에 상주<br/>1단계 메타 · 항상 떠 있음"]
    B --> C{"언제 펼치나?"}
    C -->|사용자 말이 설명과 맞음| D[Claude가 자동 호출]
    C -->|"사용자가 /skill-이름 입력"| D
    D --> E["전처리: 본문 속 !명령어를 셸로 실행해<br/>결과로 치환"]
    E --> F["SKILL.md 본문을 단일 메시지로 주입<br/>2단계 본문 · 세션 내내 유지"]
    F --> G{"본문이 더 깊은 자료를 가리키나?"}
    G -->|상세 지식 필요| H["references 문서 읽기<br/>3단계 · 토큰 소비"]
    G -->|반복 계산 작업| I["scripts 실행<br/>3단계 · 토큰 0, 읽지 않음"]
    H --> J["모델이 추론·작업 수행"]
    I --> J
    F --> J
    J --> K[결과 반환]

쉽게 풀기

Skills를 식당 메뉴판에 비유하면 이해가 빠르다.

메뉴판은 항상 펴 둔다 (1단계 메타). 손님(사용자)이 들어오면 종업원(Claude)은 “오늘 가능한 요리 이름과 한 줄 설명”만 외워 둔다. 이게 name과 description이다. 가벼우니 항상 머릿속에 떠 있다.
주문이 들어와야 레시피를 펼친다 (2단계 본문). 손님이 “된장찌개 주세요”라고 말하거나(자동 트리거), 메뉴 번호를 콕 집어 /된장찌개라고 부르면(수동 트리거) — 그제서야 종업원이 두꺼운 레시피북에서 해당 페이지(SKILL.md 본문)를 펼친다. 평소엔 안 펼치니 머리가 가볍다.
레시피가 가리키는 부록·도구는 그때 꺼낸다 (3단계 번들). 레시피에 “자세한 양념 비율은 부록 참고”라고 적혀 있으면 그때 references/ 문서를 읽고, “반죽은 반죽기로 돌려라”라고 적혀 있으면 scripts/ 도구를 읽지 않고 그냥 돌린다. 도구는 결과만 받아오므로 머리(토큰)를 쓰지 않는다.

이 “필요할 때만 한 단계씩 더 펼친다”가 바로 **점진적 공개(progressive disclosure)**다. 핵심 효과는 “두꺼운 매뉴얼 전체를 항상 들고 다니지 않아도 된다”는 것. 설명은 싸게 항상 떠 있고(1단계), 본문은 주문 시에만(2단계), 상세 자료와 스크립트는 정말 필요할 때만(3단계) 들어온다.

[!note] “이걸 skill로 빼야 한다”는 신호 같은 지침·체크리스트·다단계 절차를 채팅에 계속 붙여넣고 있다면, 또는 CLAUDE.md의 한 섹션이 “사실”이 아니라 “절차”로 자라났다면, 그 절차를 skill로 분리할 때다. CLAUDE.md와 달리 skill 본문은 쓸 때만 로드되므로, 긴 참조 자료를 붙여도 평소엔 거의 비용이 들지 않는다.

핵심 정리

디렉토리 구조 — 점진적 공개의 물리적 형태

요소	필수	로드 시점
`SKILL.md`	필수	트리거 시 본문 주입 (진입점)
`references/*.md`	선택	Claude가 필요 판단 시 (상세 문서·API 사양)
`scripts/*`	선택	Claude가 실행 시 (읽지 않고 실행만, 토큰 0)
`assets/*`	선택	출력물 재료 (템플릿·이미지·폰트)

3단계 로딩 — 분량 가이드

단계	무엇	항상 로드?	분량
1. 메타데이터	`name`+`description`	항상 상주	~100 단어
2. 본문	마크다운 지침	트리거 시	1,500~2,000 단어 (상한 <5k)
3. 번들	references/scripts/assets	필요 시	사실상 무제한

Frontmatter 필드 (공식 문서 기준 전체 — `SKILL.md` 상단 `---` 사이 YAML)

모든 필드는 선택이며, Claude가 트리거 시점을 판단하도록 description만 권장된다.

[!note] 자주 쓰는 핵심 필드

name — 목록 표시 이름. 기본값=디렉토리명. plugin 루트 SKILL.md를 제외하면 명령어 이름을 바꾸지 않음.

description (권장) — 무엇을·언제. 자동 적용 판단의 라우팅 키. 생략 시 본문 첫 단락 사용. when_to_use와 합쳐 목록에서 1,536자로 잘림 → 주요 사용 사례를 앞에 둘 것.

when_to_use — 트리거 구문·예제 요청 등 추가 컨텍스트. description에 합산되어 1,536자 제한에 포함.

disable-model-invocation (기본 false) — true면 Claude 자동 로드 차단(사용자만 /name). subagent 사전로드도 막음.

user-invocable (기본 true) — false면 / 메뉴에서 숨김(Claude만 호출). 배경 지식용.

allowed-tools — 활성 시 권한 묻지 않고 쓸 도구(공백/쉼표/YAML 목록).

[!note] 인수·실행 환경 제어 필드

argument-hint — 자동완성 힌트. 예: [issue-number], [filename] [format].

arguments — 명명 위치 인수. $name 치환용, 순서대로 매핑.

disallowed-tools — 활성 시 도구 풀에서 제거. 다음 메시지에 해제.

model — 활성 턴 동안 쓸 모델. /model 값 또는 inherit.

effort — 노력 수준 재정의: low/medium/high/xhigh/max.

context — fork 설정 시 격리 subagent 컨텍스트에서 실행.

agent — context: fork 시 쓸 subagent 유형(Explore/Plan/general-purpose/커스텀). 생략 시 general-purpose.

hooks — 이 skill 라이프사이클에 범위 지정된 hooks.

paths — glob 패턴. 일치 파일 작업 시에만 자동 로드.

shell — !command“ 블록용 셸: bash(기본)/powershell.

version — semver 문자열(예: 0.1.0). plugin-dev 계열 관례 필드.

aliases — 대체 호출 이름(실사용 plugin frontmatter에서 확인됨).

문자열 치환 변수 (본문에서 사용)

변수	설명
`$ARGUMENTS`	호출 시 전달된 전체 인수 문자열
`$ARGUMENTS[N]` / `$N`	0-기반 인덱스 개별 인수 (`$0`=첫 번째). shell식 인용
`$name`	`arguments` 목록에서 선언한 명명 인수
`${CLAUDE_SESSION_ID}`	현재 세션 ID(로깅용)
`${CLAUDE_EFFORT}`	현재 노력 수준
`${CLAUDE_SKILL_DIR}`	SKILL.md가 있는 디렉토리. 번들 스크립트 경로 참조용(설치 위치 무관)

[!note] AI가 이 메뉴를 소비하는 방식 (라이프사이클) Claude의 컨텍스트 예산은 한정돼 있어 모든 skill 본문을 항상 싣는 건 낭비다. 그래서:

세션 시작: 발견된 모든 skill의 name+description이 상주(단, disable-model-invocation: true면 description도 빠짐).

호출 시: 렌더링된 SKILL.md가 대화에 단일 메시지로 들어가 세션 내내 유지된다(매 턴 다시 읽지 않음) → 본문은 일회성 단계가 아니라 “상시 지침”으로 써야 함.

!command“: 주입 전에 셸 실행→출력 치환(1회, 재스캔 안 함). Claude가 실행하는 게 아님.

context: fork: 본문이 격리 subagent의 프롬프트가 되어, 대화 기록 없이 실행되고 결과만 요약 반환.

자동 압축(compaction) 주의: 호출된 skill은 가장 최근 호출분 처음 5,000토큰을 유지하고, 재첨부분은 25,000토큰 공동 예산을 최신순으로 채움 → 많이 호출하면 옛 skill은 압축 후 사라질 수 있음.

설명 잘림: description 목록은 컨텍스트 윈도우 1% 예산(skillListingBudgetFraction로 조정) 내에서 잘림. /doctor로 초과 여부 확인 가능.

실제 예시

예시 1 — 가장 기본형: 변경사항 요약 skill 만들기

# 1) 개인 skill 디렉토리 + 점진적 공개용 하위 폴더
mkdir -p ~/.claude/skills/summarize-changes/{references,scripts}

# ~/.claude/skills/summarize-changes/SKILL.md
---
name: summarize-changes
description: This skill should be used when the user asks to "what changed", "summarize my diff", "review my changes", or wants a commit message. Summarizes uncommitted git changes and flags risks.
version: 0.1.0
allowed-tools: Bash(git *)
---

# Summarize Changes

## Current changes
!`git diff HEAD`

## Instructions
Summarize the changes above in two or three bullet points, then list risks
(missing error handling, hardcoded values, tests needing updates). If the diff
is empty, say there are no uncommitted changes.

## Additional resources
- For risk taxonomy details, see [references/risk-patterns.md](references/risk-patterns.md)

!git diff HEAD“ 줄은 Claude가 보기 전에 셸에서 실행되어 출력으로 치환된다(전처리). 즉 지침은 실제 diff가 이미 인라인된 상태로 도착한다.

예시 2 — 트리거 문구의 표준형 (description 작성법)

// /home/seunghyeong/harness-work/claude-code/plugins/plugin-dev/skills/skill-development/SKILL.md
---
name: Skill Development
description: This skill should be used when the user wants to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.
version: 0.1.0
---

# Skill Development for Claude Code Plugins
...

이 description이 ‘이럴 때 사용’ 트리거 문구의 표준형이다: 3인칭 This skill should be used when the user wants to + 사용자가 실제로 칠 법한 따옴표 문구("create a skill", "write a new skill" …) 나열.

예시 3 — 실사용 plugin frontmatter (aliases 필드 실증)

// /home/seunghyeong/.claude/plugins/marketplaces/omc/skills/skillify/SKILL.md
---
name: skillify
aliases: [learner]
description: Turn a repeatable workflow from the current session into a reusable OMC skill draft
---

만들 때 체크리스트

디렉토리명이 곧 명령어명(/summarize-changes). plugin 루트만 name이 명령어명을 정함.
description은 3인칭 + 사용자가 칠 따옴표 트리거 문구 나열. 주요 사례를 앞에(1,536자 컷).
본문은 명령형/부정사(“Summarize…”, “List…“)로, 2인칭(“You should…“) 금지.
본문 1,500~2,000단어(상한 <5k). 상세는 references/로 빼고 링크로 가리킴(중복 금지).
반복 코드는 scripts/로(실행만, 토큰 0). 경로는 ${CLAUDE_SKILL_DIR} 사용.
부작용 있는 워크플로(deploy/commit)는 disable-model-invocation: true.
!command“로 라이브 데이터 주입 시 allowed-tools로 사전 승인.
트리거 검증: “What did I change?”로 자동 호출 + /summarize-changes로 수동 호출 둘 다 테스트.

요약 & 셀프체크

Skills는 SKILL.md 하나가 진입점인 폴더이며, “설명은 항상·본문은 호출 시·번들은 필요 시”의 3단계 점진적 공개로 컨텍스트를 아낀다.
description은 자동 트리거의 라우팅 키이자 1,536자로 잘리는 자원이므로 3인칭 트리거 문구를 앞쪽에 배치한다.
호출된 본문은 세션 내내 단일 메시지로 상주하고, scripts/는 읽지 않고 실행만 하며(토큰 0), context: fork는 격리 subagent로 돌린다.

스스로 답해보기:

같은 절차를 매번 복붙하고 있다. skill로 빼면 무엇이 좋아지고, CLAUDE.md에 두는 것과 비용 면에서 어떻게 다른가?
내 skill이 자동으로 너무 자주(혹은 안) 트리거된다. description의 어떤 점을 손봐야 하나? 자동 호출을 완전히 막으려면 어떤 필드를 쓰나?
무거운 표 생성 같은 결정론적 작업을 본문에 직접 쓰지 않고 scripts/로 빼면 토큰 측면에서 왜 유리한가?

근거 파일

/mnt/d/6study/10_프레임워크분석/_원문아카이브/claude-code/skills.md (공식문서 한글 아카이브 — frontmatter 전체 표·치환 변수·라이프사이클·context:fork·동적 주입의 1차 출처)
/home/seunghyeong/harness-work/claude-code/plugins/plugin-dev/skills/skill-development/SKILL.md (메타 예시 — description 트리거 문구 형식, 3단계 progressive disclosure, version 필드, 명령형 작성 규칙)
/home/seunghyeong/harness-work/claude-code/plugins/plugin-dev/skills/skill-development/references/skill-creator-original.md (존재 확인 — references/로 상세 분리한 실물)
/home/seunghyeong/harness-work/claude-code/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md (commands 계열 frontmatter: description/allowed-tools/model/argument-hint/disable-model-invocation 상세)
/home/seunghyeong/harness-work/claude-code/plugins/hookify/skills/writing-rules/SKILL.md (또 다른 실제 SKILL.md — name/description/version frontmatter + 트리거 문구 실증)
/home/seunghyeong/.claude/plugins/marketplaces/omc/skills/skillify/SKILL.md, .../verify/SKILL.md (실사용 plugin frontmatter — aliases 필드, 간결 description 실증)

연결

CC_개요 · _분석축_루브릭

[!tip] Codex 교차검증 위 frontmatter 전체 표·치환 변수·라이프사이클(자동 압축 5,000/25,000토큰)·context: fork·동적 주입(!command“ 1회 전처리·재스캔 없음) 내용은 공식문서 한글 아카이브(_원문아카이브/claude-code/skills.md)를 1차 출처로 대조하여 확인했다.

Claude Code · 확장점: Skills (점진적 공개 패키지)

Claude Code · 확장점: Skills (점진적 공개 패키지)

한 줄 요약

그림

쉽게 풀기

핵심 정리

디렉토리 구조 — 점진적 공개의 물리적 형태

3단계 로딩 — 분량 가이드

Frontmatter 필드 (공식 문서 기준 전체 — SKILL.md 상단 --- 사이 YAML)

문자열 치환 변수 (본문에서 사용)

실제 예시

예시 1 — 가장 기본형: 변경사항 요약 skill 만들기

예시 2 — 트리거 문구의 표준형 (description 작성법)

예시 3 — 실사용 plugin frontmatter (aliases 필드 실증)

만들 때 체크리스트

요약 & 셀프체크

근거 파일

연결

Frontmatter 필드 (공식 문서 기준 전체 — `SKILL.md` 상단 `---` 사이 YAML)