Claude Code Skills 설정 가이드 — SKILL.md 구조부터 Frontmatter까지

들어가며

Skills를 만들어보려고 SKILL.md를 처음 열면 바로 질문이 생긴다. frontmatter에는 어떤 필드를 쓸 수 있는가? description은 어떻게 쓰는 게 좋은가? Claude가 Skill을 자동으로 실행하지 않도록 막을 수 있는가? 파일을 어디에 두어야 팀 전체에 공유되는가?

이 글은 그 질문들에 답한다. SKILL.md의 파일 구조, frontmatter 각 필드의 의미와 쓰임새, Skill을 어디에 저장하느냐에 따라 달라지는 적용 범위, 인수를 넘기고 시스템 변수를 활용하는 방법까지 — Skills를 설정하고 제어하는 데 필요한 내용을 정리했다.

Skill이 동작하는 방식

Skill의 핵심은 두 단계 로딩이다. 항상 모든 내용을 메모리에 올리는 게 아니라, 필요할 때만 가져온다. Claude의 컨텍스트 윈도우는 유한하기 때문에 이 구조가 중요하다.

L1메타

항상 컨텍스트에 존재 — description 필드

세션이 시작되면 등록된 모든 Skill의 이름과 description이 컨텍스트에 로드된다. Claude는 이걸 보고 "언제 어떤 Skill을 써야 하는지" 파악한다. description이 짧을수록 컨텍스트 절약에 유리하다.

L2본문

호출 시 로드 — SKILL.md 본문

Claude가 Skill을 사용하겠다고 판단하거나, 사용자가 /skill-name으로 직접 호출하면 그때 SKILL.md의 전체 내용이 로드된다. 평소에는 컨텍스트를 차지하지 않는다.

L3리소스

선택적 로드 — 보조 파일들

Skill 디렉토리 안에 추가 파일을 둘 수 있다. SKILL.md에서 참조하면 Claude가 필요할 때만 읽는다. 방대한 API 레퍼런스나 예시 컬렉션을 분리할 때 유용하다.

이 구조 덕분에 Skill이 많아도 컨텍스트 부담이 크지 않다. description만 항상 올라오고, 나머지는 실제로 필요한 순간에만 로드된다. Skill이 많아 description 목록이 컨텍스트 한도를 초과하면 일부가 제외될 수 있는데, /context로 확인하거나 SLASH_COMMAND_TOOL_CHAR_BUDGET 환경변수로 한도를 늘릴 수 있다.

SKILL.md 파일 구조와 구성 요소

Skill은 SKILL.md 파일 하나로 시작한다. 이 파일이 있는 디렉토리가 곧 하나의 Skill이다. 구조는 단순하다.

~/.claude/skills/my-skill/ 디렉토리 구조

my-skill/
├── SKILL.md           # 메인 지침 (필수)
├── reference.md       # 상세 레퍼런스 (선택)
├── examples/
│   └── sample.md      # 예시 출력 (선택)
└── scripts/
    └── helper.py      # 실행 스크립트 (선택)

SKILL.md는 YAML frontmatter와 마크다운 본문, 두 부분으로 구성된다. frontmatter가 메타데이터를 정의하고, 본문이 실제 지침이 된다.

~/.claude/skills/explain-code/SKILL.md YAML

---
name: explain-code
description: |
  Explains code with visual diagrams and analogies.
  Use when explaining how code works, teaching about
  a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare to something familiar
2. **Draw a diagram**: Show flow and structure in ASCII art
3. **Walk through the code**: Explain step-by-step
4. **Highlight a gotcha**: What's a common mistake?

이렇게 만들어두면 "이 코드가 어떻게 동작해?"라고 물었을 때 Claude가 description을 보고 자동으로 이 Skill을 적용한다. 또는 /explain-code src/auth/login.ts처럼 직접 호출해도 된다. SKILL.md는 500줄 이하로 유지하고, 상세 레퍼런스는 별도 파일로 분리하는 게 좋다.

Frontmatter — Skill 동작을 제어하는 설정

SKILL.md의 frontmatter에서 Skill의 동작 방식을 세밀하게 제어할 수 있다. 모든 필드가 선택적이지만, description은 꼭 작성하는 게 좋다. Claude가 이 필드를 보고 언제 Skill을 쓸지 판단하기 때문이다.

frontmatter는 반드시 ---로 시작하고 ---로 닫아야 한다. 이 두 줄 사이에 YAML 형식으로 필드를 작성하고, 그 아래에 마크다운 지침 본문이 온다.

SKILL.md 기본 구조 YAML

---
name: ...
description: ...
---

지침 본문...

필드	설명	기본값
name	Skill 이름. /name으로 직접 호출할 때 사용. 생략 시 디렉토리명으로 대체.	디렉토리명
description	Skill이 하는 일과 언제 써야 하는지. Claude가 자동 호출 판단에 사용. 필수에 가까운 권장 필드.	본문 첫 단락
disable-model-invocation	true로 설정하면 Claude가 자동으로 이 Skill을 로드하지 않음. 사용자가 직접 호출해야 함.	false
user-invocable	false로 설정하면 / 메뉴에서 숨겨짐. Claude만 호출 가능한 배경 지식용.	true
allowed-tools	이 Skill이 활성화될 때 Claude가 허가 없이 사용할 수 있는 도구 목록.	—
context	fork로 설정하면 별도 서브에이전트 컨텍스트에서 실행.	—
agent	context: fork 설정 시 사용할 서브에이전트 타입. Explore, Plan, general-purpose 또는 커스텀 에이전트명.	general-purpose
model	이 Skill이 활성화될 때 사용할 모델 지정.	—
argument-hint	자동완성 시 표시되는 인수 힌트. 예: [issue-number]	—
hooks	이 Skill의 라이프사이클에 스코프된 hooks 설정.	—

description — 자동 호출의 판단 기준

description은 Claude가 "지금 이 Skill을 써야 하나?"를 결정할 때 참고하는 유일한 필드다. 생략하면 본문 첫 단락이 대신 사용되지만, 명시적으로 작성하는 게 좋다. 사용자가 어떤 상황에서 이 Skill을 쓸 것인지를 직접 적어두면 자동 호출 정확도가 높아진다.

review-pr/SKILL.md YAML

---
name: review-pr
description: |
  Review the current pull request for code quality,
  style, and potential bugs. Use when asked to review
  a PR, check code changes, or inspect a diff.
---

disable-model-invocation / user-invocable — 호출 주체 제어

Skill에서 가장 중요한 설계 결정 중 하나가 "이 Skill을 Claude가 알아서 쓰게 할 것인가, 아니면 내가 직접 부를 때만 쓸 것인가"다. disable-model-invocation과 user-invocable, 두 필드로 이를 제어한다.

문제 상황

배포 Skill을 만들었는데, 코드가 완성된 것처럼 보이자 Claude가 알아서 /deploy를 실행해버린다. 사이드 이펙트가 있는 작업이 의도치 않게 트리거된다.

해결책

disable-model-invocation: true를 설정하면 Claude는 절대 이 Skill을 스스로 호출하지 않는다. 사용자가 /deploy를 입력할 때만 실행된다.

반대 상황도 있다. 예를 들어 레거시 시스템의 배경 지식을 담은 Skill이라면, Claude는 관련 작업을 할 때 자동으로 참고해야 하지만 사용자가 /legacy-system-context를 직접 입력하는 건 의미가 없다. 이때는 user-invocable: false를 쓴다.

설정	사용자 호출	Claude 자동 호출	description 컨텍스트 상시 로드
(기본값)	가능	가능	O
disable-model-invocation: true	가능	불가	X
user-invocable: false	불가	가능	O

allowed-tools — 허가 없이 사용할 도구 지정

기본적으로 Claude는 도구를 사용할 때마다 승인을 요청한다. allowed-tools에 도구를 나열하면 이 Skill이 활성화된 동안 해당 도구는 승인 없이 바로 실행된다. Bash 명령은 Bash(패턴) 형식으로 허용 범위를 좁힐 수 있다.

build/SKILL.md YAML

---
name: build
allowed-tools: Bash(npm *), Bash(git *), Read, Write
---

context와 agent — 서브에이전트에서 실행하기

context: fork를 설정하면 Skill이 현재 대화와 분리된 서브에이전트 컨텍스트에서 실행된다. 긴 탐색 작업이나 현재 대화 맥락을 오염시키고 싶지 않을 때 유용하다. agent로 에이전트 타입을 지정할 수 있으며, 생략하면 general-purpose가 사용된다. 이 두 필드는 함께 써야 의미가 있다.

explore-codebase/SKILL.md YAML

---
name: explore-codebase
context: fork
agent: Explore
---

model — Skill별 모델 지정

특정 작업에 맞는 모델을 고정하고 싶을 때 사용한다. 단순 반복 작업엔 빠른 모델을, 복잡한 분석엔 상위 모델을 배정해 비용과 속도를 조율할 수 있다.

complex-review/SKILL.md YAML

---
name: complex-review
model: claude-opus-4-6
---

지금까지 살펴본 필드들을 실제 배포 Skill에 조합하면 다음과 같다. 각 줄의 역할을 주석으로 표시했다.

deploy/SKILL.md YAML

---
name: deploy                                       # /deploy 로 직접 호출
description: Deploy the application to production.    # 자동 호출 판단 기준
             Use when deploying to staging or production.
disable-model-invocation: true                     # Claude 자동 실행 차단
allowed-tools: Bash(npm *), Bash(git *)             # 허가 없이 쓸 수 있는 도구
context: fork                                        # 서브에이전트 컨텍스트에서 실행
agent: Explore                                       # 사용할 에이전트 타입
---

어디에 저장하는가 — Skill 저장 위치

Skill을 어느 경로에 두느냐에 따라 적용 범위가 달라진다. 개인 작업 스타일 가이드는 ~/.claude/에, 팀 공유 컨벤션은 프로젝트 루트의 .claude/에 두면 된다.

위치	경로	적용 범위
Enterprise	관리형 설정 참조	조직 전체 사용자
Personal	~/.claude/skills/<skill-name>/SKILL.md	내 모든 프로젝트
Project	.claude/skills/<skill-name>/SKILL.md	현재 프로젝트만
Plugin	<plugin>/skills/<skill-name>/SKILL.md	플러그인이 활성화된 곳

같은 이름의 Skill이 여러 위치에 있으면 우선순위가 적용된다: Enterprise > Personal > Project. 프로젝트 Skill을 버전 관리에 포함시키면 팀 전체가 동일한 지침을 공유할 수 있다.

모노레포 환경에서는 중첩 디렉토리 자동 탐색도 지원된다. packages/frontend/ 안의 파일을 편집 중이라면, Claude Code는 packages/frontend/.claude/skills/도 자동으로 찾아본다. 패키지별로 독립된 Skill을 관리할 수 있다는 뜻이다. 또한 --add-dir로 추가한 디렉토리 내 .claude/skills/도 자동 로드되며, 세션 중 수정하면 재시작 없이 즉시 반영된다.

$ARGUMENTS와 시스템 변수 — Skill에 값 전달하기

Skill을 호출할 때 인수를 넘길 수 있다. $ARGUMENTS placeholder가 실제 입력값으로 대체된다. 여러 인수는 $ARGUMENTS[0], $ARGUMENTS[1] (또는 축약형 $0, $1)으로 위치별 접근이 가능하다.

인수 1개 — argument-hint로 힌트 제공하기

인수가 하나일 때는 $ARGUMENTS를 그대로 쓰면 된다. argument-hint 필드를 추가하면 / 메뉴 자동완성에서 어떤 값을 입력해야 하는지 힌트로 표시된다.

fix-issue/SKILL.md YAML

---
name: fix-issue
description: Fix a GitHub issue
argument-hint: "[issue-number]"
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit

사용자는 다음과 같이 호출한다.

터미널 Shell

/fix-issue 42
→ $ARGUMENTS = "42"

argument-hint는 자동완성 UI에 표시되는 힌트일 뿐이며, 실제 값 전달 방식에는 영향을 주지 않는다.

인수 2개 이상 — 위치 인수로 분리하기

공백으로 구분된 여러 인수를 넘기면 $ARGUMENTS[0], $ARGUMENTS[1]로 각각 접근할 수 있다. argument-hint에 위치마다 레이블을 적어두면 사용자가 순서를 기억하기 쉽다.

deploy/SKILL.md YAML

---
name: deploy
description: Deploy to the specified environment
argument-hint: "[env] [version]"
disable-model-invocation: true
---

Deploy version $ARGUMENTS[1] to the $ARGUMENTS[0] environment.

1. Verify $ARGUMENTS[0] is a valid target (staging | production)
2. Check that tag $ARGUMENTS[1] exists in the registry
3. Run the deployment pipeline
4. Confirm health checks pass

사용자는 다음과 같이 호출한다.

터미널 Shell

/deploy staging v1.2.0
→ $ARGUMENTS[0] = "staging"
→ $ARGUMENTS[1] = "v1.2.0"
→ $ARGUMENTS    = "staging v1.2.0"  (전체 문자열)

$ARGUMENTS 외에도 시스템에서 자동으로 제공하는 변수가 있다. ${CLAUDE_SESSION_ID}는 현재 세션 ID로, 세션별 로그 파일 생성이나 작업 추적에 활용할 수 있다. ${CLAUDE_SKILL_DIR}는 해당 Skill의 디렉토리 경로로, 번들된 스크립트를 현재 작업 디렉토리와 무관하게 참조할 때 유용하다.

session-logger/SKILL.md YAML

---
name: session-logger
description: Log activity for this session
allowed-tools: Bash(python *)
---

Run the following script to log this session's activity:

python ${CLAUDE_SKILL_DIR}/scripts/log.py

Log destination: logs/${CLAUDE_SESSION_ID}.log

Activity to log: $ARGUMENTS

트러블슈팅

Skill이 예상대로 동작하지 않을 때 확인할 체크리스트다.

Q1미트리거

Skill이 자동으로 트리거되지 않는다

description에 사용자가 실제로 쓸 법한 키워드가 포함되어 있는지 확인한다. "Skill 목록 보여줘"로 등록 여부를 먼저 체크하고, /skill-name으로 직접 호출해 동작 자체는 정상인지 검증한다. description 문구를 실제 사용 패턴에 맞게 다듬는 게 효과적이다.

Q2과트리거

원치 않는 상황에 Skill이 자꾸 켜진다

description을 더 구체적으로 좁힌다. 그래도 안 되면 disable-model-invocation: true로 수동 호출 전용으로 전환한다.

Q3컨텍스트

일부 Skill이 목록에 보이지 않는다

Skill이 많으면 description 목록이 컨텍스트 예산(기본: 컨텍스트 윈도우의 2%, 최대 16,000자)을 초과해 일부가 제외된다. /context로 경고 메시지를 확인하고, 필요하면 SLASH_COMMAND_TOOL_CHAR_BUDGET 환경변수로 한도를 늘린다.

정리하며

Claude Code Skills는 "반복 설명"의 피로를 해결하는 구조적인 답이다. description만 항상 컨텍스트에 올리고, 실제 내용은 필요할 때만 로드하는 Progressive Disclosure 구조가 컨텍스트 효율을 지킨다. 개인 작업 스타일이든 팀 컨벤션이든, Skill 하나로 Claude를 일관되게 동작시킬 수 있다.

번들 스킬(/batch, /simplify 등)은 당장 쓸 수 있는 강력한 워크플로우를 제공하고, 커스텀 Skill로 팀 특화 지침을 추가하면 된다. 복잡한 워크플로우는 $ARGUMENTS와 동적 컨텍스트 주입, context: fork로 더 강력하게 만들 수 있다. 한 번 잘 만들어두면 반복 작업이 줄고, Claude의 응답 품질도 일정해진다.

핵심 정리

• 두 단계 로딩이 컨텍스트를 아낀다. description은 항상 로드되고, 본문은 호출 시에만, 보조 파일은 선택적으로 로드된다. Skill이 많아도 컨텍스트 낭비가 없다.
• description이 자동 호출의 열쇠다. Claude는 description을 보고 Skill을 써야 할지 판단한다. 어떤 상황에서 이 Skill을 써야 하는지 명시적으로 적어두면 자동 호출 정확도가 높아진다.
• disable-model-invocation: true는 사이드이펙트 있는 Skill에 필수. 배포·메시지 전송처럼 타이밍을 직접 제어해야 하는 작업에는 Claude가 알아서 호출하지 못하도록 막아야 한다.
• 저장 위치가 적용 범위를 결정한다. ~/.claude/는 개인 전체, .claude/는 프로젝트 한정. 프로젝트 Skill을 버전 관리에 포함하면 팀 전체가 동일한 지침을 공유할 수 있다.
• $ARGUMENTS로 Skill을 동적으로 만든다. $ARGUMENTS[0], $ARGUMENTS[1]로 위치별 인수를 받고, ${CLAUDE_SKILL_DIR}·${CLAUDE_SESSION_ID} 같은 시스템 변수로 경로와 세션 정보를 처리할 수 있다.