로드되는 스킬을 작성하는 방법: 50만 개 스타에서 얻은 다섯 가지 규칙

2026년 GitHub에서 가장 빠르게 성장하는 카테고리는 프레임워크, 모델 또는 데이터베이스가 아닙니다. 그것은 Markdown 파일을 포함하는 폴더입니다. Matt Pocock의 skills repo는 254,000개의 스타를 돌파했습니다. Jesse Vincent의 superpowers는 284,000개 이상을 기록하고 있습니다. 이들 사이에서 자동화된 트래커들은 Claude Code 스킬 정의가 포함된 24,000개가 넘는 저장소를 색인했으며, 이는 6개월 전의 약 2,000개 대비 증가한 수치입니다.

📖 차트와 임베디드 소스가 있는 전체 버전은 AgentConn →에서 읽기

그리고 그들 대부분은 작동하지 않습니다(broken).

에러를 발생시키는 방식으로 작동하지 않는 것이 아닙니다. 스킬이 .claude/skills/ 디렉토리에 구조적으로 유효하게 존재하지만, Claude가 이를 로드하지 못하는 방식입니다. 사용자가 트리거해야 할 프롬프트를 입력해도, Claude는 기본 도구(default tools)를 찾습니다. claude-code issue tracker에는 반복되는 패턴이 있습니다: 개발자들은 32개의 스킬 중 단 1개만 로드된다고 보고하거나, 슬래시 명령어(slash command)로는 작동하지만 자연어에서는 절대 발동하지 않는 스킬을 보고하거나, 어제까지 작동하던 스킬이 버전 업그레이드를 통해 조용히 깨지는 경우를 보고합니다.

GitHub에서 mattpocock/skills 보기 →

이 생태계는 스킬을

규칙을 알기 전에, Claude가 스킬을 로드할지 여부를 어떻게 결정하는지 이해해야 합니다. 대부분의 개발자가 가지고 있는 정신 모델인 'Claude가 내 모든 스킬을 읽고 가장 좋은 것을 고를 것이다'는 잘못된 생각입니다.

Anthropic 공식 스킬 문서에 따르면 실제 작동 방식은 다음과 같습니다:

1. 세션 시작 시, Claude는 각 스킬의 YAML 프런트매터(frontmatter)에서 name과 description 필드만 읽습니다. 본문이나 스크립트는 아닙니다. 오직 이 두 필드뿐입니다.
2. 프롬프트를 보낼 때, Claude는 사용자의 요청을 해당 설명들과 의미론적으로 일치시킵니다(semantically matches). 만약 설명이 일치하면, 전체 SKILL.md 본문을 컨텍스트로 로드합니다.
3. 본문은 지침으로 실행됩니다. Claude는 스킬이 지정한 도구—Bash, 파일 작업, 브라우저 등—를 사용하여 스킬의 단계를 따릅니다.

핵심적인 시사점: 설명이 여러분의 스킬과 망각 사이를 가르는 유일한 장벽입니다. 완벽한 본문을 가졌지만 모호한 설명을 가진 스킬은 절대 작동하지 않을 것입니다. 평범한 본문이지만 정확한 설명을 가진 스킬이 매번 작동할 것입니다.

공식 스킬 문서 보기 →

⚠️ 설명이 트리거이며, 이름이 아닙니다 — Claude는 스킬 이름을 기준으로 일치시키지 않습니다. 설명(description)을 기준으로 일치시킵니다. '배포-스테이징(deploy-staging)'이라는 이름에

name: code-review
description: "코드 검토에 사용되는 스킬"
...

Claude는 "코드 검토에 사용되는 스킬"이라는 설명을 읽고 언제 이 스킬을 사용해야 할지 알지 못합니다. "이 PR 확인해 줄래?"와 같은 요청일까요? 아니면 "이 함수가 맞는지 봐줘?" 일까요? 혹은 "내 아키텍처를 검토해 줘?" 일까요? 설명만으로는 아무런 신호도 주지 않습니다.

좋은 설명:

---
name: code-review
description: "현재 diff, PR 또는 브랜치를 정확성 버그, 보안 문제 및 성능 문제를 위해 검토합니다. 코드 검토 요청을 받거나, PR 확인, 변경 사항 감사(audit), 또는 diff에서 버그를 찾을 때 사용하세요."
...

이 설명에는 개발자가 실제로 입력할 법한 구체적인 문구들, 즉 "코드 검토(review code)", "PR 확인(check a PR)", "변경 사항 감사(audit changes)", "버그 찾기(find bugs)"가 포함되어 있습니다. Claude의 의미론적 매칭(semantic matching)은 붙잡을 만한 무언가를 얻게 됩니다.

최상위 레포지토리에서 가져온 패턴: Matt Pocock의 스킬 레포는 트리거 구문들의 합집합처럼 보이는 설명을 사용합니다. 그의 plan 스킬 설명은 단순히 "계획 수립에 도움을 준다"가 아니라, 계획 작성, 구현 설계, 트레이드오프 고려 등 구체적인 시나리오들을 나열합니다. Jesse Vincent의 슈퍼파워(superpowers)도 같은 패턴을 따르며, 각 설명에서 언제 스킬을 사용해야 하고 언제 사용하지 말아야 하는지를 명시적으로 언급합니다.

💡 트리거 테스트하기 — 설명을 작성한 후, 실제 개발자가 사용할 법한 5가지 다른 표현으로 테스트해 보세요. 만약 그중 어느 것도 스킬을 트리거하지 못한다면, 해당 구문들을 설명에 추가하세요. 일상적인 언어로도 테스트해 보세요. "이 난장판 좀 고쳐줘"는 단순히 "애플리케이션 디버깅(debug the application)"하는 것이 아니라 디버깅 스킬을 트리거해야 합니다.

규칙 2: 하나의 스킬, 하나의 역할 — 그리고 500줄 이내 유지하기

모든 것을 하려고 하는 스킬은 아무것도 잘하지 못합니다. 이것은 철학이 아니라 컨텍스트 예산 제약(context budget constraint)입니다.

Claude는 유한한 컨텍스트 창(context window)을 가지고 있습니다. 로드되는 모든 스킬 본문은 코드베이스, 대화 기록, 그리고 다른 활성화된 스킬들과 공간을 두고 경쟁합니다. 배포(deployment), 테스트(testing), 린팅(linting), 문서화(documentation)를 모두 다루는 2,000줄짜리 스킬은 사용자가 요청하지 않은 세 가지 워크플로우에 컨텍스트 토큰을 소모하고 있습니다.

최상위 레포지토리들은 이를 가차 없이 강제합니다:

• superpowers는 워크플로우를 브레인스토밍, 계획 작성, 테스트 주도 개발(test-driven development), 코드 검토(code review), 검증 등 14개의 개별 스킬로 분할합니다. 각 스킬은 오직 하나의 작업만 수행합니다.
• mattpocock/skills는 각 스킬을 자체 폴더로 패키징하고, 그 안에 초점을 맞춘 SKILL.md 파일을 포함합니다. 어떤 스킬도 여러 워크플로우를 다루려고 시도하지 않습니다.

500줄 규칙: 여러 커뮤니티 가이드와 Anthropic의 모범 사례는 SKILL.md 파일은 500줄을 넘지 않도록 유지할 것을 권장합니다. 만약 스킬이 참고 자료(API 문서, 스키마 정의, 스타일 가이드 등)가 필요하다면, 이를 references/ 하위 디렉터리로 이동시키고 해당 스킬이 필요할 때 로드하도록 합니다.

.
claude/skills/deploy/
  SKILL.md           # < 500 lines — 지침(instructions)
  references/
...

💡 결정론적 작업을 위한 스크립트(Scripts for Deterministic Work) — 정답이 하나인 모든 것(수학 계산, 파일 이름 변경, 고정 매개변수를 가진 API 호출 등)은 스킬의 지침에 넣는 것이 아니라 번들된 스크립트에 속해야 합니다. 스킬은

• ~/.claude/skills/<name>/SKILL.md — 개인 스킬(personal skills), 모든 프로젝트에서 사용 가능
• .claude/skills/<name>/SKILL.md — 프로젝트 스킬(project skills), 레포지토리에 커밋되며 팀과 공유됨

YAML 프론트매터가 필수입니다. name 및 description 필드는 파일 상단에 --- 마커 사이에 존재해야 합니다. 프론트매터가 없는 SKILL.md는 스킬이 아닌 일반 Markdown 파일로 처리됩니다.

---
name: my-skill
description: "이 스킬의 기능과 Claude가 언제 사용해야 하는지"
...

이름 제약 조건: name 필드는 슬래시 명령어 이름으로도 사용됩니다. 소문자, 숫자, 하이픈만 사용하세요. Code_Review나 my skill 같은 이름은 문제를 일으킵니다. 그리고 help, clear, config, 또는 init과 같이 예약 키워드와 충돌하는 이름은 절대 사용하지 마세요. 이러한 내장 명령어들은 스킬을 가릴 수 있습니다.

스킬이 로드되지 않는 GitHub 이슈 보기 →

⚠️ 재시작 비용(The Restart Tax) — Claude Code는 세션 시작 시 스킬을 읽습니다. 스킬을 추가, 이름 변경 또는 수정했다면, 변경 사항이 적용되도록 새 세션을 시작해야 합니다. '핫 리로드' 기능은 없습니다. 이 때문에 사람들은 스킬을 편집하고 같은 세션에서 테스트한 후 변화가 보이지 않자 스킬이 고장 났다고 결론 내립니다. 하지만 그렇지 않습니다. 오래된 캐시를 보고 있는 것입니다.

규칙 4: 무엇(What)뿐만 아니라 왜(Why)도 설명하라

고장 난 스킬에서 흔히 볼 수 있는 패턴은 이유 없이 명령어 목록을 나열하는 것입니다.

# 배포 스킬 (Deploy Skill)

1. `npm run build` 실행
...

이것은 셸 스크립트에는 작동합니다. 하지만 Claude는 셸 스크립트 인터프리터가 아니기 때문에 스킬에는 작동하지 않습니다. Claude는 판단을 내리는 데 컨텍스트가 필요한 추론 엔진입니다.

더 좋은 방법:

# 배포 스킬 (Deploy Skill)

## 빌드(Build)
...

두 번째 버전은 각 단계가 왜 중요한지 설명하고, 제약 조건과 엣지 케이스를 명시하며, 문제가 발생했을 때 Claude가 무엇을 해야 하는지 알려줍니다. 이것이 단순히 '행복한 경로(happy path)'에서 작동하는 스킬과 실제 운영 환경(production)에서 작동하는 스킬의 차이점입니다.

최상위 레포지토리들은 모두 이 패턴을 따릅니다. Superpowers의 verification-before-completion 스킬은 단순히 '테스트 실행'이라고만 말하지 않습니다. 무엇이 검증된 것으로 간주되는지, 불안정한 테스트(flaky tests)는 어떻게 처리해야 하는지, 그리고 언제 에스컬레이션할지를 설명합니다. Matt Pocock의 code-review 스킬은 각 우선순위 마커가 무엇을 의미하는지, 그리고 발견 사항을 어떻게 형식화해야 하는지 설명합니다.

규칙 5: 경계를 보호하라 — 할 것과 하지 말 것

모든 스킬에는 명시적인 경계(boundaries)가 있어야 합니다. 이것이 없으면 Claude는 이탈할 것입니다. 코드-리뷰 스킬을 사용해서 코드를 리팩토링할 것이고, 배포(deploy) 스킬을 사용해서 테스트도 실행할 것입니다. 언어 모델은 제약 조건 없이 요청한 범위를 기꺼이 확장하기 때문에, 그럴 것입니다.

패턴:

## 언제 이 스킬을 사용할지
- 사용자가 PR 또는 diff 검토를 요청할 때
- 사용자가 버그에 대해 코드를 확인할 때
...

이것은 방어적 프로그래밍(defensive programming)이 아닙니다. 이것이 최고 품질의 스킬들이 가장 흔한 실패 모드인 '범위 확장(scope creep)'을 방지하는 방법입니다. Claude가 스킬을 로드했는데 그 스킬이 '코드를 수정하지 마라'라고 한다면, 변경 사항을 만들지 않고 발견된 사항만 보고할 것입니다. 그런 보호 장치 없이는, 코드를 다시 작성하며 기꺼이 '도움'을 주게 되는데, 이는 리뷰 스킬이 해야 할 일이 아닙니다.

disable-model-invocation 탈출구: 만약 슬래시 명령어(slash command)를 통해서만 작동하고 자연어 매칭을 통해서는 절대 작동하지 않는 스킬을 원한다면, 프론트매터(frontmatter)에 이것을 추가하세요:

---
name: dangerous-deploy
description: "무중단으로 운영 환경에 배포"
...

이것은 실수로 트리거되기를 원하지 않는 부작용(side effects)이 있는 스킬들—운영 환경 배포, 데이터 마이그레이션, 계정 작업 등—에 유용합니다.

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