Claude Code 스킬 만드는 법 2026 — 공식 skill-creator 가이드 핵심만

Anthropic이 2026년 3월 skill-creator에 evals·벤치마크·description 튜닝을 추가했다. 공식 Complete Guide(32페이지 PDF)는 첫 스킬 제작에 15–30분이면 된다고 밝혔다. 이 글은 그 가이드에서 실무에 바로 쓸 핵심만 압축한다.

Quick Answer (40–80단어)

Claude Code 스킬은 Use case 정의 → Frontmatter 설계 → Instruction 설계 → Validation 루프 4단계로 만든다. Capability Uplift(모델 보강)와 Encoded Preference(절차·스타일 고정)를 구분하고, description에 “언제 쓰는지”를 전부 넣어야 한다. evals 3개 이상 필수. 2026년 3월 skill-creator 업데이트로 evals·벤치마크·description 튜닝을 코드 없이 할 수 있다.

32페이지짜리 공식 가이드를 받아놓고, 3페이지에서 덮었습니다. “이걸 다 읽어야 스킬 하나 만들 수 있는 건가?” 진입 장벽이 높다고 느꼈거든요. description 대충 적고, 트리거 검증 없이 만든 스킬은 필요할 때는 안 불리고 엉뚱한 순간에 발동했습니다. 근데 skill-creator를 실제로 따라하면서 깨달았어요. 32페이지를 다 읽을 필요가 없었습니다. 핵심은 4단계, 진짜 승부처는 description 한 문장이었습니다.

skill-creator는 2025년 10월 Skills 정식 출시 이후, 2026년 1월 Complete Guide(32페이지)와 2026년 3월 evals·벤치마크·description 튜닝 업데이트로 이어졌다. 이제 “스킬 만드는 법”이 감이 아니라 use case 정의 → frontmatter 설계 → instruction 설계 → validation 루프로 표준화되는 분위기다. 이 글은 그 흐름에서 실무에 바로 쓸 핵심만 압축한다.

실제로 skill-creator를 따라 스킬을 만들어보면, description 설계가 품질의 80%를 좌우한다는 걸 체감한다. use case 5분을 아끼지 않고, evals 3개를 붙이는 습관만 들여도 오발동·미발동이 눈에 띄게 줄어든다.

이 글이 필요한 사람

Claude Code나 Cursor에서 스킬을 쓰긴 하는데, 직접 만드는 건 막막한 사람 — SKILL.md 구조가 뭔지, frontmatter에 뭘 넣어야 하는지 감이 안 잡힌다. 이 글은 4단계 워크플로로 처음부터 끝까지 따라 할 수 있다.
32페이지 공식 PDF 다 읽기 부담스러운 사람 — 핵심만 10분에 훑고 싶다. Complete Guide 전체를 읽기 전에 실무에 바로 쓸 요약이 필요하다.
“프롬프트로 충분한데 왜 스킬을 만들어야 하지?” 고민하는 사람 — 프롬프트 vs 스킬 구분, “언제 스킬로 만들지 말아야 하는지”가 헷갈린다. 이 글의 표와 비교 사례가 판단 기준을 준다.
내 반복 워크플로를 AI에 박아두고 싶은데, 뭘 스킬로 만들지 모르겠는 사람 — 3~5번 반복된 작업, 절차가 고정된 작업을 골라 스킬화하는 체크리스트가 있다. 30분 안에 첫 초안을 만들 수 있다.
스킬을 만들었는데 오발동(false positive)이 잦거나, 필요할 때 안 불리는 사람 — description 설계가 품질의 80%를 좌우한다. “호출돼야 할 3개 + 호출되면 안 될 3개”를 먼저 적는 법을 이 글에서 배운다.

질문 후크: “이 중 하나라도 해당되면, 이 글은 당신을 위한 것이다. 스킬을 쓰기만 하고 만들지는 못한 사람, 여기부터 시작하자. 32페이지 PDF를 다 읽기 전에 포기했던 사람도, 이 글만으로 10분 안에 핵심을 훑을 수 있다.”

지금 결론: Capability Uplift vs Encoded Preference 1페이지 요약

스킬을 만들기 전에, 이 스킬이 어떤 종류인지부터 구분하는 게 중요합니다. Anthropic 공식 블로그(2026년 3월 3일)에서 이렇게 나눕니다.

유형	설명	예시	수명 관리
Capability Uplift	기본 모델이 못하거나 약한 영역을 보강	crypto-analyzer, valuation-calculator, PDF 폼 채우기	모델 업그레이드 시 필요성 재검증. evals로 “이제 기본 모델이 해결하네?” 감지
Encoded Preference	팀/개인의 절차·스타일을 레시피처럼 고정	blog-writer-skill, trading-coach, NDA 검토 절차	모델과 무관하게 유지. 절차 변경 시만 수정. evals로 절차 충실도 검증

핵심 한 줄: Capability Uplift는 모델이 좋아질수록 희석될 수 있고, Encoded Preference는 취향 자동저장이라 오래 갑니다.

Anthropic 2026년 3월 블로그: “Encoded preference 스킬은 더 오래 가지만, 실제 워크플로에 대한 충실도만큼만 가치가 있다. Evals가 그 충실도를 검증한다. Capability uplift 스킬은 모델이 좋아지면 덜 필요해질 수 있다. Evals가 그 시점을 알려준다.”

그래서 스킬을 만들 때는:
– “모델이 못하는 걸 보강하는 건가?” → Capability Uplift. evals 필수로 붙이고, 모델 업그레이드 시 pass rate 재측정
– “내가 매번 다시 설명하기 귀찮은 절차·스타일인가?” → Encoded Preference. evals로 “내 절차가 제대로 지켜지는지” 검증

언제 스킬을 안 만들어도 되나? 한두 번만 쓰는 작업, 매번 요구사항이 바뀌는 작업, 그냥 프롬프트 한 번으로 충분한 작업은 스킬로 만들 필요 없습니다.

직접 써본 경험으로 말하면, 볼트에 crypto-analyzer(Capability Uplift)랑 trading-coach(Encoded Preference)를 같이 돌리고 있는데, 모델이 바뀔 때마다 crypto-analyzer evals를 먼저 돌린다. “이제 기본 모델이 해결하네?”가 되면 그 스킬은 아카이브 후보. trading-coach는 절차가 바뀌지 않는 한 evals만으로 충실도 검증하면 된다.

판별 질문: “이 스킬 없이 기본 모델이 이 작업을 할 수 있나?” → 예: Encoded Preference(절차·스타일만 고정). 아니오: Capability Uplift(모델 보강). “모델이 좋아지면 이 스킬이 덜 필요해질 수 있나?” → 예: Capability Uplift. 아니오: Encoded Preference.

질문 후크: “내가 만들려는 스킬이 모델 보강인가, 내 취향 고정인가? 구분이 안 되면 evals 설계부터 막힌다.”

Anthropic skill-creator 핵심 워크플로 4단계

공식 Complete Guide와 skill-creator SKILL.md를 기준으로, 실제로 따라야 할 4단계를 정리합니다.

Codex skill-creator는 6단계(Understand → Plan → Initialize → Edit → Validate → Iterate)로 되어 있는데, 이 글에서는 실무에 바로 쓸 수 있게 Use case·Frontmatter·Instruction·Validation 4단계로 압축했다. init_skill.py로 템플릿 생성하는 건 “Initialize”에 해당하고, quick_validate.py는 “Validate”에 해당한다.

1단계: Use case 정의

구체적 작업, 트리거, 성공 기준을 명확히 합니다.

구체적 작업: “블로그 글을 쓴다”가 아니라 “배당투자 블로그를 E-E-A-T 구조로 HTML 인라인 스타일로 작성한다”. 추상적일수록 트리거가 애매해집니다.
트리거: 이 스킬이 불려야 할 프롬프트 3개, 불리면 안 될 프롬프트 3개를 먼저 적는다. 예: “BTC 시황 블로그 써줘” → 발동 O, “블로그 글감 뭐가 좋을까?” → 발동 X
성공 기준: 출력에 반드시 포함돼야 할 항목(예: 가격·OI·펀딩비), 금지 패턴(예: “ㅋㅋ”, “결론부터 말하면”)

직접 써본 경험으로 말하면, use case를 대충 넘기면 나중에 description을 10번 고쳐도 트리거가 안정되지 않습니다. 처음 5분을 아끼지 마세요.

실제 스킬 예시: unified-blog-writer-markdown-eeat는 “테크/투자 블로그 글을 E-E-A-T + OREO + GEO 구조로 작성”이라는 구체적 작업을 명시했다. crypto-analyzer는 “550개 암호화폐의 29가지 기술적 지표 + AI 종합 예측 + 블로그 시황 포스팅”으로 범위를 좁혔다. 둘 다 “블로그 써줘” 같은 애매한 트리거와 구분된다.

질문 후크: “이 스킬이 불려야 할 상황 3개를 말할 수 있나? 불리면 안 될 상황 3개도?”

2단계: Frontmatter 설계

name과 description이 스킬의 전부입니다. 본문은 트리거된 뒤에야 로드되니까, description에 “언제 불리는지”를 다 넣어야 합니다.

name: 64자 이내, 소문자·하이픈만. blog-dividend-writer 같은 동사 중심. 툴별 네임스페이스가 도움 될 때는 gh-address-comments처럼 접두사 붙이기도 함
description: 200자 이내(API 기준). 무엇을 하는지 + 언제 쓰는지를 한 문장에. support.anthropic.com 기준 200자, 일부 문서는 1024자까지 허용한다고 하니 환경별로 확인

description 설계가 스킬 품질의 80%를 좌우합니다. 여기서 아끼면 evals 돌려도 false positive·false negative를 못 잡습니다.

나쁜 예: “블로그 관련 작업을 합니다” → “블로그 뭐 쓸까?” 같은 아이디어 단계에서도 발동. 나쁜 예 2: “배당투자 블로그를 HTML로 변환합니다” → 테크 블로그 작성 요청 시 안 불림(너무 좁음). 좋은 예: “배당투자 블로그 작성. 웹 검색 + 사실 확인 + GEO 최적화 + 인라인 스타일 HTML 출력. 배당노마드 폴더 저장.” → 작성 요청에만 발동, 아이디어/분석과 구분됨.

볼트 내 skill-structure.md에서도 동일한 좋은/나쁜 예시를 쓰고 있다.

description 설계 실전 팁: “호출돼야 할 3개 + 호출되면 안 될 3개”를 먼저 적고, 그걸 만족하는 한 문장을 쓰는 게 가장 빠르다. 예: “배당 블로그 써줘” O, “블로그 글감 뭐가 좋을까?” X, “테크 블로그 써줘” X → description에 “배당투자 블로그”를 명시하고, “글감·아이디어”는 제외. “테크”는 명시적으로 안 넣으면 “블로그”가 넓어서 테크도 포함될 수 있으니, “배당노마드” 같은 채널/폴더를 넣어서 구분한다.

실제 스킬 예시: trading-coach는 “매일 시장 체크 + 멀티 페르소나 진입 판단 + 필요시 팀 토론 + AI 관점 저장을 한번에”로 한 문장에 담았다. crypto-analyzer는 “블로그 시황 포스팅 및 트레이딩 기록용”을 끝에 붙여 “분석만 할 때”와 “블로그/기록용”을 구분했다. 둘 다 200자 안에 “무엇을 + 언제”를 압축했다.

3단계: Instruction 설계

SKILL.md 본문에 절차·예시·에러 처리를 명시합니다.

절차: 단계별로 무엇을 할지. “1. 리서치 패키지 읽기 2. 도입부 패턴 확인 3. 최근 3개 글과 다른 TYPE 선택”. 명령형/부정형으로 쓴다(Codex skill-creator 권장)
예시: 입력·출력 샘플 1~2개. “이런 요청이 오면 → 이런 식으로 응답”. 장황한 설명보다 짧은 예시가 토큰 대비 효과가 좋다
에러 처리: “리서치 패키지가 없으면 → 사용자에게 요청” 같은 폴백. 결정적 작업은 scripts/로 빼고, SKILL.md에서는 호출만 안내

Codex skill-creator는 “context window는 공유 자원”이라고 강조합니다. Codex가 이미 아는 건 빼고, 정말 필요한 것만 넣으세요.

Progressive Disclosure: 500줄 넘으면 references/로 분리. SKILL.md는 메타데이터 + 핵심 절차만. references/는 “필요 시 로드”로 두면 컨텍스트를 아낄 수 있다.

Set Appropriate Degrees of Freedom(Codex skill-creator): 작업의 취약성·가변성에 맞춰 자유도를 조절한다. 높은 자유도(텍스트 지시)는 여러 접근이 유효할 때, 중간(의사코드·파라미터 스크립트)은 선호 패턴이 있을 때, 낮은 자유도(구체 스크립트)는 오류에 취약하거나 일관성이 중요할 때. “좁은 다리에는 가드레일, 넓은 들판에는 여러 경로”라고 생각하면 된다.

실제 스킬 예시: crypto-analyzer는 “1. 스크립트 실행 2. 저장된 파일 읽기 3. AI 종합 판단 섹션 작성 4. 파일 업데이트” 4단계로 절차를 고정했다. trading-coach는 “quick-check → team-debate → final-judge” 하이브리드 모드와 “리서치 패키지가 없으면 사용자에게 요청” 같은 폴백을 명시했다. 둘 다 명령형·부정형으로 써서 AI가 따라하기 쉽게 했다.

4단계: Validation 루프

2026년 3월 skill-creator 업데이트로 evals·벤치마크·description 튜닝이 들어갔습니다.

evals: 테스트 프롬프트 + 기대 결과 + pass 기준. “이 프롬프트에 이 스킬이 불려야 함” / “이 프롬프트에선 불리면 안 됨”. Anthropic은 PDF 스킬에서 non-fillable 폼 실패를 evals로 격리하고 수정했다고 밝혔음
벤치마크: 모델 업그레이드 후 pass rate·토큰 사용량·소요 시간 추적. multi-agent로 evals를 병렬 실행해 컨텍스트 오염 없이 빠르게 돌릴 수 있음
description 튜닝: skill-creator가 샘플 프롬프트 대비 description을 분석해, false positive·false negative 줄이는 제안. document-creation 스킬 6개 중 5개에서 트리거 개선이 확인됨

“잘 되는 것 같다”로 끝내지 말고, evals 3개 이상은 꼭 붙이세요. 모델이 바뀌거나 description을 수정할 때마다 재검증하는 습관이 실패 포인트를 줄입니다.

질문 후크: “이 스킬이 제대로 작동하는지 검증하는 테스트 3개를 적을 수 있나?”

Eval 예시 (볼트 내 skill-structure.md 스타일):

#	입력 프롬프트	기대 결과	pass 기준
1	“BTC 시황 분석해줘”	가격·OI·펀딩비 포함 마크다운	3개 지표 모두 존재
2	“어제 분석 다시 보여줘”	호출되지 않아야 함	스킬 미발동
3	“ETH 시황 블로그 써줘”	블로그 포맷, E-E-A-T 구조	도입부+본문+출처 포함

이렇게 3개만 있어도 description 수정 후 “트리거가 망가졌나?”를 바로 확인할 수 있다. skill-creator 2026년 3월 업데이트는 evals를 작성·실행·분석하는 걸 도와주고, comparator agent로 스킬 A vs B, 스킬 유무 비교도 가능하게 했다. 코드 없이 테스트할 수 있게 설계됐다.

실제 스킬 예시: crypto-analyzer evals는 “BTC 시황 분석해줘” → 가격·OI·펀딩비 포함, “어제 분석 다시 보여줘” → 미발동, “ETH 시황 블로그 써줘” → 블로그 포맷 포함으로 3종을 검증한다. unified-blog-writer-markdown-eeat는 “배당 블로그 써줘” → E-E-A-T 구조, “블로그 글감 뭐가 좋을까?” → 미발동으로 트리거를 격리했다. evals 3개만 있어도 description 수정 후 회귀를 바로 잡을 수 있다.

좋은 스킬의 최소 구조

공식 가이드와 Codex skill-creator SKILL.md를 종합하면:

skill-name/
├── SKILL.md (필수)
│   ├── YAML frontmatter (name, description)
│   └── Markdown 본문 (절차, 예시, 에러 처리)
├── scripts/ (선택) — 결정적·반복 작업용
├── references/ (선택) — 상세 문서, 스키마
└── assets/ (선택) — 템플릿, 아이콘

scripts/: 같은 코드를 매번 다시 쓰거나, 결정적 신뢰가 필요한 작업에 쓴다. PDF 회전, 스키마 쿼리 같은 것. 스크립트는 실행만 하면 되니 컨텍스트에 안 넣어도 되고, 토큰 효율이 좋다. Codex skill-creator: “같은 코드를 반복해서 쓰거나 결정적 신뢰가 필요할 때 scripts/를 써라.”

references/: API 문서, DB 스키마, 회사 정책처럼 Codex가 참조해야 할 문서. 10k 단어 넘으면 SKILL.md에 grep 패턴을 넣어서 필요한 부분만 로드하도록 안내한다. SKILL.md와 references에 같은 정보를 두지 말 것. 중복 유지보수만 늘어난다.

assets/: 로고, 템플릿, 폰트처럼 출력에 쓰이는 파일. 컨텍스트에 로드할 필요 없이 복사·수정 대상이다. 예: assets/logo.png, assets/slides.pptx, assets/frontend-template/

Progressive Disclosure 3단계:
1. 메타데이터: 항상 ~100단어 수준으로 로드됨
2. SKILL.md 본문: 트리거 시에만 로드 (<5k 단어 권장)
3. 리소스: 필요 시에만 로드. scripts는 실행만 하면 되니 컨텍스트에 안 넣어도 됨

SKILL.md에 넣지 말 것: README, INSTALLATION_GUIDE, QUICK_REFERENCE, CHANGELOG. AI가 읽을 건 “이 작업을 어떻게 하는지”뿐입니다. skill-creator는 “스킬은 해당 작업에 필요한 정보만 담아야 한다”고 명시합니다. 설정·테스트 절차·사용자용 문서는 스킬 밖에 둔다.

skill-creator 직접 사용 관점: Codex에서 skill-creator를 쓰면 init_skill.py로 템플릿을 생성하고, quick_validate.py로 검증한다. Claude Code에서는 플러그인으로 설치하고 “skill-creator 써서 OOO 스킬 만들어줘”라고 요청하면 된다. 2026년 3월 기준 evals 작성·실행·description 튜닝까지 skill-creator가 도와주니, 수동으로 SKILL.md를 작성한 뒤 evals만 skill-creator에 맡기는 식으로도 쓸 수 있다.

개인 워크플로를 스킬로 옮길 때 흔한 함정

함정 1: description을 너무 넓게 씀

“블로그 작업을 합니다” → 아이디어 단계, 글감 정리, 발행 스케줄 등 모두에서 발동. 호출돼야 할 3개 + 호출되면 안 될 3개를 먼저 적고, 그걸 만족하는 description을 쓰세요. 볼트 내 skill-structure.md에서도 동일한 가이드를 쓰고 있다.

함정 2: Capability Uplift를 과신함

모델이 약한 영역을 보강하는 스킬은, 모델이 좋아지면 “이제 기본으로 되네?”가 됩니다. Anthropic 블로그: “기본 모델이 스킬 없이 evals를 통과하기 시작하면, 그 스킬의 기법이 이미 모델에 흡수됐다는 신호다.” evals로 주기적으로 “스킬 없이도 pass하는지” 확인하고, 필요 없어지면 아카이브하세요.

이렇게 하면 안 되는 이유: Capability Uplift 스킬을 “한 번 만들면 영원히 쓸 자산”으로 여기면, 모델 업그레이드 후에도 계속 그 스킬을 로드해 토큰만 낭비하게 된다. crypto-analyzer 같은 스킬은 “29가지 지표 + AI 예측”이 오늘의 기본 모델에 흡수됐을 수 있다. evals 없이 “아직 필요하지”라고 가정하면, 실제로는 기본 모델이 해결하는데 스킬 본문을 매번 로드하는 비효율이 발생한다. 모델이 좋아질수록 Capability Uplift 스킬의 수명은 짧아진다.

함정 3: 본문에 “언제 쓰는지”를 적음

description에 다 넣어야 합니다. 본문의 “When to Use” 섹션은 트리거된 뒤에야 보이니까, 트리거 결정에 기여하지 못합니다. Codex skill-creator: “When to Use 정보는 description에 넣어라. 본문에 넣으면 소용없다.”

함정 4: 한 스킬에 너무 많은 걸 넣음

“블로그 + 트위터 + 뉴스레터 다 하는 스킬” → 트리거가 애매해지고, 유지보수가 어려워집니다. 한 스킬 = 한 가지 작업으로 쪼개세요. 여러 도메인이 있으면 references/를 도메인별로 나누고, SKILL.md에서는 선택 가이드만 둔다.

함정 5: evals 없이 “잘 되는 것 같다”로 끝냄

실제로 몇 번 써보고 “잘 되네”로 끝나면, 모델 업그레이드나 description 수정 후에 망가진 걸 늦게 발견합니다. 최소 3개 eval은 붙이세요. skill-creator 2026년 3월 업데이트는 “대부분의 스킬 작성자는 엔지니어가 아니라 도메인 전문가”라며, evals·벤치마크로 코드 없이 품질을 검증할 수 있게 했다.

이렇게 하면 안 되는 이유: evals 없이는 false positive(불려야 할 때 안 불림)와 false negative(불리면 안 될 때 발동)를 구분할 수 없다. “블로그 글감 뭐가 좋을까?”에 blog-writer가 발동하면 글감 수집 스킬과 역할이 겹치고, “배당 블로그 써줘”에 안 불리면 사용자는 매번 긴 프롬프트를 다시 써야 한다. description을 한 번만 수정해도 트리거가 크게 바뀌는데, evals 없이는 그 변화를 감지할 방법이 없다. 회귀를 잡지 못한 채 스킬 개수만 늘어나면, 나중에 “어떤 스킬이 뭘 하는지”조차 헷갈린다.

함정 6: “나중에 필요할 수도 있으니까” 과다 설계

요청하지 않은 기능, 예외 케이스, 미래 확장을 미리 넣다 보면 SKILL.md가 500줄을 넘어간다. skill-creator 원칙: “Codex가 이미 아는 건 빼라. 각 문단이 토큰 비용을 정당화하는지 물어보라.” 지금 필요한 것만 넣고, 실사용에서 부족하면 그때 추가하는 게 맞다.

이렇게 하면 안 되는 이유: SKILL.md가 길어질수록 트리거될 때마다 로드되는 토큰이 늘어나고, AI가 핵심 절차를 놓칠 확률이 커진다. “나중에 쓸지도” 하는 예외 케이스를 10개 넣어두면, 실제로 그 상황이 오기 전까지는 노이즈일 뿐이다. 500줄 넘는 스킬은 references/로 분리하지 않으면 컨텍스트 윈도우를 과다 점유한다. 지금 필요한 3~5단계만 명시하고, 부족하면 사용자 피드백 받은 뒤 그때 추가하는 편이 유지보수도 쉽다.

함정 7: “When to Use”를 본문에 넣음

본문에 “이 스킬은 다음 상황에서 사용할 수 있습니다” 같은 섹션을 넣는 실수가 있다. 트리거는 description에만 넣어야 한다. 본문은 트리거된 뒤에야 로드되므로, “언제 쓰는지”를 본문에 적어도 AI가 트리거 결정에 쓸 수 없다. Codex skill-creator: “When to Use 정보는 description에 넣어라. 본문에 넣으면 소용없다.”

오늘 바로 만들 수 있는 첫 스킬 초안 체크리스트

30분 안에 첫 스킬 초안을 만들 수 있는 체크리스트입니다.

Step 1: 스킬화할 작업 고르기 (5분)

[ ] 내가 3번 이상 반복해서 설명한 작업이 있는가?
[ ] 그 작업이 멀티스텝인가? (한 번에 끝나지 않음)
[ ] Capability Uplift인가, Encoded Preference인가? 라벨링했다

예: “매번 블로그 글 쓸 때 E-E-A-T 구조, 도입부 패턴, GEO 최적화를 다시 설명한다” → Encoded Preference. “암호화폐 기술적 지표 29개를 분석한다” → Capability Uplift.

Step 2: 트리거 정의 (5분)

[ ] 이 스킬이 불려야 할 프롬프트 3개를 적었다
[ ] 이 스킬이 불리면 안 될 프롬프트 3개를 적었다
[ ] 유사한 다른 스킬과 트리거가 겹치지 않는다

예: blog-dividend-writer라면 “배당 블로그 써줘” → O, “블로그 글감 뭐가 좋을까?” → X, “테크 블로그 써줘” → X. 이 3종을 description이 구분할 수 있어야 한다.

이렇게 하면 O / 이렇게 하면 X:
– O: “배당 블로그 써줘” O, “블로그 글감 뭐가 좋을까?” X, “테크 블로그 써줘” X — 3종을 명시적으로 구분했다.
– X: “블로그 관련이면 다 불러” — 글감 수집·아이디어 단계까지 포함돼 blog-idea-manager와 겹친다.

Step 3: Frontmatter 작성 (5분)

[ ] name: 64자 이내, 동사 중심, kebab-case
[ ] description: 200자 이내, “무엇을 + 언제” 한 문장에

name 예: blog-dividend-writer, crypto-multi-analyzer. description 예: “배당투자 블로그 작성. 웹 검색 + 사실 확인 + GEO 최적화 + 인라인 스타일 HTML 출력. 배당노마드 폴더 저장.”

이렇게 하면 O / 이렇게 하면 X:
– O: description에 “배당투자 블로그” + “배당노마드 폴더” — 채널·저장 위치까지 넣어 테크 블로그와 구분됨.
– X: “블로그 글 씁니다” — 아이디어·글감·발행 스케줄까지 발동. “무엇을 + 언제”가 없다.

Step 4: 본문 초안 (10분)

[ ] 절차 3~5단계로 나눴다
[ ] 입력·출력 예시 1개 이상
[ ] “이런 경우엔 이렇게” 폴백 1개 이상

절차는 명령형으로. “1. 리서치 패키지 읽기 2. 도입부 패턴 확인 3. 최근 3개 글과 다른 TYPE 선택”처럼. 폴백 예: “리서치 패키지가 없으면 사용자에게 요청하고 진행하지 말 것.”

이렇게 하면 O / 이렇게 하면 X:
– O: “1. 스크립트 실행 2. 저장된 파일 읽기 3. AI 판단 섹션 작성” — 3~5단계, 명령형. “리서치 패키지 없으면 사용자에게 요청” — 폴백 1개.
– X: “블로그 글을 잘 쓰세요” — 추상적. “가능하면 이렇게, 안 되면 저렇게, 상황에 따라…” — 단계가 없고 자유도만 높음.

Step 5: Eval 3개 (5분)

[ ] “이 프롬프트 → 이 스킬 발동, 이 결과” 2개
[ ] “이 프롬프트 → 이 스킬 미발동” 1개

eval 3개만 있어도 description 수정 후 “트리거가 망가졌나?”를 바로 확인할 수 있다. skill-creator 2026년 3월 업데이트는 evals 작성·실행을 도와주니, 수동으로 표를 만들지 않아도 된다.

질문 후크: “30분이면 첫 스킬 초안이 나온다. 완벽할 필요 없고, evals 3개만 붙으면 다음에 반복 개선할 수 있다.”

공식 Complete Guide는 “skill-creator를 쓰면 첫 스킬을 15–30분 안에 만들고 테스트할 수 있다”고 밝혔다. 이 체크리스트는 그걸 30분 단위로 나눈 것이다. 5분씩 5단계, 마지막 5분은 evals. 3개 eval만 있어도 description 수정 후 “트리거가 망가졌나?”를 바로 확인할 수 있다.

프롬프트 vs 스킬: 언제 안 써도 되는지

skill-creator를 쓰든 수동으로 만들든, 먼저 “이게 스킬이어야 하나?”를 판단해야 한다.

상황	스킬 필요?	이유
한두 번만 쓰는 작업	❌	프롬프트로 충분. 스킬화하면 유지보수만 늘어남
매번 요구사항이 바뀌는 작업	❌	트리거·description이 고정이 안 됨
2~3번 반복된 작업	△	프롬프트 저장으로 시작. 아직 스킬일 필요는 없음
3~5번 반복되며 절차가 고정된 작업	✅	스킬 후보. evals로 트리거 검증 후 등록
팀/개인 절차가 명확한 문서·리뷰 스타일	✅	Encoded Preference. 오래 갈 스킬

공식 가이드: “반복 가능한 멀티스텝 작업에 특히 강하다. 프론트엔드 산출물, 조사 방식, 팀 문서 스타일 같은 ‘매번 다시 설명하기 귀찮은 것’을 캡슐화하는 데 잘 맞는다.”

실제로 스킬로 만들었을 때 vs 프롬프트만 썼을 때: “BTC 시황 블로그 써줘”를 매번 요청한다고 가정하자. 프롬프트만 쓰면 매번 “E-E-A-T 구조, 도입부 패턴, GEO 최적화, 가격·OI·펀딩비 포함, 배당노마드 폴더에 저장”을 길게 적어야 한다. 스킬로 만들면 “BTC 시황 블로그 써줘” 한 문장으로 unified-blog-writer-markdown-eeat가 트리거되고, 절차·스타일·저장 위치가 자동 적용된다. 5번째 요청부터는 스킬이 토큰·시간 모두에서 이득이다. 반대로 “이번 주 뭐 쓸까?” 한두 번만 물으면 프롬프트로 충분하고, 스킬로 만들면 유지보수만 늘어난다.

질문 후크: “이 작업을 5번 이상 반복할 예정인가? 절차가 고정돼 있나? 둘 다 아니면 스킬로 만들지 마라. 프롬프트로 충분한 작업을 스킬로 만들면 유지보수만 늘어난다.”

실수 TOP 5

description을 본문에 의존함 — 본문은 트리거 후에 로드되므로, “언제 쓰는지”는 description에 전부 넣어야 함. 이걸 모르고 본문에 “When to Use”를 길게 적는 경우가 많다.
트리거 검증을 안 함 — evals 없이 “잘 되는 것 같다”로 끝남. false positive·false negative를 못 잡음. 스킬 개수가 늘수록 description 정밀도가 생명선이다.
Capability Uplift를 영원한 걸로 봄 — 모델 업그레이드 시 evals로 필요성 재검증 안 함. “이제 기본 모델이 해결하네?”를 감지할 때까지 evals를 돌려야 한다.
한 스킬에 여러 작업을 넣음 — 트리거가 애매해지고, 유지보수 불가. “블로그 + SNS + 뉴스레터” 같은 통합 스킬은 나중에 쪼개기 힘들다.
scripts/references를 SKILL.md에 중복 — SKILL.md는 핵심 절차만, 상세 내용은 references/로 분리. SKILL.md와 references에 같은 정보를 두면 중복 유지보수만 늘어난다.

실패 포인트 요약: description 설계·트리거 검증·evals를 건너뛰는 게 가장 흔한 실패이다. “일단 만들어보자”로 시작하면 나중에 10번 고쳐도 트리거가 안정되지 않는다. use case 정의 5분을 아끼지 마라.

질문 후크: “실수 TOP 5 중 하나라도 해당되면, evals 3개를 먼저 붙이고 description을 다시 설계하자.”

FAQ

Q1. 프롬프트랑 스킬이 뭐가 다른가요?

프롬프트는 매번 새로 적는 일회성 지시입니다. 스킬은 재사용 가능한 템플릿으로, name + description으로 트리거되고, 본문이 로드됩니다. 2~3번 반복되면 프롬프트를 저장하고, 3~5번 반복되면 스킬로 만드는 게 좋습니다. 볼트 내 CLAUDE.md 규칙도 “2~3번 반복 시 프롬프트 저장, 3~5번 반복 시 스킬 생성”을 권장한다. 프롬프트는 컨텍스트에 매번 넣어야 하고, 스킬은 트리거될 때만 본문이 로드되므로 토큰 효율이 좋다.

Q2. skill-creator 없이 수동으로 만들어도 되나요?

됩니다. skill-creator는 “자연어 설명 → SKILL.md” 변환을 도와주는 메타 스킬입니다. 수동으로 SKILL.md를 작성해도 구조는 동일합니다. 다만 evals·벤치마크·description 튜닝은 skill-creator가 편합니다. Claude.ai, Cowork, Claude Code 플러그인, Anthropic skills 레포에서 모두 사용 가능하다. init_skill.py로 템플릿 생성, quick_validate.py로 검증하는 흐름은 수동으로도 할 수 있지만, skill-creator가 한 번에 처리해준다.

Q3. Cursor에서 만든 스킬을 Claude Code에서 쓸 수 있나요?

구조가 호환됩니다. SKILL.md + frontmatter 형식이 같고, 경로만 다릅니다. Cursor는 .cursor/skills/, Claude Code는 플러그인/레포 기준입니다. 복사해서 쓰면 됩니다. Codex skill-creator와 Claude Code skill-creator는 같은 SKILL.md 구조를 쓰므로 이식이 쉽다.

Q4. description이 200자 넘으면 어떻게 하나요?

API 기준 200자 제한이 있고, 일부 문서는 1024자까지 허용한다고 합니다. 200자 안에 “무엇을 + 언제”를 압축하는 게 우선입니다. 안 되면 references/에 상세 트리거 가이드를 두고, description에서는 핵심만 적습니다. skill-creator의 description 튜닝 기능이 샘플 프롬프트 대비 개선안을 제안해주니 활용하자.

Q5. evals를 어떻게 작성하나요?

테스트 프롬프트 + 기대 결과 + pass 기준을 표로 만듭니다. 예: “BTC 시황 분석해줘” → 가격·OI·펀딩비 포함 마크다운 → 3개 지표 모두 존재. skill-creator(2026년 3월 업데이트)가 evals 작성·실행·분석을 도와줍니다. comparator agent로 스킬 버전 A/B 비교, 스킬 유무 비교도 가능하다. 코드 없이 테스트할 수 있게 설계됐다.

skill-creator 2026년 3월 업데이트 한 줄 요약

Anthropic이 2026년 3월 3일에 발표한 skill-creator 개선 사항:

evals: 테스트 프롬프트 + 기대 결과로 스킬 품질 검증. PDF 스킬 non-fillable 폼 실패를 evals로 격리·수정한 사례 공개.
벤치마크: pass rate, 소요 시간, 토큰 사용량 추적. 모델 업그레이드 후 재측정용.
multi-agent: evals를 병렬 실행해 컨텍스트 오염 없이 빠르게. 각 에이전트가 독립 컨텍스트로 실행.
comparator agent: 스킬 A vs B, 스킬 유무 A/B 비교. 어떤 쪽이 더 나은지 블라인드로 판단.
description 튜닝: 샘플 프롬프트 대비 description 분석, false positive·false negative 줄이는 제안. document-creation 스킬 6개 중 5개에서 트리거 개선 확인.

Claude.ai, Cowork, Claude Code 플러그인, Anthropic skills 레포에서 모두 사용 가능하다.

질문 후크: “evals·벤치마크·description 튜닝이 뭔지 모르겠다면, 위 5가지만 기억하면 된다. 코드 없이 검증·개선할 수 있게 설계됐다.”

공식 출처 / 참고 자료

출처	URL	용도
Anthropic Complete Guide	https://claude.com/blog/complete-guide-to-building-skills-for-claude	15–30분 첫 스킬, 워크플로 4단계, 2026년 1월 29일 발표
skill-creator 개선 (2026-03-03)	https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills	Capability Uplift vs Encoded Preference, evals·벤치마크·description 튜닝, multi-agent 병렬 실행
Claude Code Skills 문서	https://docs.claude.com/en/docs/claude-code/skills	SKILL.md 구조, progressive disclosure, frontmatter 규격
The Complete Guide PDF	https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf	32페이지 공식 PDF, 2026년 1월

Skills 정식 출시는 2025년 10월, Complete Guide 발표는 2026년 1월 29일, skill-creator evals·벤치마크 업데이트는 2026년 3월 3일이다. description 최대 길이는 API 기준 200자, 일부 문서는 1024자까지, name은 64자 이내다.

다음에 읽을 글

한 줄 요약: use case 5분 + description 설계 + evals 3개. 이 세 가지만 지키면 스킬 품질이 눈에 띄게 올라간다. 32페이지 PDF 대신 이 글만 훑어도 핵심은 다 잡을 수 있다.

다음 액션: 내가 반복해서 설명하는 작업 3개를 적고, 각각 Capability Uplift인지 Encoded Preference인지 라벨링해보자. 가장 자주 쓰는 워크플로 1개를 골라 trigger 문구, 출력 형식, 금지 패턴까지 적은 최소 스킬 초안을 만든다. 이번 주 안에 evals 3개를 붙여서 description 수정 후 “트리거가 망가졌나?”를 확인해보자.