majiayu000 Claude Code 스킬 작성 가이드
사용자가 요청한 스킬을 아래 규칙에 따라 작성하라. 인자가 있으면 참고하고, 없으면 사용자에게 어떤 스킬을 만들지 물어봐라.
요청: $ARGUMENTS
1. 파일 구조
.claude/skills/<skill-name>/
├── SKILL.md # 필수. 스킬 본체
├── reference.md # 선택. 상세 레퍼런스
├── examples/ # 선택. 예제 모음
└── scripts/ # 선택. 실행 스크립트
- 스킬 이름(디렉토리명): 소문자, 숫자, 하이픈만 허용 (최대 64자)
SKILL.md하나만 있으면 동작한다
2. SKILL.md 포맷
---
name: my-skill
description: |
이 스킬이 뭘 하는지, 언제 트리거되는지 설명.
Claude가 이 description을 보고 자동 호출 여부를 판단한다.
argument-hint: "[arg1] [arg2]"
disable-model-invocation: false
user-invocable: true
allowed-tools: Read, Grep, Bash(npm *)
context: fork
agent: Explore
---
# 스킬 제목
본문 지시사항...
프론트매터 필드 요약
| 필드 | 필수 | 설명 |
|---|---|---|
name |
아니오 | 슬래시 커맨드 이름. 생략 시 디렉토리명 사용 |
description |
권장 | Claude가 자동 호출 판단에 사용. 핵심 키워드 포함할 것 |
argument-hint |
아니오 | 자동완성 시 보여줄 인자 힌트 |
disable-model-invocation |
아니오 | true면 Claude 자동 호출 차단. 수동(/name)으로만 실행 |
user-invocable |
아니오 | false면 / 메뉴에서 숨김. 배경지식용 |
allowed-tools |
아니오 | 권한 확인 없이 쓸 수 있는 도구 목록 |
context |
아니오 | fork면 격리된 서브에이전트에서 실행 |
agent |
아니오 | context: fork 시 사용할 에이전트 타입 |
3. 변수 치환
| 변수 | 설명 |
|---|---|
$ARGUMENTS |
전체 인자 문자열 |
$ARGUMENTS[N] 또는 $N |
N번째 인자 (0-based) |
${CLAUDE_SESSION_ID} |
현재 세션 ID |
4. 호출 제어 패턴
| 목적 | 설정 |
|---|---|
| 기본 (사용자+Claude 모두 호출) | 설정 없음 |
| 사용자만 수동 호출 | disable-model-invocation: true |
| Claude만 자동 호출 (메뉴 숨김) | user-invocable: false |
규칙: 부작용(배포, 커밋 등)이 있는 스킬은 반드시 disable-model-invocation: true 설정.
5. 저장 위치와 우선순위
| 우선순위 | 위치 | 범위 |
|---|---|---|
| 1 (최고) | Enterprise 관리 설정 | 조직 전체 |
| 2 | ~/.claude/skills/ |
개인 전체 |
| 3 | .claude/skills/ |
프로젝트 |
| 4 (최저) | 플러그인 | 플러그인 범위 |
동일 이름이면 높은 우선순위가 이긴다.
6. 스킬 로드 조건
스킬을 만들어도 Claude가 인식하지 못하면 소용없다. 로드되려면 아래 조건을 충족해야 한다.
필수 조건
- 올바른 경로에
SKILL.md존재:.claude/skills/<name>/SKILL.md또는~/.claude/skills/<name>/SKILL.md - 프론트매터 형식 정확:
---로 감싼 YAML 블록이 파일 최상단에 있어야 함 - description 존재: 없으면 본문 첫 문단이 대신 쓰이지만, 명시하는 것을 권장
로드 시점
- Claude Code 시작 시 모든 스킬의 description만 컨텍스트에 로드됨 (본문은 호출 시 로드)
- description은 컨텍스트 윈도우의 ~2% 예산 내에서 로드 (최소 16,000자 보장)
- 스킬이 너무 많으면 일부 description이 잘릴 수 있음
로드 확인 방법
/context명령으로 현재 로드된 스킬 목록과 예산 초과 경고 확인 가능- 스킬이 안 보이면
SLASH_COMMAND_TOOL_CHAR_BUDGET환경변수로 예산 확대
로드 안 되는 흔한 원인
| 증상 | 원인 | 해결 |
|---|---|---|
/ 메뉴에 안 나옴 |
파일 경로 오류 또는 user-invocable: false |
경로 확인, 설정 확인 |
| Claude가 자동 호출 안 함 | disable-model-invocation: true 또는 description에 키워드 부족 |
설정 확인, description 개선 |
| 스킬 목록에서 누락 | description 예산 초과 | /context로 확인, 예산 확대 |
| 프론트매터 무시됨 | YAML 문법 오류 (들여쓰기, 콜론 뒤 공백 등) | YAML 린트 확인 |
| 모노레포에서 안 보임 | 하위 디렉토리의 .claude/skills/에 있는데 상위에서 실행 |
작업 디렉토리 확인 또는 --add-dir 사용 |
7. 작성 노하우
description 잘 쓰기
- 사용자가 자연스럽게 말할 키워드를 포함
- BAD:
"코드 도우미"-> 너무 모호 - GOOD:
"코드를 시각적 다이어그램과 비유로 설명. 사용자가 '이 코드 어떻게 동작해?' 같은 질문을 할 때 사용"
본문 지시사항 작성 원칙
- 명확한 역할 부여: "너는 ~하는 전문가다" 식으로 시작
- 단계별 지시: 번호 매긴 단계로 작업 흐름 정의
- 제약 조건 명시: 하지 말아야 할 것도 명확히
- 출력 형식 지정: 원하는 결과물 포맷 제시
- 500줄 이내: 길면 별도 파일로 분리 후 참조
서브에이전트 활용
조사/탐색 위주 스킬은 context: fork로 격리 실행:
context: fork
agent: Explore
메인 대화 컨텍스트를 오염시키지 않는다.
딥 씽킹 활성화
본문 어딘가에 ultrathink를 넣으면 확장 사고 모드가 켜진다.
8. 스킬 작성 절차
위 규칙을 따라 아래 순서로 스킬을 생성하라:
- 사용자 요구사항 파악 (인자 또는 질문으로)
- 스킬 이름, description, 호출 방식 결정
.claude/skills/<name>/SKILL.md작성- 필요시 보조 파일(reference.md, scripts/) 추가
- 작성 결과를 사용자에게 요약 보고