mattpocock/skills 에 대한 자세한 설명

 

GitHub - mattpocock/skills: Skills for Real Engineers. Straight from my .claude directory.

 

핵심 개념

이 저장소의 스킬은 크게 두 종류입니다.

User-invoked skill은 사용자가 직접 /grill-me, /to-prd처럼 호출하는 명령형 스킬입니다.
Model-invoked skill은 에이전트가 작업 중 필요할 때 자동으로 참고하거나 호출하는 내부 절차형 스킬입니다. README도 이 둘을 “누가 호출할 수 있는가” 기준으로 나눈다고 설명합니다. (GitHub)

즉, 단순 프롬프트 모음이라기보다 기획 → 질문 → 문서화 → 이슈화 → 구현 → 테스트 → 디버깅 → 구조 개선까지 에이전트가 반복 가능한 개발 루틴을 따르게 만드는 장치입니다.

---

1. Engineering 스킬

코드 작업에 직접 쓰는 스킬들입니다.

/setup-matt-pocock-skills

처음 한 번 실행하는 설정 스킬입니다.
프로젝트에서 어떤 이슈 트래커를 쓸지, triage 라벨을 어떻게 쓸지, CONTEXT.md와 ADR 같은 도메인 문서를 어디에 저장할지 정합니다. README에 따르면 GitHub, Linear, 로컬 파일 기반 이슈 관리를 선택할 수 있습니다. (GitHub)

쉽게 말하면:

“이 프로젝트에서 앞으로 에이전트가 일할 규칙과 문서 위치를 정하는 초기 세팅”

입니다.

---

/ask-matt

현재 상황에 어떤 스킬을 쓰면 좋을지 물어보는 라우터입니다.
예를 들어 “기획을 정리해야 하나?”, “이슈로 쪼개야 하나?”, “버그를 잡아야 하나?” 같은 상황에서 적절한 스킬을 추천받는 용도입니다. README는 이를 user-invoked skills 위의 라우터라고 설명합니다. (GitHub)

---

/grill-with-docs

가장 중요한 스킬 중 하나입니다.
사용자가 만들고 싶은 기능이나 변경사항에 대해 에이전트가 집요하게 질문합니다. 단순 질문에서 끝나는 것이 아니라, 프로젝트의 도메인 모델, 공통 용어, ADR까지 같이 정리합니다. (GitHub)

예를 들어 사용자가 이렇게 말하면:

“회원 결제 기능 만들어줘.”

에이전트가 바로 코딩하지 않고 먼저 묻습니다.

회원은 무료/유료가 있나요?
결제 실패 시 상태는 어떻게 되나요?
환불은 누가 처리하나요?
구독 갱신 실패 후 며칠 동안 접근을 허용하나요?

그 결과를 CONTEXT.md나 ADR에 남겨서 이후 작업에서도 같은 용어와 판단 기준을 쓰게 합니다.

---

/to-prd

현재 대화 내용을 바탕으로 PRD, 즉 제품 요구사항 문서로 정리하는 스킬입니다.
README에 따르면 별도 인터뷰 없이 지금까지 논의한 내용을 종합해서 PRD로 만들고 이슈 트래커에 게시하는 역할입니다. (GitHub)

사용 상황:

“지금까지 말한 내용을 PRD로 정리해줘.”
“이 기능을 개발 문서로 만들어줘.”

결과물은 보통 다음을 포함합니다.

항목내용

목표	왜 만드는가
사용자 시나리오	누가 어떻게 쓰는가
기능 요구사항	무엇을 만들어야 하는가
비기능 요구사항	성능, 보안, 접근성 등
범위 제외	지금 하지 않을 것
구현 영향	어떤 모듈을 건드릴 가능성이 있는가

---

/to-issues

PRD나 기획서를 작업 가능한 이슈 단위로 쪼개는 스킬입니다.
README는 이를 vertical slice, 즉 독립적으로 가져가서 구현 가능한 단위로 나누는 스킬이라고 설명합니다. (GitHub)

예를 들어 “결제 기능 구현”을 이렇게 나눕니다.

큰 기능이슈 예시

결제 API	결제 요청 endpoint 추가
결제 상태	pending/success/failed 상태 모델링
웹훅	PG사 결제 완료 웹훅 처리
UI	결제 버튼과 실패 메시지 화면
테스트	결제 성공/실패/중복 웹훅 테스트

장점은 에이전트에게 “큰 덩어리”를 던지지 않고, 하나씩 검증 가능한 작업으로 나누는 것입니다.

---

/triage

이슈를 상태 머신처럼 이동시키는 스킬입니다.
README에 따르면 triage role 라벨을 기준으로 이슈를 옮깁니다. (GitHub)

예상 흐름은 이런 식입니다.

새 이슈 → 검토 필요 → 기획 필요 → 구현 가능 → 작업 중 → 완료

[Inference] 실제 라벨명은 /setup-matt-pocock-skills에서 사용자가 정한 값에 따라 달라질 수 있습니다.

---

/prototype

버릴 수 있는 프로토타입을 빠르게 만드는 스킬입니다.
README는 상태/비즈니스 로직 질문에는 실행 가능한 터미널 앱을, UI 질문에는 한 라우트에서 여러 UI 변형을 토글할 수 있는 방식으로 만든다고 설명합니다. (GitHub)

예를 들어:

“이 온보딩 플로우가 좋은지 모르겠어.”

라고 하면, 실제 제품 코드에 바로 넣지 않고 여러 버전의 UI를 만들어 비교하게 합니다.

---

/improve-codebase-architecture

코드베이스 구조 개선 스킬입니다.
README에 따르면 CONTEXT.md의 도메인 언어와 docs/adr/의 결정을 참고해, 코드베이스에서 “deepening opportunities”를 찾고 시각적 HTML 리포트로 보여준 뒤, 선택한 항목에 대해 질문 과정을 진행합니다. (GitHub)

쉽게 말하면:

“코드가 점점 진흙덩어리처럼 복잡해지는 것을 막기 위한 구조 점검 스킬”

입니다.

찾을 수 있는 문제 유형은 보통 이런 것들입니다.

문제설명

얕은 모듈	파일은 나뉘었지만 추상화가 약함
경계 불명확	도메인 로직과 UI/인프라 코드가 섞임
중복 규칙	같은 비즈니스 규칙이 여러 곳에 흩어짐
테스트 어려움	작은 인터페이스로 검증하기 어려움
명명 불일치	도메인 용어와 코드 이름이 다름

---

diagnosing-bugs

모델이 필요할 때 쓰는 버그 진단 루프입니다.
README는 이를 “재현 → 최소화 → 가설 → 계측 → 수정 → 회귀 테스트” 흐름으로 설명합니다. (GitHub)

일반적인 AI 코딩의 문제는 바로 “수정부터” 한다는 점입니다.
이 스킬은 먼저 버그를 재현하고, 최소 사례를 만들고, 로그나 테스트로 확인한 다음 수정하게 만듭니다.

---

tdd

테스트 주도 개발 스킬입니다.
README는 red-green-refactor 루프를 사용해 기능이나 버그 수정을 vertical slice 단위로 진행한다고 설명합니다. (GitHub)

흐름은 다음과 같습니다.

단계의미

Red	실패하는 테스트를 먼저 작성
Green	테스트를 통과하도록 최소 구현
Refactor	동작을 유지하면서 구조 개선

AI 에이전트에게 특히 유용한 이유는 “돌아가는지 확인할 피드백 루프”를 강제로 만들기 때문입니다.

---

domain-modeling

프로젝트의 도메인 모델을 정리하고 다듬는 스킬입니다.
README에 따르면 용어를 glossary와 대조하고, edge case 시나리오로 검증하며, CONTEXT.md와 ADR을 업데이트합니다. (GitHub)

예를 들어 교육 플랫폼이라면:

모호한 표현도메인 용어로 정리

강의 올리기	lesson materialization
수업 묶음	course section
공개 처리	publish transition
수강 가능 상태	enrollment eligibility

이런 식으로 프로젝트 내부 언어를 정리합니다.

---

codebase-design

좋은 코드베이스 설계를 위한 내부 규율 스킬입니다.
README는 “작은 인터페이스 뒤에 많은 동작을 숨기는 deep module” 개념을 중심으로, 깨끗한 경계와 테스트 가능한 인터페이스를 강조합니다. (GitHub)

즉, 에이전트가 코드를 만들 때:

파일만 쪼개지 말고, 진짜 의미 있는 모듈 경계를 만들어라.

라는 설계 원칙을 주입하는 스킬입니다.

---

2. Productivity 스킬

코드에만 한정되지 않는 일반 작업용 스킬입니다.

/grill-me

비코드 작업에도 쓸 수 있는 질문 스킬입니다.
README는 사용자의 계획이나 디자인에 대해 모든 결정 분기가 해결될 때까지 집요하게 인터뷰하는 스킬이라고 설명합니다. (GitHub)

예를 들어:

“블록체인 뉴스 자동화 스튜디오 만들고 싶어.”

라고 하면 바로 PRD를 쓰지 않고:

대상 사용자는 누구인가?
뉴스 수집 소스는 어디인가?
자동 업로드까지 할 것인가?
검수 단계가 필요한가?
실패하면 누가 알림을 받는가?

이런 질문을 통해 요구사항을 명확히 합니다.

---

/handoff

현재 대화를 다른 에이전트가 이어받을 수 있도록 handoff 문서로 압축하는 스킬입니다.
README는 현재 대화를 compact하게 정리해서 다른 에이전트가 이어서 작업할 수 있게 한다고 설명합니다. (GitHub)

용도:

“지금까지 논의한 걸 다음 에이전트에게 넘길 문서로 정리해줘.”

포함될 만한 내용:

항목내용

목표	무엇을 하려는지
현재 결정	이미 정한 것
미해결 질문	아직 모르는 것
파일/모듈	관련 코드 위치
다음 작업	이어서 할 일

---

/teach

사용자에게 새 기술이나 개념을 여러 세션에 걸쳐 가르치는 스킬입니다.
README는 현재 디렉터리를 상태 저장형 teaching workspace로 사용한다고 설명합니다. (GitHub)

예를 들어:

“TypeScript 고급 타입을 단계별로 가르쳐줘.”

같은 요청에 맞습니다.

---

/writing-great-skills

좋은 스킬을 작성하고 편집하기 위한 참고 스킬입니다.
README는 스킬을 예측 가능하게 만드는 어휘와 원칙을 다루는 reference라고 설명합니다. (GitHub)

즉, 사용자가 직접 Claude/Codex용 skill을 만들 때 참고하는 “스킬 제작 가이드”입니다.

---

grilling

/grill-me와 /grill-with-docs 뒤에서 재사용되는 내부 질문 루프입니다.
README는 계획이나 디자인의 결정 분기가 모두 해소될 때까지 사용자를 인터뷰하는 재사용 루프라고 설명합니다. (GitHub)

---

3. Misc 스킬

자주 쓰지는 않지만 특정 상황에서 유용한 도구성 스킬입니다.

git-guardrails-claude-code

Claude Code에서 위험한 git 명령을 막는 hook을 설정합니다.
README는 push, reset --hard, clean 같은 위험 명령을 실행 전에 차단한다고 설명합니다. (GitHub)

실제 개발에서 AI 에이전트가 실수로 작업물을 날리는 것을 막는 안전장치입니다.

---

migrate-to-shoehorn

테스트 파일에서 TypeScript의 as 타입 assertion을 @total-typescript/shoehorn으로 마이그레이션하는 스킬입니다. (GitHub)

이건 범용 스킬이라기보다 Matt Pocock의 Total TypeScript 생태계와 관련된 특수 목적 스킬에 가깝습니다.

---

scaffold-exercises

강의나 학습용 exercise 디렉터리 구조를 만드는 스킬입니다.
README는 sections, problems, solutions, explainers 구조를 만든다고 설명합니다. (GitHub)

예를 들어 TypeScript 강의 자료를 만들 때:

exercises/
  01-basic-types/
    problem/
    solution/
    explainer.md

같은 식으로 구성하는 용도입니다.

---

setup-pre-commit

Husky, lint-staged, Prettier, type checking, tests를 포함한 pre-commit hook을 설정하는 스킬입니다. (GitHub)

즉, 커밋 전에 자동으로 코드 포맷, 린트, 타입 체크, 테스트를 돌리게 만드는 개발 품질 장치입니다.

---

전체 흐름으로 보면

이 저장소는 이렇게 쓰는 게 가장 자연스럽습니다.

1. /setup-matt-pocock-skills
   ↓
2. /grill-with-docs
   요구사항 질문 + 도메인 용어 정리
   ↓
3. /to-prd
   PRD 작성
   ↓
4. /to-issues
   구현 가능한 이슈로 분해
   ↓
5. /tdd
   테스트 기반 구현
   ↓
6. diagnosing-bugs
   버그 발생 시 재현 중심으로 진단
   ↓
7. /improve-codebase-architecture
   코드가 복잡해지기 전에 구조 개선

한 줄로 요약하면:

mattpocock/skills는 AI 코딩 에이전트에게 “기획을 확인하고, 문서화하고, 이슈로 쪼개고, 테스트하며, 구조를 관리하는 개발 습관”을 강제로 주입하는 스킬 세트입니다.

특히 그냥 “만들어줘”라고 던지는 방식보다, PRD → 이슈 → TDD → 디버깅 → 아키텍처 개선 흐름을 만들고 싶은 사람에게 유용합니다.