Claude Code 커스텀 스킬 만들기 — SKILL.md 한 파일로 시작하는 자동화

지난 글에서 Superpowers 플러그인이 14개 스킬로 brainstorm → plan → TDD 흐름을 강제하는 방식을 봤습니다. "그러면 내 작업 흐름도 같은 방식으로 스킬로 박을 수 있나?" 가 자연스러운 다음 질문이에요. 답은 마크다운 한 파일이면 됩니다.

오늘은 Claude Code 커스텀 스킬을 직접 만드는 법을 한 번에 정리합니다 — SKILL.md 구조·frontmatter 14개 필드·자동 발동 트리거·description 잘 쓰는 법·실전 예시 두 개·플러그인으로 묶어 배포까지. 작성 시점(2026-05-15) Claude Code 2.1.x 기준이에요.

1. 스킬이 뭔지 — 한 번 더 짚기

Skill(스킬) — SKILL.md 한 파일로 정의되는, Claude가 필요할 때 자동으로 불러와 따르는 지시사항. 디렉토리 한 개에 마크다운 파일 하나면 끝이라, 진입 장벽이 가장 낮은 Claude 확장 방식이에요.

이전 글에서 다룬 두 가지와의 차이:

항목	어디에서 정의	언제 작동
MCP 서버	TS/Python 코드	외부 시스템 호출 시
CLAUDE.md	마크다운 파일	매 세션 항상 활성
Skill	SKILL.md 마크다운 파일	필요할 때만 자동 로드

핵심 차이는 언제 로드되는가. CLAUDE.md는 매번 컨텍스트에 들어가 토큰을 잡아먹지만, 스킬은 description 한 줄만 컨텍스트에 두고 본문은 호출될 때만 로드돼요. 그래서 스킬을 100개 만들어도 평소엔 부담이 거의 없습니다.

2. 가장 단순한 SKILL.md — 한 파일

스킬은 디렉토리 하나 + 그 안의 SKILL.md 한 파일 이 최소 구조예요.

.claude/skills/run-tests/
└── SKILL.md

SKILL.md 안에는 두 부분만 있으면 됩니다:

---
name: run-tests
description: Run the project's test suite using the Makefile target. Use this whenever the user asks to run tests, check tests, or verify the test suite is passing.
---

# Run Tests

When invoked, run the tests using `make test`.

If tests fail:
1. Read the failure output carefully
2. Identify which test failed and why
3. Suggest a minimal fix
4. Ask before applying it

이걸 .claude/skills/run-tests/SKILL.md 에 저장하고 Claude Code를 재시작하면, 다음에 "테스트 돌려줘" 라고 했을 때 자동으로 이 스킬이 발동합니다.

3. 어디에 저장하나 — 전역 vs 프로젝트

스킬은 두 곳에 둘 수 있어요. 어느 쪽에 둘지가 "누가 쓸 스킬인가" 를 결정합니다.

위치	범위	용도
~/.claude/skills/	전역 — 모든 프로젝트에서 사용 가능	본인의 개인 워크플로 (예: 영어 메일 톤 잡기, 한국어 윤문)
<repo>/.claude/skills/	프로젝트 — 이 리포지토리 안에서만	팀 공통 워크플로 (배포 체크리스트, 마이그레이션 절차)

팀 단위로 공유할 거면 반드시 프로젝트 폴더에 두세요 — git에 커밋되어 동료들도 자동으로 받습니다. ~/.claude/ 는 본인 노트북에만 있어서 팀 공유 안 됩니다.

4. 자동 발동 vs 명시적 호출 — 두 트리거

스킬을 발동시키는 방법 은 두 가지예요.

4-1. 명시적 호출 — 슬래시 명령

/run-tests

스킬 디렉토리 이름이 그대로 슬래시 명령이 됩니다. 사용자가 직접 칠 때만 작동해 예측 가능 하지만, 매번 손으로 쳐야 한다는 번거로움이 있어요.

4-2. 자동 발동 — Claude가 description 보고 판단

사용자: 테스트 결과 좀 확인해 줘
→ Claude가 description의 "verify the test suite is passing" 매칭 → 자동 로드

이게 스킬의 진짜 매력이에요. description을 잘 쓰면 사용자가 슬래시 명령을 외울 필요 없이 Claude가 알아서 적절한 스킬을 꺼냅니다.

기본값은 둘 다 가능. 슬래시로도 부를 수 있고 자동으로도 발동돼요. 두 가지를 frontmatter로 개별 제한할 수 있는데, 이건 §6에서 다룹니다.

5. description — 스킬의 운명을 결정하는 한 줄

자동 발동이 얼마나 정확하게 작동하느냐 는 99% description 이 결정합니다. 이건 "Claude에게 던지는 트리거 한 줄" 이라고 생각하면 돼요.

5-1. 나쁜 description vs 좋은 description

❌ "테스트와 관련된 작업을 도와줍니다" — 동사가 모호, 트리거 단어 없음. 발동률 낮음
✅ "Run the project's pytest suite when the user asks to run tests, check tests, or verify the test suite is passing" — 동사로 시작, 사용자가 실제 칠 단어(run/check/verify)가 박혀 있음

5-2. description 잘 쓰는 4가지 룰

1. 동사로 시작 — "Run...", "Validate...", "Generate...". "A skill that helps with..." 같은 라벨식 description은 피하세요
2. 트리거 단어를 명시적으로 넣기 — 사용자가 실제로 쓸 단어 (한국어/영어 둘 다 가능)를 description에 박아 두면 매칭률이 확 올라갑니다
3. 사용 시점을 명시 — "Use when..." / "Whenever the user asks to..." 패턴이 가장 효과적
4. 2~3문장 이내 — 너무 길면 매칭 정확도가 오히려 떨어집니다. 200자 안에서 끝내세요

자가 검증 한 줄 — description을 소리 내어 읽었을 때 "이 스킬이 언제 발동될지" 가 명확하면 OK.

5-3. description 글자 수 한도

• Claude.ai: 200자
• Claude Code (Agent Skills 사양): 1,024자
• description + when_to_use 합쳐서: 1,536자에서 잘림

전체 스킬 목록의 총 컨텍스트 예산 은 컨텍스트 윈도의 1% 정도(8,000자 fallback)예요. 스킬이 많아지면 description이 자동으로 잘리니까 짧고 정확하게 가 정답.

6. frontmatter 14개 필드 — 한 표 정리

name 과 description 외에 12개 옵션 필드로 언제·어떻게·어떤 권한으로 발동될지 미세 조정할 수 있어요. 자주 쓰는 것 위주 정리.

필드	용도
name (필수)	디렉토리명과 일치, 소문자·하이픈, 최대 64자
description (권장)	자동 발동 트리거. §5 룰대로
when_to_use	description에 추가될 트리거 컨텍스트. 보조 트리거 모음
disable-model-invocation	true이면 자동 발동 차단, /이름 으로만 호출
user-invocable	false이면 슬래시 메뉴에 안 뜸. 배경 지식 전용
allowed-tools	스킬 활성화 동안 별도 허락 없이 쓸 수 있는 도구. 예: Bash(npm test *) Read Grep
paths	글로브 패턴으로 자동 발동 파일 제한. 예: **/*.ts (TS 파일에서만 자동 발동)
model	이 스킬 실행할 모델 지정. 예: claude-opus-4-7
effort	추론 노력 단계 (high / xhigh / max)
agent	서브에이전트로 실행할지
context	fork 시 신선한 컨텍스트로 분기
dependencies	필요한 패키지. 예: python>=3.8, pandas>=1.5.0
argument-hint	사용자에게 보여줄 인자 힌트. 예: [file-or-directory]
shell	셸 종류 (bash 등)

6-1. 가장 자주 쓰는 패턴 3종

자동 발동 + 부수 효과 없는 경우 (기본값, 추가 필드 없음):

---
name: run-tests
description: Run the project's pytest suite when the user asks to run tests, check tests, or verify tests pass
---

부수 효과 있어서 자동 발동 막을 경우 (배포·커밋·DB 마이그레이션):

---
name: deploy-staging
description: Deploy to staging environment with safety checks
disable-model-invocation: true
allowed-tools: Bash(kubectl *) Bash(helm *)
---

특정 파일 타입에서만 발동되어야 할 경우:

---
name: react-component-rules
description: Apply our team's React component conventions when editing components
paths: "**/*.tsx"
---

7. 실전 예시 1 — Conventional Commit 스킬

자동 발동의 매력을 한 번에 보여주는 예시. "commit" 단어만 등장하면 자동으로 발동되어 Conventional Commit 형식으로 메시지를 짜 줍니다.

.claude/skills/conventional-commit/SKILL.md:

---
name: conventional-commit
description: Use this skill any time the user asks for a git commit, to commit changes, or to write a commit message. It writes the message in Conventional Commit format (feat/fix/docs/style/refactor/test/chore).
allowed-tools: Bash(git status *) Bash(git diff *) Bash(git add *) Bash(git commit *)
---

# Conventional Commit

When invoked, follow these steps:

1. Run `git status` to see staged/unstaged files
2. Run `git diff --cached` to see what's being committed
3. Pick the most appropriate type prefix:
   - `feat:` new feature
   - `fix:` bug fix
   - `docs:` documentation only
   - `style:` formatting, no logic change
   - `refactor:` rewrite without behavior change
   - `test:` test additions/changes
   - `chore:` tooling, dependencies, build
4. Write the subject line:
   - Max 72 characters
   - Imperative mood ("Add", not "Added")
   - No period at the end
5. Show the proposed message to the user and ask for confirmation
6. On confirmation, run `git commit -m "<message>"`

## Examples

- `feat: add 2FA via TOTP for user login`
- `fix: prevent race condition in cart update`
- `docs: clarify env vars in README`

이걸 박아두면 "이 변경 커밋해 줘" 한 줄에 위 흐름이 자동으로 작동합니다. 매번 "커밋 메시지는 Conventional Commit으로 써 줘" 라고 설명할 필요 X.

8. 실전 예시 2 — 배포 전 체크리스트 (명시 호출 전용)

부수 효과가 있는 작업은 자동 발동을 막아 사용자가 명시적으로 부를 때만 작동해야 합니다.

.claude/skills/deploy-check/SKILL.md:

---
name: deploy-check
description: Pre-deploy checklist — runs git status, tests, env config validation, and gates the deploy on explicit user confirmation
disable-model-invocation: true
allowed-tools: Bash(git status *) Bash(npm test *) Bash(node scripts/check-env.js *)
---

# Deploy Check

This skill MUST be invoked manually via `/deploy-check`. It will NOT auto-run.

## Steps

1. Run `git status` — fail if there are uncommitted changes
2. Run `npm test` — fail if any test fails
3. Run `node scripts/check-env.js` — fail if required env vars are missing
4. Show the user a summary of all 3 checks
5. Ask the user explicitly: "All checks passed. Deploy to staging now? (yes/no)"
6. Only if user says "yes", run the deploy command. Otherwise stop.

## Important

- **Never deploy without explicit user "yes"**, even if all checks pass
- **Never skip a check** even if the user asks

disable-model-invocation: true 가 핵심이에요. "코드가 잘 짜였으니 이제 배포해 볼까" 라고 Claude가 알아서 판단하는 게 위험한 상황을 막습니다.

9. 보조 자원 — references·scripts·assets 폴더

SKILL.md 본문은 500줄 이하 로 유지하는 게 권장입니다. 더 긴 참조 자료가 필요하면 같은 디렉토리 안에 폴더로 분리해요.

.claude/skills/api-style-guide/
├── SKILL.md           # 메인 스킬 (500줄 이하)
├── references/
│   ├── endpoints.md   # 상세 엔드포인트 명세
│   └── auth.md        # 인증 흐름 상세
├── assets/
│   └── error-codes.json   # 에러 코드 매핑 테이블
└── scripts/
    └── validate.py    # API 응답 검증 스크립트

각 폴더의 역할:

• references/ — Claude가 필요할 때만 읽어들이는 보조 문서
• assets/ — 템플릿·룩업 테이블·스키마 등 정적 자산
• scripts/ — Python·Node·Bash 실행 스크립트 (Claude가 직접 실행)

SKILL.md 본문에서 "이런 케이스는 references/auth.md를 읽고…" 같은 식으로 참조하면, Claude가 필요할 때만 그 파일을 추가로 로드합니다.

의존성 선언 (scripts 사용 시)

---
name: data-analysis
description: Analyze CSV files and generate visualizations
dependencies: python>=3.8, pandas>=1.5.0, matplotlib
---

dependencies 필드를 박으면 스킬 첫 실행 시 Claude가 자동으로 pip install / npm install 을 시도합니다. 같은 패키지를 매번 다시 깔지 않게 캐시도 알아서 관리.

10. 플러그인으로 묶어 배포

스킬 여러 개를 한 묶음으로 팀·세상에 공유하고 싶으면 플러그인 으로 패키징하면 됩니다. Superpowers 플러그인이 정확히 이 방식이에요.

10-1. 최소 플러그인 구조

my-claude-plugin/
├── .claude-plugin/
│   └── plugin.json          # 플러그인 메타데이터
├── skills/
│   ├── run-tests/
│   │   └── SKILL.md
│   ├── conventional-commit/
│   │   └── SKILL.md
│   └── deploy-check/
│       └── SKILL.md
├── commands/                 # (옵션) 슬래시 명령
├── hooks/                    # (옵션) SessionStart 등 훅
└── README.md

.claude-plugin/plugin.json:

{
  "name": "my-team-workflow",
  "version": "1.0.0",
  "description": "Our team's standard workflow skills",
  "author": "Your Team",
  "license": "MIT"
}

이 리포를 GitHub에 푸시하면, 다른 사람이 한 줄로 설치 가능:

/plugin marketplace add your-team/my-claude-plugin
/plugin install my-team-workflow@my-claude-plugin

10-2. 마켓플레이스 만들기

여러 플러그인을 묶어 마켓플레이스 로 운영할 수도 있어요. 별도 리포지토리에:

my-marketplace/
└── .claude-plugin/
    └── marketplace.json     # 플러그인 카탈로그

marketplace.json 에 플러그인 목록을 넣어 두면 Superpowers Marketplace 처럼 회사 단위·팀 단위 마켓플레이스가 됩니다.

11. 디버깅 — 스킬이 안 발동될 때

자주 만나는 문제 5가지.

증상	원인·해결
Claude가 스킬을 발동하지 않음	description이 너무 모호. 동사+트리거 단어로 다시 작성
/이름 슬래시 명령이 안 보임	user-invocable: false 설정 여부 확인, Claude Code 재시작
자동 발동이 너무 자주 일어남	description이 너무 광범위. 트리거 조건을 좁힘
스킬이 권한 요청을 매번 함	allowed-tools 에 필요한 도구 미리 등록
의존성 미설치 에러	dependencies 필드 추가, 또는 수동으로 한 번 설치

가장 유용한 디버깅 방법 — Claude에게 직접 물어보세요:

사용자: 내 conventional-commit 스킬이 잘 안 발동되는데, 어떻게 고칠까?

Claude가 SKILL.md를 읽고 "description에 '커밋' 한국어 트리거가 빠져 있어서 한국어로 요청 시 매칭률이 낮습니다" 같이 짚어줍니다. Superpowers의 writing-skills 스킬 도 이런 자가 검수에 특화된 스킬이에요.

12. 한 줄 정리

Claude Code 커스텀 스킬 = 마크다운 한 파일로 작성하는 재사용 가능한 워크플로. SKILL.md 안에 YAML frontmatter + 본문을 박고 .claude/skills/<이름>/ 폴더에 두면 끝. 자동 발동(description 매칭)과 명시 호출(/이름) 두 방식을 골라 쓸 수 있고, 부수 효과 있는 작업은 disable-model-invocation: true 로 막아두면 안전합니다.

핵심 결정 3가지:

1. description을 잘 쓰는 것 — 동사로 시작, 트리거 단어 명시, 200자 이내
2. 저장 위치 — 본인용은 ~/.claude/skills/, 팀 공유는 <repo>/.claude/skills/ (git 커밋)
3. 부수 효과 통제 — 배포·DB 변경 같은 작업은 disable-model-invocation: true

여러 스킬을 모으면 그게 곧 플러그인이고, 플러그인을 묶으면 마켓플레이스예요. Superpowers 가 정확히 이 흐름의 정점에 있는 사례입니다. 처음 한 스킬은 30분이면 만들 수 있고, "이거 매번 설명하던 작업이었네" 라는 깨달음은 그날 바로 손에 들어옵니다.

다음 단계 — 본인이 자주 반복하는 작업 하나를 골라 SKILL.md 한 파일로 박아 보세요. 일주일 뒤에 "왜 이걸 진작 안 했지" 가 자연스러운 다음 생각이 됩니다.

---

참고 자료

• Claude Code Docs — Skills 공식 문서
• Claude.ai Docs — Creating Custom Skills
• Anthropic Help Center — How to Create Custom Skills
• Skill 작성 모범 사례 (Anthropic API Docs, 한국어)
• Claude Code Skills 한국어 가이드 (Anthropic 공식)
• Moeed Rajpoot — Claude Code Skills Practical Guide 2026
• Every SKILL.md Frontmatter Field 2026 (14개 필드 상세)
• ClaudeGuide — How to Build a Custom Claude Code Skill

본 글은 일반 정보 정리용이며, Claude Code·스킬 사양은 빠르게 갱신됩니다. 최신 사양은 공식 docs 와 RELEASE-NOTES에서 직접 확인하세요.