Claude Code 스킬이 로드되게 쓰는 5가지 규칙

2026년 GitHub에서 가장 빠르게 성장하는 카테고리는 프레임워크도, 모델도, 데이터베이스도 아닙니다. 마크다운 파일이 들어 있는 폴더입니다. Matt Pocock의 skills 저장소는 254,000개가 넘는 스타를 기록했습니다. Jesse Vincent의 superpowers는 284,000개를 훌쩍 넘습니다. 이 둘 사이에서 자동 추적 도구들은 Claude Code skill 정의를 포함한 저장소를 24,000개 이상 색인했습니다. 6개월 전 약 2,000개였던 것과 비교하면 크게 늘어난 수치입니다.

📖 차트와 출처가 포함된 전체 버전은 AgentConn에서 확인하세요 →

그리고 그 대부분은 제대로 작동하지 않습니다.

에러를 내는 식으로 망가진 것이 아닙니다. .claude/skills/ 디렉터리에 구조적으로는 유효한 skill로 들어 있지만 Claude가 절대 로드하지 않는 식으로 망가져 있습니다. 트리거되어야 할 프롬프트를 입력해도 Claude는 대신 기본 도구를 사용합니다. claude-code 이슈 트래커에는 반복되는 패턴이 있습니다. 개발자들은 자신의 32개 skill 중 1개만 로드된다고 보고하거나, slash command에서는 동작하지만 자연어로는 절대 실행되지 않는다거나, 버전 업그레이드 후 어제까지 되던 skill이 조용히 망가졌다고 보고합니다.

GitHub에서 mattpocock/skills 보기 →

이 생태계는 skill을 "그냥 마크다운"처럼 취급합니다. 파일 하나 넣어두면 Claude가 알아서 파악할 거라는 식입니다. 하지만 그런 관점은 실제 실패 모드를 가립니다. 이 글은 Anthropic의 공식 문서와 상위 skill 저장소들의 패턴, 그리고 가장 흔한 버그 리포트에서 다섯 가지 구조적 규칙을 뽑아냅니다. 이 규칙을 따르면 skill이 로드됩니다. 어기면 skill은 가만히 멈춰 있고, 당신은 모델 탓만 하게 됩니다.

▶ 영상: https://youtu.be/xM2RiVOKR4Y

Skill 로딩 모델: 실제로 일어나는 일

규칙에 들어가기 전에, Claude가 skill을 로드할지 어떻게 판단하는지 이해해야 합니다. 대부분의 개발자가 떠올리는 정신 모델 — "Claude가 내 모든 skill을 읽고 가장 좋은 것을 고른다" — 은 틀렸습니다.

Anthropic의 공식 skills 문서에 따르면 실제 과정은 이렇습니다.

1. 세션 시작 시 , Claude는 각 skill의 YAML frontmatter에서 name과 description 필드만 읽습니다. 본문은 읽지 않습니다. 스크립트도 읽지 않습니다. 오직 그 두 필드만 읽습니다.

2. 프롬프트를 보내면 , Claude는 사용자의 요청을 해당 description과 의미적으로 매칭합니다. description이 맞으면 전체 SKILL.md 본문을 컨텍스트에 로드합니다.

3. 본문은 지시사항으로 실행됩니다 . Claude는 skill이 지정한 도구들 — Bash, 파일 작업, 브라우저 등 무엇이든 — 을 사용해 skill의 단계를 따릅니다.

핵심 함의는 이것입니다. description만이 당신의 skill과 망각 사이를 가르는 유일한 방어선입니다. 본문은 완벽하지만 description이 모호한 skill은 절대 실행되지 않습니다. 본문이 평범하더라도 description이 정확한 skill은 매번 실행됩니다.

공식 skills 문서 보기 →

⚠️ 트리거는 description이지, 이름이 아닙니다 — Claude는 skill 이름으로 매칭하지 않습니다. description으로 매칭합니다. deploy-staging이라는 이름에 "배포를 돕습니다"라는 description을 가진 skill은, "현재 브랜치를 staging 환경에 배포하고, 스모크 테스트를 실행한 뒤 배포 URL을 보고합니다"라는 description을 가진 ship-it skill에 집니다.

이것이 "skill이 로드되지 않는다"는 보고의 가장 흔한 원인입니다 — 그리고 이것이 곧바로 규칙 1로 이어집니다.

규칙 1: description은 요약이 아니라 트리거로 작성하라

description 필드의 역할은 하나뿐입니다. 올바른 프롬프트가 들어왔을 때 Claude가 이 skill을 로드하게 만드는 것입니다. README 요약이 아닙니다. 마케팅 문구도 아닙니다. 의미론적 트리거입니다.

나쁜 description:

name: code-review
description: "A skill for reviewing code"

Claude는 “A skill for reviewing code”를 읽고도 언제 사용해야 하는지 전혀 알 수 없습니다. “이 PR 확인해줘”일까요? “이 함수가 맞아?”일까요? “내 아키텍처를 검토해줘”일까요? 설명만으로는 신호가 없습니다.

좋은 설명:

name: code-review
description: "Review the current diff, PR, or branch for correctness bugs, security issues, and performance problems. Use when asked to review code, check a PR, audit changes, or find bugs in a diff."

이 설명에는 개발자가 실제로 입력할 법한 정확한 문구가 들어 있습니다: “review code,” “check a PR,” “audit changes,” “find bugs.” Claude의 의미론적 매칭이 걸어들어갈 대상이 생깁니다.

상위 저장소에서 보이는 패턴: Matt Pocock의 skills 저장소는 트리거 문구들의 집합처럼 읽히는 설명을 사용합니다. 그의 plan skill 설명은 단순히 “계획을 돕는다”가 아니라, 계획 작성, 구현 설계, 트레이드오프 고려 같은 구체적인 상황을 나열합니다. Jesse Vincent의 superpowers도 같은 패턴을 따르며, 각 설명에 그 skill을 언제 써야 하는지와 언제 쓰지 말아야 하는지가 명시되어 있습니다.

💡 트리거를 테스트하라 — 설명을 작성한 뒤, 실제 개발자가 쓸 법한 서로 다른 5가지 표현으로 테스트해 보세요. 그중 하나라도 skill을 트리거하지 못하면, 그 표현을 설명에 추가하세요. 일상적인 표현으로도 테스트하세요 — “fix this mess”는 단순히 “debug the application”이 아니라 디버깅 skill을 트리거해야 합니다.

▶ 영상: https://youtu.be/2BtNfWFA2lU

규칙 2: 하나의 skill, 하나의 역할 — 그리고 500줄 이하로 유지하라

모든 것을 하려는 skill은 아무것도 제대로 하지 못합니다. 이것은 철학이 아니라 컨텍스트 예산의 제약입니다.

Claude의 컨텍스트 윈도우는 한정되어 있습니다. 로드되는 모든 skill 본문은 코드베이스, 대화 기록, 그리고 다른 활성 skill과 공간을 경쟁합니다. 배포, 테스트, 린팅, 문서화를 모두 아우르는 2,000줄짜리 skill은 사용자가 요청하지도 않은 세 가지 워크플로우에 컨텍스트 토큰을 낭비하는 것입니다.

상위 저장소들은 이를 가차 없이 적용합니다.

• superpowers는 워크플로우를 브레인스토밍, 계획 작성, 테스트 주도 개발, 코드 리뷰, 검증 등 14개의 별도 skill로 나눕니다. 각 skill은 정확히 하나의 일만 합니다.

• mattpocock/skills는 각 skill을 집중된 SKILL.md를 가진 별도 폴더로 패키징합니다. 어떤 skill도 여러 워크플로우를 함께 다루려 하지 않습니다.

500줄 규칙: 여러 커뮤니티 가이드와 Anthropic의 자체 모범 사례는 SKILL.md를 500줄 미만으로 유지할 것을 권장합니다. skill에 참조 자료가 필요하다면 — API 문서, 스키마 정의, 스타일 가이드 — 이를 skill이 필요할 때 불러오는 references/ 하위 디렉터리로 옮기세요.

1234567.claude/skills/deploy/
  SKILL.md           # < 500 lines — the instructions
  references/
    aws-regions.md   # loaded only when needed
    env-vars.md      # loaded only when needed
  scripts/
    deploy.sh        # deterministic work in scripts, not prompts

💡 결정적 작업을 위한 스크립트 — 수학 계산, 파일 이름 변경, 고정된 매개변수를 가진 API 호출처럼 정답이 하나뿐인 것은 skill의 지침이 아니라 번들된 스크립트에 넣어야 합니다. skill은 “scripts/deploy.sh를 실행하라”고 말하고; 스크립트가 결정적 작업을 수행합니다. 이렇게 하면 토큰 낭비를 줄이고 모델이 지침을 잘못 해석하는 일을 없앨 수 있습니다.

규칙 3: 파일 시스템 계약을 존중하라

파일 시스템 레이아웃이 잘못되면 skill은 조용히 실패합니다. 오류 메시지는 없습니다. skill은 그냥 나타나지 않습니다. Anthropic 문서와 버그 리포트가 확인하는 구조적 요구사항은 다음과 같습니다.

파일 이름은 정확히 SKILL.md여야 합니다. 대문자 S, 대문자 K, 대문자 I, 대문자 L, 대문자 L, 점, 대문자 M, 대문자 D. macOS와 Linux에서는 파일 이름이 대소문자를 구분합니다. skill.md, Skill.md, SKILLS.md는 인식되지 않습니다.

각 skill은 자신만의 디렉터리를 가져야 합니다. 폴더 하나당 SKILL.md 하나입니다. 같은 디렉터리 트리의 서로 다른 깊이에 두 개의 SKILL.md 파일을 두면 하나만 로드되며, 어느 것이 로드될지는 정의되어 있지 않습니다.

디렉터리 구조가 중요합니다:

12345678# CORRECT
.claude/skills/my-skill/SKILL.md

# WRONG — double-nested
.claude/skills/my-skill/my-skill/SKILL.md

# WRONG — no wrapper directory
.claude/skills/SKILL.md

개인 범위 vs. 프로젝트 범위:

• ~/.claude/skills/ /SKILL.md — 개인 skill, 모든 프로젝트에서 사용 가능

• .claude/skills/ /SKILL.md — 프로젝트 skill, 저장소에 커밋되며 팀과 공유됨

YAML frontmatter는 필수입니다. 파일 맨 위의 --- 마커 사이에 name과 description 필드가 반드시 있어야 합니다. frontmatter가 없는 SKILL.md는 skill이 아니라 일반 Markdown 파일로 취급됩니다.

123456name: my-skill
description: "What this skill does and when Claude should use it"

# My Skill Instructions

Steps go here...

이름 제약: name 필드는 slash-command 이름과도 같습니다. 소문자, 숫자, 하이픈만 사용하세요. Code_Review나 my skill 같은 이름은 문제를 일으킵니다. 그리고 예약 키워드와 충돌하는 이름은 절대 사용하지 마세요 — help, clear, config, init 같은 내장 명령이 skill을 가려버립니다.

skills가 로드되지 않는 GitHub 이슈 보기 →

⚠️ 재시작 비용 — Claude Code는 세션 시작 시 skills를 읽습니다. skill을 추가, 이름 변경, 수정하면 변경 사항이 적용되도록 새 세션을 시작해야 합니다. 핫 리로드는 없습니다. 많은 사람이 skill을 수정한 뒤 같은 세션에서 테스트하고, 변화가 없다고 판단해 skill이 고장 났다고 결론 내립니다. 고장 난 것이 아닙니다. 오래된 캐시를 보고 있는 것입니다.

규칙 4: 무엇을 하는지만 말하지 말고, 왜 그런지도 설명하라

고장 난 skills에서 흔히 보이는 패턴은 이유 설명 없이 명령만 나열한 목록입니다.

123456# Deploy Skill

1. Run `npm run build`
2. Run `aws s3 sync ./dist s3://my-bucket`
3. Run `aws cloudfront create-invalidation --distribution-id E123`
4. Post to Slack channel #deploys

이것은 셸 스크립트에는 통합니다. 하지만 skill에는 통하지 않습니다. Claude는 셸 스크립트 인터프리터가 아니라, 판단을 위해 맥락이 필요한 추론 엔진이기 때문입니다.

더 나은 방식:

12345678910111213141516171819# Deploy Skill

## Build
Run `npm run build`. If it fails, read the error output and fix the
issue before proceeding — do NOT deploy a broken build.

## Upload
Sync the dist/ directory to the S3 bucket. Use `--delete` to remove
stale files, but NEVER delete the /assets/legacy/ path (it serves
URLs that external partners have hardcoded).

## Cache Invalidation
Invalidate the CloudFront distribution. This takes 5-15 minutes to
propagate. Do not report "deploy complete" until the invalidation
status shows "Completed".

## Notification
Post to #deploys with the commit SHA, deploy time, and a link to
the CloudFront distribution. Include any build warnings.

두 번째 버전은 각 단계가 왜 중요한지 설명하고, 제약 조건과 예외 사례를 명시하며, 일이 잘못되었을 때 Claude가 무엇을 해야 하는지도 알려 줍니다. 이것이 정상 경로에서만 동작하는 skill과 실제 운영 환경에서 동작하는 skill의 차이입니다.

상위권 저장소들은 모두 이 패턴을 따릅니다. Superpowers의 verification-before-completion skill은 단순히 "테스트를 실행하라"라고만 하지 않습니다. 무엇이 검증된 것으로 간주되는지, 불안정한 테스트는 어떻게 처리할지, 언제 에스컬레이션할지를 설명합니다. Matt Pocock의 code-review skill은 각 우선순위 표식의 의미와 결과를 어떤 형식으로 작성해야 하는지 설명합니다.

▶ 영상: https://youtu.be/2BFN2DtcQMw

규칙 5: 경계를 지켜라 — 해야 할 것과 하지 말아야 할 것

모든 skill에는 명시적인 경계가 있어야 합니다. 그렇지 않으면 Claude는 경계를 벗어납니다. code-review skill을 사용해 코드를 리팩터링할 수도 있고, deploy skill을 사용해 테스트까지 실행할 수도 있습니다. 제약이 없으면 요청 범위를 친절하게 넓혀 주는데, 언어 모델은 원래 그렇게 동작하기 때문입니다.

패턴:

123456789## When to Use This Skill
- When the user asks to review a PR or diff
- When the user asks to check code for bugs
- When the user asks to audit changes before merge

## When NOT to Use This Skill
- Do not refactor or fix the code — only report findings
- Do not run the code or execute tests — this is a static review
- Do not review files outside the diff — scope to changed files only

이것은 방어적 프로그래밍이 아닙니다. 이것이야말로 가장 흔한 실패 모드인 범위 확장을 막아, 최고 품질의 skills가 동작하는 방식입니다. Claude가 skill을 불러왔고 그 skill에 "코드를 수정하지 말라"라고 적혀 있으면, Claude는 변경을 가하지 않고 결과만 보고합니다. 이런 가드가 없으면, Claude는 당신의 코드를 "도와주겠다"며 다시 써 버릴 것입니다. 그런데 review skill이 해야 할 일은 그것이 아닙니다.

disable-model-invocation 탈출구: 자연어 매칭으로는 절대 실행되지 않고 슬래시 명령에서만 실행되는 skill을 원한다면, 프런트매터에 다음을 추가하세요.

name: dangerous-deploy
description: "Deploy to production with zero downtime"
disable-model-invocation: true

이것은 실수로 트리거되면 안 되는 부작용이 있는 skill에 유용합니다. 예를 들어 운영 배포, 데이터 마이그레이션, 계정 작업 등이 그렇습니다.

생태계는 둔화되지 않고 있다

숫자가 이를 말해 줍니다. 2026년 8월 GitHub의 트렌딩 페이지는 agent 인프라가 지배했습니다 — harnesses, skills, memory layers. 모델은 뒷전으로 밀렸습니다. 모델 주변의 기계장치가 이제 가치의 중심이 된 것입니다.

Analytics Vidhya에서 GitHub 트렌딩 분석 보기 →

일부 관찰자들은 더 나아갑니다. OODA Loop 분석은 skills가 MCP 자체보다 더 큰 의미를 가질 수 있다고 주장합니다. skills는 워크플로 지식을 인코딩하기 때문입니다. 이는 보통 선임 엔지니어의 머릿속에 있다가 그들이 회사를 떠나면 사라지는 종류의 조직 내 전문 지식입니다.

이 분야를 만들고 있다면, 이전 보도도 참고하세요.

• Agent Skills Are the New Dotfiles — skills 저장소가 어떻게 GitHub에서 가장 빠르게 성장하는 카테고리가 되었는지

• Config Files That Run Code: The Agent Skill Supply Chain — 다른 사람의 SKILL.md를 가져올 때의 보안 의미

• 하네스에서 실패하지, 모델에서 실패하지 않는다 — 인프라가 모델 선택보다 더 중요한 이유

스킬 모범 사례에 대한 전체 Substack 글 읽기 →

반대 의견 코너: Skills는 "그냥 Markdown"이 아니다

⚠️ 아무도 말하지 않는 반론 — 공개 Skills 생태계에는 어두운 면이 있습니다. GitHub 저장소에서 skill을 설치할 때, 다른 사람의 지침에 코드베이스, 파일 시스템, 셸에 직접 접근할 권한을 주는 셈입니다. 악성 SKILL.md는 Claude에게 환경 변수를 유출하라고 지시하거나, 변경 사항을 숨기기 위해 .gitignore를 수정하거나, 빌드 파이프라인에 코드를 주입하라고 지시할 수 있습니다. claude skills install의 편리함은 분명히 사실입니다. 하지만 공격 표면도 그렇습니다. package.json의 의존성을 검증하듯이 설치하는 모든 skill을 검증하세요. 왜냐하면 그것이 정확히 그 역할이기 때문입니다.

"그냥 markdown"이라는 프레이밍은 좋은 skill을 작성하는 데 실제로 필요한 역량도 흐리게 만듭니다. 설명 필드는 프롬프트 엔지니어링 문제입니다. 본문 구조는 워크플로 설계 문제입니다. 파일 배치는 시스템 통합 문제입니다. skills를 사소한 것으로 취급하는 태도가 GitHub의 24,000개 skill 저장소 중 90%에 있는 skill이 안정적으로 트리거되지 않는 이유입니다.

체크리스트

skill을 게시하거나 설치하기 전에 다음을 확인하세요:

이것이 빌더에게 의미하는 것

Skills는 파워 유저를 위한 있으면 좋은 기능이 아닙니다. 팀이 엔지니어링 워크플로를 인코딩하는 주된 방식이 되어가고 있습니다 — 배포 절차, 리뷰 표준, 테스트 프로토콜, 온보딩 가이드. 잘 구조화된 skills에 투자하는 팀은 생산성을 계속 쌓아 올리게 됩니다. 이를 뒷전으로 미루는 팀은 왜 AI 비서가 "프로젝트를 이해하지 못하는지" 계속 의아해하게 될 것입니다.

다섯 가지 규칙은 복잡하지 않습니다. 심지어 특별히 까다롭지도 않습니다. 하지만 skills를 챗봇에 대한 가벼운 메모가 아니라 소프트웨어 — 계약, 명세, 테스트 전략을 가진 무엇 — 로 생각해야 합니다.

GitHub의 24,000개 저장소는 수요가 실제라는 것을 증명합니다. 버그 보고는 그중 대부분이 망가져 있다는 것을 증명합니다. 이 두 사실 사이의 간극이 바로 여러분의 기회입니다.

하나의 skill부터 시작하세요. 다섯 가지 규칙을 따르세요. 로드되는 모습을 지켜보세요.

원문은 AgentConn에 처음 게시되었습니다.

출처

• 원문: https://dev.to/max_quimby/write-skills-that-load-five-rules-from-500k-stars-4go7 (2026-10-08 · Max Quimby)