🔥 세 단락짜리 스킬이 바이럴 된 이유 — Matt Pocock의 mattpocock/skills 톺아보기

mattpocock/skills 레포를 처음 열었을 때 README의 한 문장에서 잠시 멈췄다. "GSD, BMAD, Spec-Kit ... they take away your control." 평소에 framework를 깔아 놓고도 어딘가 답답했던 이유를 그 한 줄이 정리해 줬다. 무엇이 어디서 결정되는지 모른 채 그냥 따라가고 있었다는 것이다. 그 자리에서 레포를 처음부터 끝까지 읽었다. 마지막까지 머리에 남은 건 본문이 세 단락뿐인 grill-me라는 스킬이었다.

이 글은 그 레포를 한 번에 정리한다. Matt Pocock이 어떤 4가지 실패 모드를 풀려고 했고, 그 답이 왜 작은 스킬의 형태로 나왔는지, 그리고 그 짧은 스킬이 어떻게 바이럴 됐는지를 차례로 본다.

왜 새로 만들었나 — 4가지 실패 모드

Matt Pocock은 TypeScript 콘텐츠로 알려진 강사다. 그가 자기 .claude/ 디렉터리에서 매일 쓰는 것을 추려 공개한 것이 mattpocock/skills 레포다. 슬로건은 "Skills For Real Engineers".

README는 4가지 실패 모드로 시작한다. Matt이 말하는 실패는 모델 자체의 능력 한계가 아니라, 에이전트와 일하는 방식의 실패다.

첫째, 에이전트가 내가 원한 것과 다른 걸 만든다. 인용은 Pragmatic Programmer다.

No-one knows exactly what they want.
(어느 누구도 자기가 정확히 무엇을 원하는지 모른다.)

Matt은 이 misalignment를 grilling session으로 푼다. 에이전트가 사용자에게 detail 질문을 던져 결정 트리를 한 가지씩 내려간다.

둘째, 에이전트가 너무 verbose하다. 인용은 Eric Evans의 Domain-Driven Design이다. shared vocabulary가 없으면 한 단어로 될 일을 스무 단어로 한다는 진단이다. Matt이 자기 course-video-manager 레포에서 든 예시는 이렇다.

• BEFORE: "There's a problem when a lesson inside a section of a course is made 'real' (i.e. given a spot in the file system)"
• AFTER: "There's a problem with the materialization cascade"

해법은 CONTEXT.md라는 도메인 용어집을 프로젝트에 두고, 모든 세션이 그것을 입력으로 다시 사용하는 것이다.

셋째, 코드가 작동하지 않는다. Pragmatic Programmer를 또 인용한다.

Always take small, deliberate steps. The rate of feedback is your speed limit.
(항상 작고 신중한 단계로 움직여라. feedback 속도가 곧 작업 속도의 상한선이다.)

해법은 feedback loop다. static type, browser access, 자동화 테스트, 그리고 red-green-refactor.

넷째, 코드가 진흙 덩어리가 된다. Kent Beck("매일 시스템 설계에 투자하라")과 John Ousterhout("좋은 모듈은 deep하다 — 단순한 인터페이스 뒤에 풍부한 기능")을 인용한다. 에이전트가 코딩 속도를 올리니까 entropy도 같이 올라간다는 것이 Matt의 진단이다. 해법은 매일 설계를 챙기는 도구를 두는 것이다.

이 네 가지가 Matt이 만든 레포의 출발점이다. 인용한 책 네 권이 모두 1990~2010년대의 고전이라는 점이 흥미롭다. AI 시대에도 같은 문제가 같은 형태로 돌아왔다는 입장이다.

framework가 아니라 작은 도구의 모음

Matt은 이 4가지 실패 모드를 푸는 도구로 통합 framework를 만들지 않았다. 그는 자기 입장을 README에 분명히 적는다.

Approaches like GSD, BMAD, and Spec-Kit try to help by owning the process. But while doing so, they take away your control... These skills are designed to be small, easy to adapt, and composable.
(GSD, BMAD, Spec-Kit 같은 접근은 프로세스를 owning하면서 사용자의 control을 빼앗는다. 이 스킬들은 작고, 적응 가능하고, 조합 가능하도록 설계됐다.)

이 구분이 mattpocock/skills 레포의 가장 중요한 입장이다. 프로세스를 통째로 가져가는 도구가 아니라, 사용자가 원할 때 끼워 쓰고 안 맞으면 빼는 단위 도구의 모음이다.

레포 폴더는 카테고리 5개로 나뉜다.

skills/
├── engineering/    # 코드 작업 (tdd, diagnose, to-prd, to-issues, ...)
├── productivity/   # 작업 방식 (caveman, grill-me, write-a-skill)
├── misc/           # 가끔 쓰는 도구
├── personal/       # Matt 개인용
└── deprecated/     # 폐기된 것

skills/
├── engineering/    # 코드 작업 (tdd, diagnose, to-prd, to-issues, ...)
├── productivity/   # 작업 방식 (caveman, grill-me, write-a-skill)
├── misc/           # 가끔 쓰는 도구
├── personal/       # Matt 개인용
└── deprecated/     # 폐기된 것

각 스킬 폴더는 다음 표준 구조를 따른다.

skill-name/
├── SKILL.md       # 진입점 (필수)
├── REFERENCE.md   # 상세 (옵션)
├── EXAMPLES.md    # 예시 (옵션)
└── scripts/       # 결정적 작업용 실행 파일 (옵션)

skill-name/
├── SKILL.md       # 진입점 (필수)
├── REFERENCE.md   # 상세 (옵션)
├── EXAMPLES.md    # 예시 (옵션)
└── scripts/       # 결정적 작업용 실행 파일 (옵션)

이 단순한 폴더 규약이 두 가지 효과를 만든다. 먼저, 스킬 하나를 통째로 카피해 자기 레포로 가져가기 쉽다. 그다음, 어떤 스킬도 다른 스킬에 코드로 의존하지 않는다. 결합점은 코드가 아니라 프로젝트의 문서(CONTEXT.md, docs/adr/)다.

SKILL.md는 어떻게 쓰는가

SKILL.md의 frontmatter는 두 필드뿐이다.

---
name: tdd
description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
---

---
name: tdd
description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
---

description 필드가 가장 중요하다. 에이전트가 어떤 스킬을 로드할지 결정할 때 보는 유일한 텍스트라서다. Matt이 write-a-skill에 정해 둔 규칙은 다음과 같다.

• 1,024자 이내
• 3인칭으로 쓴다
• 첫 문장: 무엇을 하는지
• 둘째 문장: Use when [구체적 트리거 키워드 / 문맥 / 파일 타입]

좋은 description과 나쁜 description을 직접 대조한다.

GOOD
  Extract text and tables from PDF files, fill forms, merge documents.
  Use when working with PDF files or when user mentions PDFs, forms,
  or document extraction.

BAD
  Helps with documents.

GOOD
  Extract text and tables from PDF files, fill forms, merge documents.
  Use when working with PDF files or when user mentions PDFs, forms,
  or document extraction.

BAD
  Helps with documents.

나쁜 쪽은 같은 문서 처리 스킬이 다섯 개 있을 때 어느 것을 골라야 할지 단서를 주지 않는다. 좋은 쪽은 트리거 키워드와 사용 맥락을 함께 적는다.

write-a-skill의 또 다른 규칙은 SKILL.md 본문이 100줄을 넘지 않게 하는 것이다. 그 이상은 보조 파일로 분리한다.

progressive disclosure — 100줄 제한이 만드는 것

100줄 제한은 미관 문제가 아니다. 토큰 예산과 라우팅 정확도의 문제다.

engineering/tdd/ 폴더가 그 사례다. SKILL.md 본문은 짧고, 같은 폴더에 사이드카 5개가 함께 있다.

tdd/
├── SKILL.md
├── tests.md
├── mocking.md
├── refactoring.md
├── deep-modules.md
└── interface-design.md

tdd/
├── SKILL.md
├── tests.md
├── mocking.md
├── refactoring.md
├── deep-modules.md
└── interface-design.md

SKILL.md 안에서는 마크다운 링크로 가리킨다. 예를 들어 See [refactor candidates](refactoring.md) 같은 식이다. 에이전트는 그 링크를 따라야 할 때만 보조 파일을 읽는다. refactor 단계가 아니면 refactoring.md는 컨텍스트에 들어오지 않는다.

결정적 작업은 본문이 아니라 scripts/ 안의 실행 파일로 분리한다. engineering/diagnose/scripts/hitl-loop.template.sh가 그 예다. 사람이 직접 클릭해야 하는 마지막 수단의 디버깅 루프를 bash 템플릿으로 박아 둔 것이다. 같은 코드를 매번 LLM이 다시 생성하지 않게 한다.

이 progressive disclosure 패턴이 4가지 실패 모드 전반에 적용돼 있다. Matt이 write-a-skill에 적은 한 줄이 그 의도를 정리한다.

Scripts save tokens and improve reliability vs generated code.
(스크립트는 LLM이 매번 생성하는 코드보다 토큰을 아끼고 신뢰성을 올린다.)

세 단락짜리 grill-me — 글의 정점

productivity/grill-me/SKILL.md의 본문은 정확히 다음과 같다.

Interview me relentlessly about every aspect of this plan until we
reach a shared understanding. Walk down each branch of the design
tree, resolving dependencies between decisions one-by-one. For each
question, provide your recommended answer.

Ask the questions one at a time.

If a question can be answered by exploring the codebase, explore
the codebase instead.

Interview me relentlessly about every aspect of this plan until we
reach a shared understanding. Walk down each branch of the design
tree, resolving dependencies between decisions one-by-one. For each
question, provide your recommended answer.

Ask the questions one at a time.

If a question can be answered by exploring the codebase, explore
the codebase instead.

세 단락뿐이다. README의 4가지 실패 모드 중 첫 번째 — misalignment — 의 해법이 이 세 단락이다.

Matt이 aihero 글에 적은 표현은 다음과 같다.

The most flexible skill I've ever created.
(내가 만든 스킬 중 가장 유연한 것이다.)

작동 규칙은 네 가지다.

1. 한 번에 한 질문. 사용자의 답을 받기 전에는 다음 질문을 하지 않는다.
2. 모든 질문에 자기 추천 답을 함께 낸다. 사용자는 동의하거나 반박하기만 하면 된다. Matt이 최근에 추가했다고 밝힌 한 줄이 바로 이 부분이다. 백지 질문보다 답이 빠르다.
3. 결정 트리를 한 가지(branch)씩 내려간다. 한 결정이 다른 결정에 의존하면, 의존하는 쪽을 먼저 푼다.
4. 코드로 답할 수 있는 질문은 사용자에게 묻지 않는다. 에이전트가 직접 코드베이스를 읽는다.

Matt은 5 Agent Skills I Use Every Day에서 같은 입장을 더 직접적으로 적는다.

Skills don't have to be long to be impactful. You just need to choose the right words at the right time.
(스킬이 길어야 효과가 있는 것은 아니다. 적절한 시점에 적절한 단어를 고르면 된다.)

grill-me는 코딩 외 용도로도 작동한다. Matt은 Skills Changelog 글에서 누군가 어머니 추도사(eulogy)를 작성하는 데 이 스킬을 쓴 사례를 인용한다 — "worked wonderfully". 짧은 텍스트에 다섯 영역의 결정을 담아 놓았기에 가능한 일이다.

비슷한 인터뷰 패턴을 코드용으로 확장한 것이 grill-with-docs다. 인터뷰 도중 결정된 용어는 CONTEXT.md에 즉시 적히고, 큰 결정 중 되돌리기 어렵고 + 맥락 없으면 놀랍고 + 진짜 타협의 결과인 것만 docs/adr/에 ADR로 적힌다. 같은 결정을 다음 세션에서 또 묻지 않는다.

스킬들은 어떻게 결합하는가

권장 워크플로는 다음과 같다 (aihero 글).

grill-me → domain-model → to-prd → to-issues → tdd

grill-me → domain-model → to-prd → to-issues → tdd

grill-me는 앞 절에서 본 인터뷰 단계다. 그다음 절에서는 grill-me 이후의 흐름인 domain-model → to-prd → to-issues → tdd를 본다.

• domain-model이 도메인 용어와 ADR을 점검하면서 계획을 압박한다.
• to-prd가 그 합의된 맥락을 PRD로 정리한다. 모듈 분리(deep modules) 후보를 함께 적는다.
• to-issues가 PRD를 vertical slice 단위 GitHub 이슈로 쪼갠다. 각 이슈가 통합 레이어를 가로지르도록 만들어 handoff 문제를 줄이는 것이 목표다.
• tdd가 이슈를 받아 red-green-refactor로 구현한다.

이 흐름의 결합점은 함수 호출이 아니라 _파일_이다. 한 스킬이 CONTEXT.md를 갱신하면 다음 스킬이 그 파일을 다시 읽는다. 한 스킬이 ADR을 추가하면 그다음 세션이 그 결정을 입력으로 받는다. 결합이 코드가 아닌 문서로 되어 있어 어떤 스킬을 빼고 다른 스킬을 끼워도 흐름이 깨지지 않는다.

레포에는 작업 모드만 바꾸는 짧은 스킬도 있다. caveman이 그 예다. 본문 자체가 caveman 톤이다. 토큰을 약 75% 줄이는 것이 목적이다.

"Sure! I'd be happy to help you with that. The issue you're
experiencing is likely caused by..."
                  ↓
"Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"

"Sure! I'd be happy to help you with that. The issue you're
experiencing is likely caused by..."
                  ↓
"Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"

긴 사담을 자르는 단순한 모드 스위치도 별도 스킬로 둘 만하다는 입장이다.

한 줄 요약 — control은 어디에 두는가

Code Complete는 software construction — 상세 설계·코딩·디버깅·단위/통합 테스트 — 이 프로젝트 시간의 30~80%를 차지한다고 적는다. AI가 이 비율을 단축한다 해도, 어떤 결정을 내릴지 정하는 일은 줄어들지 않는다. mattpocock/skills 레포가 가르치는 것은 어떻게 코딩하느냐가 아니라 어떤 결정을 내가 직접 내릴 것인가의 목록이다.

이 글의 도입부에서 멈춰 섰던 README의 한 문장으로 돌아간다. framework가 control을 가져가면 사용자는 따라간다. 작은 스킬을 조합하면 control은 사용자에게 남는다. 짧은 grill-me가 바이럴 된 건 아마도 그 단순한 사실을 다시 떠올리게 했기 때문일 것이다.

설치는 한 줄이다. Claude Code, Codex 등 여러 coding agent에서 쓰도록 설계됐다.

npx skills@latest add mattpocock/skills

npx skills@latest add mattpocock/skills

설치 후 /setup-matt-pocock-skills를 한 번 돌리면 issue tracker, triage label vocabulary, 도메인 문서 위치를 잡아 준다. 그다음부터는 자기 프로젝트에 어떤 스킬을 두고, 어떤 스킬을 빼고, 어떤 스킬을 변형할지 자기가 정한다. 그게 이 레포의 사용법이다.

참고 자료

• mattpocock/skills 레포
• 5 Agent Skills I Use Every Day — aihero
• My 'Grill Me' Skill Went Viral — aihero
• Skills Changelog: Ubiquitous Language → grill-with-docs — aihero
• skills-domain-model — aihero
• skill-test-driven-development-claude-code — aihero