mattpocock/skills — Claude 에이전트에 실무 엔지니어링 스킬을 심는 법
TDD, 디버깅, 아키텍처 리뷰까지 — .claude 디렉터리에서 바로 쓰는 22개 에이전트 스킬 모음
mattpocock/skills란 — .claude 디렉터리에서 바로 쓰는 에이전트 스킬 모음
mattpocock/skills는 TypeScript 교육자 Matt Pocock이 자신의 .claude 디렉터리에서 실제 사용하는 22개 에이전트 스킬을 MIT 라이선스로 공개한 GitHub 저장소입니다. 2026년 5월 11일 기준 69,300개 이상의 스타와 6,000개 이상의 포크를 기록하고 있습니다.
Claude Code를 쓰다 보면 에이전트가 코드 생성은 잘하는데, 팀의 개발 프로세스까지 따르게 만들기는 어렵습니다. TDD 순서를 지키게 하거나, 스펙을 GitHub 이슈로 분할하거나, 아키텍처 결정 기록을 참조해서 코드를 짜게 하려면 매번 프롬프트를 길게 써야 하죠.
mattpocock/skills는 이 문제를 '스킬 파일'이라는 단위로 풀어냅니다. 각 스킬은 SKILL.md라는 마크다운 파일 하나로 구성됩니다. Claude Code가 시작할 때 이름과 설명만 읽어두고, 관련 작업이 감지되면 전체 내용을 로드하는 구조입니다.
Matt Pocock은 Total TypeScript를 운영하는 독립 개발자이자 TypeScript 교육자입니다. 전 XState 코어팀 멤버이자 전 Vercel 개발자 애드보킷이기도 합니다. Anthropic 직원이 아닌 커뮤니티 기여자라는 점은 미리 짚어둡니다.
아래에서 설치법, 핵심 스킬 5선, 도입 시뮬레이션, 운영 모델, 그리고 도입하지 않는 게 나은 경우까지 정리합니다.
69K 스타까지의 성장 — 하루 6,000 스타가 몰린 이유
2026년 2월 3일에 생성된 이 저장소는 4월 말 바이럴을 타면서 하루 최대 6,175개의 스타 증가를 기록했고, GitHub 주간 트렌딩 상위권에 진입했습니다.
성장 속도를 타임라인으로 정리하면 이렇습니다.
| 시점 | 이벤트 | 스타 수 |
|---|---|---|
| 2026-02-03 | 저장소 생성 | — |
| 2026-04-28 | 바이럴 시작, 대규모 스타 유입 | — |
| 2026-04-29 | GitHub 주간 트렌딩 #2 달성 | 39,382 |
| 2026-05-02 | Pocock 유튜브 영상 후 23% 추가 급증 | 45,289 |
| 2026-05-11 | 현재 (검색 시점) | 69,300+ |
제가 보기에 이 수치는 한 레포의 인기를 넘어서는 신호입니다. 같은 주에 andrej-karpathy-skills(97K+), addyosmani/agent-skills(25K+)까지 트렌딩 상위 5개 중 3자리를 스킬 레포가 차지했습니다. 개별 저장소가 뜬 게 아니라 '스킬'이라는 형식 자체가 에이전트 설정의 표준 단위로 굳어지는 흐름입니다.
스킬 파일(SKILL.md)의 구조와 작동 원리
각 스킬은 YAML 프론트매터(name, description)와 마크다운 본문으로 구성된 단일 SKILL.md 파일이며, Claude Code는 시작 시 이름·설명만 메모리에 올리고 필요할 때 전체 내용을 로드합니다.
스킬의 설계 원칙은 '작고, 적응 가능하고, 조합 가능한(small, adaptable, composable)' 단위를 지향합니다. 런타임이나 패키지를 배포하지 않습니다. 마크다운 파일과 선택적 스크립트만으로 동작합니다.
Anthropic은 이 로딩 방식을 Progressive Disclosure라고 부릅니다. 세션이 시작되면 수십 개 스킬의 이름과 한 줄 설명만 메모리에 올라갑니다. 사용자가 `/tdd`를 호출하거나 관련 맥락이 감지될 때 비로소 해당 SKILL.md의 전체 내용을 로드합니다. 컨텍스트 윈도우를 아끼는 구조라, 스킬을 수십 개 설치해도 초기 로딩 비용이 거의 없습니다.
다만 스킬 시스템은 계속 진화 중입니다. YAML 프론트매터 필드나 디렉터리 구조가 향후 변경될 수 있으므로, `npx skills update`로 주기적으로 동기화하는 습관이 필요합니다.
설치부터 첫 실행까지 — 도입 시뮬레이션
설치는 npx skills@latest add mattpocock/skills 한 줄입니다. 설치 후 Claude Code에서 /setup-matt-pocock-skills를 실행하면 이슈 트래커, 트리아지 라벨, 문서 저장 위치를 프로젝트에 맞게 설정합니다.
1단계: 설치
```bash
npx skills@latest add mattpocock/skills
```
Node.js/npm 환경이 필요합니다. 이 명령은 vercel-labs/skills CLI를 통해 스킬 파일들을 로컬에 내려받습니다.
2단계: 프로젝트 설정
Claude Code를 열고 `/setup-matt-pocock-skills`를 실행합니다. 이슈 트래커(GitHub Issues, Linear, 또는 로컬), 트리아지 라벨 어휘, 문서 저장 위치를 묻고 프로젝트별 설정을 생성합니다.
3단계: 첫 테스트
가장 안전한 첫 테스트는 `/grill-me`입니다. '이 기능의 목표가 뭔가요?', '엣지 케이스는 뭐가 있나요?' 같은 질문을 에이전트가 던지기 시작하면 스킬이 정상 로드된 겁니다. 코드를 건드리지 않으면서 스킬이 제대로 붙었는지 확인할 수 있어서 첫 테스트로 좋습니다.
코드 레벨에서 확인하고 싶다면 `/tdd`로 작은 함수의 테스트를 먼저 작성하게 한 뒤, 레드→그린→리팩터 루프가 작동하는지 보는 것도 좋습니다.
경로 불일치 주의
한국 사용자 입장에서 흔히 부딪히는 문제가 하나 있습니다. `npx skills`가 스킬을 `~/.agents/skills/` 경로에 설치하는 반면, Claude Code는 `~/.claude/skills/`에서 스킬을 로드할 수 있습니다. 스킬이 인식되지 않으면 `/doctor` 명령으로 경로를 확인하고, 필요하면 심볼릭 링크(`ln -s`)나 파일 복사로 해결합니다.
핵심 스킬 5선 — 각 스킬이 해결하는 구체적 문제
mattpocock/skills에는 engineering(10개), productivity(3개), misc(4개) 카테고리에 걸쳐 총 16~22개의 스킬이 포함되어 있습니다. 그중 실무에서 가장 자주 쓰이는 5개를 골랐습니다.
`/tdd` — 레드-그린-리팩터 루프 강제
에이전트가 코드부터 쓰려는 습관을 교정합니다. 실패하는 테스트를 먼저 작성하고, 테스트를 통과하는 최소 구현을 작성한 뒤, 리팩터링하는 순서를 강제합니다. 제가 보기에는 이 스킬 하나만으로도 설치 가치가 있습니다.
`/diagnose` — 체계적 디버깅 프로세스
버그를 만나면 에이전트가 재현→최소화→가설 수립→계측→수정→회귀 테스트 순서를 따릅니다. '일단 코드 바꿔보기'식 디버깅을 막고 엔지니어링 디버깅 프로세스를 적용하는 스킬입니다.
`/grill-me` — 의사결정 분기 질문 프레임워크
구현을 시작하기 전에 에이전트가 모든 의사결정 분기를 질문으로 파악합니다. '이 API의 인증 방식은?', '실패 시 롤백 전략은?' 같은 질문을 통해 요구사항의 빈틈을 미리 잡아냅니다.
`/caveman` — 토큰 소비 약 75% 절감 모드
> 주의: 75% 절감은 Pocock의 추정치이며 공식 벤치마크는 아닙니다.
기술적 정밀도를 유지하면서 에이전트 통신을 초압축합니다. 대규모 리팩터링이나 컨텍스트 윈도우가 빠듯한 작업에서 활성화하면 유용합니다.
`/to-issues` — 스펙을 수직 슬라이스 GitHub 이슈로 변환
PRD나 스펙 문서를 넣으면 에이전트가 수직 슬라이스(vertical slice) 단위로 GitHub 이슈를 생성합니다. 이슈 하나가 프론트엔드부터 백엔드까지 관통하는 단위로 쪼개져서, 각 이슈가 독립적으로 배포 가능한 형태가 됩니다.
운영 모델 — CONTEXT.md와 ADR로 스킬 효과를 높이는 법
CONTEXT.md에 프로젝트의 도메인 용어를 정의하면 여러 스킬이 공유 어휘를 사용해 변수명·함수명·파일명의 일관성이 올라가고, docs/adr/ 디렉터리에 Architecture Decision Records를 관리하면 아키텍처 관련 스킬의 정확도가 높아집니다.
실제로 확인할 부분은 스킬 설치 자체보다 이 두 가지 문서 패턴의 정착입니다.
CONTEXT.md — 프로젝트 도메인 용어집
프로젝트 루트에 CONTEXT.md를 생성하고 도메인 특유의 용어를 정의합니다. 예를 들어 '물질화 캐스케이드(materialization cascade)'라는 프로젝트 내부 개념이 있다면 여기에 적어두면, `/grill-with-docs`, `/improve-codebase-architecture` 등 여러 스킬이 이 용어를 참조하면서 에이전트와 사람 사이의 어휘 차이를 줄입니다.
docs/adr/ — 아키텍처 결정 기록
Architecture Decision Records를 관리하면 `/improve-codebase-architecture` 스킬이 기존 결정을 참조해서 일관된 아키텍처 제안을 합니다. ADR이 없으면 에이전트가 매번 백지에서 판단하게 되므로 제안의 일관성이 떨어집니다.
스킬 업데이트
`npx skills update` 명령으로 최신 버전과 동기화합니다. 스킬 시스템이 활발히 진화 중이므로 2~4주마다 한 번 정도 업데이트를 확인하는 게 좋습니다.
함께 쓰면 좋은 도구 — karpathy-skills, vercel-labs/skills CLI
Karpathy 스킬(행동 제약)과 Pocock 스킬(워크플로우)을 결합하면 에이전트의 태도와 동작 모두를 표준화할 수 있고, vercel-labs/skills CLI로 다양한 스킬 저장소를 같은 명령 체계로 관리할 수 있습니다.
2026년 5월 기준 GitHub 트렌딩 상위에 스킬 레포 3곳이 동시에 올라왔습니다. 각각 접근이 다릅니다.
| 저장소 | 스타 (검색 시점) | 접근 방식 |
|---|---|---|
| forrestchang/andrej-karpathy-skills | 97K+ | 행동 제약 — '가정하지 말 것', '혼란을 숨기지 말 것' 등 에이전트 태도 규범 |
| mattpocock/skills | 69K+ | 워크플로우 — TDD, 디버깅, 아키텍처 리뷰 등 실무 프로세스 |
| addyosmani/agent-skills | 25K+ | 범용 — 코드 리뷰, 문서화, 테스트 등 일반 개발 스킬 |
Pocock 스킬이 '무엇을 하라'에 집중한다면, Karpathy 스킬은 '어떻게 행동하라'에 집중합니다. 두 가지를 함께 설치하면 에이전트의 작업 프로세스와 커뮤니케이션 태도를 동시에 잡을 수 있습니다.
`vercel-labs/skills` CLI는 이런 스킬 저장소들을 `npx skills@latest add <owner/repo>` 한 줄로 설치·관리·업데이트하는 공식 도구입니다. mattpocock/skills 외에 다른 커뮤니티 스킬도 같은 명령으로 추가할 수 있습니다.
추천 분야와 도입하지 않아야 할 경우
TypeScript/JavaScript 웹 프로젝트, TDD 기반 팀, GitHub Issues 또는 Linear을 이슈 트래커로 사용하는 프로젝트에 가장 잘 맞습니다. 반대로, Claude Code 외 AI 도구만 사용하거나 Node.js 환경이 없는 경우에는 도입 오버헤드가 작업보다 클 수 있습니다.
도입이 효과적인 경우
- TypeScript/JavaScript 웹 프로젝트 — Matt Pocock의 전문 분야와 직결되어 스킬 내용이 이 생태계에 최적화되어 있습니다
- TDD 기반 개발 프로세스를 AI 에이전트로 자동화하려는 팀
- GitHub Issues 또는 Linear을 이슈 트래커로 사용하는 프로젝트 — `/triage`, `/to-issues` 스킬이 이 워크플로우에 맞춰져 있습니다
- 도메인 언어 정의(DDD)와 ADR을 실천하는 중·대규모 프로젝트
도입을 보류하는 게 나은 경우
- Claude Code가 아닌 Cursor·Copilot 등만 사용하는 환경 — Agent Skills 로딩 메커니즘이 Claude Code에 최적화되어 있습니다
- Node.js/npm 환경이 없는 경우 — `npx` 설치 자체가 불가합니다. SKILL.md 파일을 수동 복사하는 방법은 있지만 관리가 번거롭습니다
- 극히 단순한 일회성 스크립트 작업 — `/setup-matt-pocock-skills` 설정 자체가 작업보다 오래 걸릴 수 있습니다
- 이미 팀 고유의 CLAUDE.md 기반 워크플로우가 성숙한 경우 — 기존 설정과 충돌하지 않는지 먼저 평가해야 합니다
주의사항 — 경로 불일치, 추정치, 진화 중인 시스템
mattpocock/skills를 도입할 때 확인해야 할 세 가지가 있습니다. 설치 경로 불일치, 토큰 절감 수치의 성격, 그리고 스킬 시스템의 변경 가능성입니다.
설치 경로 불일치
`npx skills`가 `~/.agents/skills/`에 파일을 넣는 반면 Claude Code가 `~/.claude/skills/`에서 읽는 경우가 보고되고 있습니다. 설치 후 스킬이 인식되지 않으면 `/doctor` 명령으로 경로를 확인하고 심볼릭 링크(`ln -s ~/.agents/skills ~/.claude/skills`)로 연결하면 됩니다.
토큰 절감 수치는 추정치
`/caveman` 스킬의 75% 토큰 절감은 Pocock이 자신의 사용 경험에서 제시한 수치입니다. Anthropic의 공식 벤치마크가 아니므로 실제 절감 폭은 프로젝트와 작업 유형에 따라 달라집니다.
마지막으로, Agent Skills 자체가 Anthropic이 2025년 10월 발표한 오픈 스탠다드이며 현재도 활발히 발전하고 있습니다. YAML 프론트매터 필드, 디렉터리 구조, CLI 명령어가 바뀔 수 있으므로 공식 문서를 주기적으로 확인하시기 바랍니다.
자주 묻는 질문
Q. mattpocock/skills 설치는 어떻게 하나요?
A. npx skills@latest add mattpocock/skills 한 줄로 설치합니다. Node.js/npm 환경이 필요하며, 설치 후 Claude Code에서 /setup-matt-pocock-skills를 실행해 이슈 트래커와 라벨을 설정합니다. 스킬이 인식되지 않으면 설치 경로(~/.agents/skills/)와 Claude Code 로드 경로(~/.claude/skills/)가 다른지 확인합니다.
Q. 나만의 커스텀 Claude 스킬을 만들 수 있나요?
A. 가능합니다. /write-a-skill 스킬을 실행하면 새 스킬 작성 가이드가 시작됩니다. SKILL.md 파일에 YAML 프론트매터(name, description)와 마크다운 본문을 작성하면 되며, ~/.claude/skills/ 디렉터리에 저장하면 Claude Code가 자동 인식합니다.
Q. mattpocock/skills는 Cursor나 Codex 같은 다른 AI 도구에서도 쓸 수 있나요?
A. SKILL.md 포맷과 Progressive Disclosure 로딩은 Claude Code(및 Claude Agent SDK)에 최적화되어 있습니다. 다른 AI 도구에서 SKILL.md 파일 자체를 프롬프트 참조 문서로 사용하는 건 가능하지만, 자동 로드·슬래시 명령 호출 같은 네이티브 통합은 Claude Code 환경에서만 동작합니다.
Q. /tdd 스킬을 실행하면 에이전트가 구체적으로 어떤 순서를 따르나요?
A. 레드-그린-리팩터 순서를 강제합니다. 먼저 실패하는 테스트를 작성하고(레드), 테스트를 통과하는 최소한의 구현을 작성한 뒤(그린), 코드를 정리합니다(리팩터). 에이전트가 테스트 없이 코드부터 작성하려는 기본 습성을 교정하는 스킬입니다.
Q. 팀 프로젝트에 mattpocock/skills를 도입하려면 무엇부터 해야 하나요?
A. 먼저 프로젝트 루트에 CONTEXT.md를 만들어 도메인 용어를 정의합니다. 그다음 npx skills@latest add mattpocock/skills로 설치하고 /setup-matt-pocock-skills로 팀의 이슈 트래커(GitHub Issues 또는 Linear)를 연결합니다. 소규모 기능 하나에 /tdd를 적용해보고, 기존 CLAUDE.md 설정과 충돌이 없는지 확인한 뒤 점진적으로 확대하는 것을 권합니다.
참조 링크
- mattpocock/skills — Skills for Real Engineers (공식 GitHub 저장소) — 스킬 목록, 설치법, README, CONTEXT.md, ADR 패턴 원본
- Extend Claude with skills — Claude Code 공식 스킬 문서 — SKILL.md 포맷, YAML 프론트매터, Progressive Disclosure 공식 레퍼런스
- Equipping agents for the real world with Agent Skills — Anthropic 엔지니어링 블로그 — Agent Skills 오픈 스탠다드 설계 철학과 아키텍처
- vercel-labs/skills — npx skills CLI 공식 저장소 — npx skills@latest add 명령어의 원본 CLI 도구
- Matt Pocock Skills Repo Jumps Past 45K Stars — 45K 스타 돌파 분석 및 유튜브 영상 후 성장 데이터
- GitHub Trending Weekly 2026-04-29 — 스킬 생태계 주간 트렌딩 — 스킬 레포 3곳 동시 트렌딩 상위권 분석
- mattpocock/skills — Trendshift 트렌딩 통계 — 스타 증가 추이 및 일별 성장 패턴
- Claude Code Skills Not Found After NPX Install — 경로 불일치 트러블슈팅 — ~/.agents/skills/ vs ~/.claude/skills/ 경로 불일치 해결법
- Matt Pocock — TypeScript Educator 공식 사이트 — Matt Pocock 인물 정보 출처