Matt Pocock Skills 분석: 실전 엔지니어링을 위한 Agent Skill 설계법

mattpocock/skills는 Claude Code, Codex 같은 coding agent를 더 예측 가능하게 쓰기 위한 skill 모음이다.

README의 핵심 문장은 “Skills For Real Engineers”다. vibe coding을 위한 프롬프트 모음이라기보다, 실제 엔지니어링에서 자주 실패하는 지점을 skill이라는 작은 절차로 고정하려는 시도에 가깝다.

이 repo의 방향은 분명하다.

거대한 개발 방법론 프레임워크를 agent에게 통째로 맡기는 대신, 작고 조합 가능한 skill을 필요한 순간에 꺼내 쓴다.

한 줄로 이해하기

mattpocock/skills는 agent에게 “무엇을 만들라”가 아니라 “어떤 절차를 밟아야 하는가”를 가르치는 repo다.

각 skill은 특정 상황에서 agent가 따라야 할 과정, 질문 방식, 완료 조건, 금지할 실패 패턴을 담는다.

예를 들어 다음과 같은 상황을 다룬다.

• 구현 전에 사용자의 의도를 집요하게 좁히기
• 버그를 볼 때 먼저 feedback loop 만들기
• TDD를 한 번에 모든 테스트를 쓰는 방식이 아니라 vertical slice로 진행하기
• 큰 계획을 agent가 집을 수 있는 issue 단위로 쪼개기
• 도메인 용어를 CONTEXT.md에 정리해 agent의 말과 코드 언어를 맞추기
• shallow module을 deep module로 바꾸는 아키텍처 개선 기회를 찾기

즉 이 repo의 본질은 prompt collection이 아니라 agent process library다.

Repo 구조

저장소는 크게 bucket 단위로 나뉜다.

engineering은 실제 코드 작업용 skill이다. tdd, diagnosing-bugs, triage, to-issues, to-prd, prototype, domain-modeling, codebase-design 같은 skill이 여기에 있다.

productivity는 비코드 workflow다. grill-me, grilling, handoff, teach, writing-great-skills가 여기에 있다.

misc는 자주 쓰지는 않지만 유용한 보조 skill이다. git guardrail, pre-commit setup, exercise scaffold 같은 도구성 skill이 들어 있다.

personal, in-progress, deprecated도 존재하지만 공개적으로 plugin manifest에 올리는 대상은 아니다.

Claude Code가 읽는 진입점은 .claude-plugin/plugin.json이다. 여기에는 실제로 로드할 skill 경로들이 나열되어 있다. README와 CLAUDE.md는 이 규칙을 명확히 한다. engineering, productivity, misc에 있는 공개 skill은 README와 plugin.json에 올라가야 하고, personal/in-progress/deprecated는 올라가면 안 된다.

어떻게 설치되고 동작하나

README 기준 설치 흐름은 간단하다.

npx skills@latest add mattpocock/skills

이 명령으로 skill을 가져오고, 사용할 agent와 skill을 선택한다. 특히 setup-matt-pocock-skills를 선택하라고 안내한다.

setup skill은 repo별 설정을 맞춘다.

• issue tracker: GitHub, GitLab, local markdown, 기타 tracker
• triage labels: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix
• domain docs: CONTEXT.md와 ADR 위치

이 설정이 중요한 이유는 다른 engineering skill들이 이 정보를 전제로 동작하기 때문이다. 예를 들어 triage나 to-issues는 issue tracker가 어디인지 알아야 하고, tdd나 diagnosing-bugs는 CONTEXT.md의 도메인 용어와 ADR을 읽어야 한다.

즉 이 repo는 skill 파일만 던져주는 구조가 아니다. repo마다 agent가 일관되게 일할 수 있도록 issue tracker, label vocabulary, domain docs를 먼저 맞춘다.

Model-invoked와 User-invoked

이 repo에서 중요한 설계 축은 invocation이다.

skill은 크게 두 종류로 나뉜다.

첫 번째는 model-invoked skill이다. 모델이 상황을 보고 자동으로 사용할 수 있다. frontmatter에서 disable-model-invocation을 생략하고, description에는 모델이 trigger를 판단할 수 있는 설명을 둔다.

예를 들어 diagnosing-bugs는 사용자가 “debug this”, “broken”, “failing”, “slow” 같은 상황을 말하면 모델이 자동으로 떠올릴 수 있다.

두 번째는 user-invoked skill이다. 사람이 slash command처럼 직접 호출해야 한다. frontmatter에 disable-model-invocation: true가 들어간다.

예를 들어 grill-with-docs, to-issues, setup-matt-pocock-skills는 user-invoked다. 모델이 마음대로 실행하기보다 사용자가 명시적으로 시작하는 workflow에 가깝다.

이 구분은 context load와 통제권의 trade-off다.

model-invoked skill은 agent가 알아서 reach할 수 있지만, description이 항상 context에 들어가므로 context load가 생긴다.

user-invoked skill은 context load가 낮지만, 사람이 그 skill의 존재를 기억해야 한다. 이것을 repo에서는 cognitive load라고 본다.

좋은 설계 원칙은 명확하다. 모델이 자율적으로 reach해야 하는 skill만 model-invoked로 두고, 사람이 직접 호출하는 workflow는 user-invoked로 둔다.

Skills가 해결하려는 문제

README는 agent coding에서 자주 생기는 실패를 몇 가지로 잡는다.

첫째, agent가 사용자의 의도를 제대로 이해하지 못한다. 그래서 grill-me와 grill-with-docs가 있다. 이 skill들은 구현 전에 질문을 한 번에 쏟아내지 않고, 설계 tree를 따라 하나씩 물으면서 의도를 좁힌다.

둘째, agent가 장황하고 프로젝트 용어를 잘못 쓴다. 그래서 CONTEXT.md와 domain-modeling이 있다. 프로젝트의 ubiquitous language를 문서화해 agent가 같은 단어를 같은 의미로 쓰게 한다.

셋째, agent가 버그를 감으로 고치려 한다. diagnosing-bugs는 이것을 막는다. 가장 먼저 red-capable feedback loop를 만들라고 한다. 재현 가능한 loop 없이 가설부터 세우지 말라는 점이 핵심이다.

넷째, agent가 테스트를 implementation detail에 맞춘다. tdd skill은 public interface를 통해 behavior를 검증하라고 강조한다. 또한 모든 테스트를 먼저 쓰고 모든 구현을 나중에 하는 horizontal slicing을 반패턴으로 본다. 대신 test 하나, implementation 하나의 vertical slice를 반복한다.

다섯째, 큰 계획을 agent가 잡기 어려운 덩어리로 둔다. to-issues는 plan이나 PRD를 end-to-end로 검증 가능한 tracer bullet issue로 쪼갠다.

실제 workflow는 어떻게 안정화되나

이 repo의 skill들은 공통적으로 agent의 자유도를 줄인다. 하지만 답을 고정하지는 않는다. 대신 과정을 고정한다.

예를 들어 diagnosing-bugs는 버그 원인을 바로 추측하지 못하게 한다.

먼저 feedback loop를 만든다. 그 loop는 red-capable해야 한다. 즉 사용자가 말한 정확한 증상을 잡을 수 있어야 한다. 그냥 “에러 없이 실행됨”은 충분하지 않다.

그 다음 reproduce와 minimise를 한다. 최소 재현을 만들고, 3-5개의 falsifiable hypothesis를 세운다. 각 hypothesis는 바꾸면 어떤 현상이 나와야 하는지 예측 가능해야 한다. 이후 instrumentation, fix, regression test, cleanup으로 간다.

이 흐름은 agent가 흔히 저지르는 “그럴듯한 원인 하나를 찍고 바로 수정”하는 행동을 막는다.

tdd skill도 마찬가지다. 모든 테스트를 한꺼번에 작성하지 말라고 한다. 하나의 behavior test를 쓰고, 최소 구현으로 green을 만든 뒤 다음 behavior로 간다. 이것은 agent가 상상 속 API에 맞춰 테스트를 대량으로 작성하는 문제를 줄인다.

grilling skill은 질문 방식까지 제한한다. 여러 질문을 한 번에 묻지 말고 하나씩 물으라고 한다. 사용자가 답하기 쉬운 상태로 decision tree를 좁히기 위해서다.

좋은 Skill 작성법

writing-great-skills는 이 repo의 철학을 가장 직접적으로 보여준다.

핵심 문장은 “A skill exists to wrangle determinism out of a stochastic system”이다. 즉 skill은 stochastic한 모델을 deterministic하게 만드는 것이 아니라, 매번 같은 과정을 밟게 만드는 장치다.

좋은 skill의 기준은 다음과 같다.

첫째, completion criterion이 명확해야 한다. agent가 언제 끝났는지 스스로 확인할 수 있어야 한다. “충분히 분석하라”는 약하다. “red-capable command를 이미 한 번 실행했고, 그 출력이 특정 증상을 잡는다”는 강하다.

둘째, description은 신중하게 써야 한다. model-invoked skill의 description은 항상 context에 올라오기 때문이다. trigger branch가 중복되면 context load만 늘어난다.

셋째, reference는 progressive disclosure로 내릴 수 있어야 한다. 모든 정보를 SKILL.md에 넣으면 sprawl이 생긴다. 일부 branch에서만 필요한 정보는 별도 파일로 빼고, 필요한 순간에만 읽게 한다.

넷째, no-op 문장을 제거해야 한다. “be careful”, “be thorough”처럼 모델이 이미 대충 알고 있는 말은 비용만 쓴다. 대신 tight loop, tracer bullet, deep module 같은 강한 leading word를 사용한다.

다섯째, user-invoked와 model-invoked를 구분해야 한다. 모델이 스스로 reach해야 하는 skill만 description을 남기고, 나머지는 사람이 직접 호출하는 command로 둔다.

실전 팁

이 repo를 그대로 쓰든, 자신의 skill을 만들든 몇 가지 팁이 있다.

첫째, skill을 크게 만들지 말아야 한다. 하나의 거대한 “개발 잘하기” skill보다 “diagnosing-bugs”, “tdd”, “to-issues”처럼 상황별로 작게 나누는 편이 낫다.

둘째, skill은 output template보다 process에 집중해야 한다. 좋은 agent는 예쁜 문서를 만드는 것보다 올바른 순서로 확인하고 결정하는 데서 성능 차이가 난다.

셋째, completion criterion을 강하게 써야 한다. 특히 bug, test, deploy, issue 생성처럼 검증 가능한 작업은 완료 조건을 checkable artifact로 묶어야 한다.

넷째, domain language를 별도로 관리해야 한다. CONTEXT.md는 단순 메모가 아니라 agent가 프로젝트 용어를 해석하는 기준이다. 도메인 용어가 흔들리면 agent 답변도 장황해진다.

다섯째, issue는 vertical slice로 쪼개야 한다. “DB 작업”, “API 작업”, “UI 작업”처럼 계층별로 나누면 agent가 독립적으로 완료하기 어렵다. “사용자가 X를 할 수 있다” 같은 end-to-end slice가 더 좋다.

여섯째, model-invoked skill은 적게 유지해야 한다. 자동 호출 가능한 skill이 많아질수록 description context load가 늘어난다. 정말 모델이 스스로 알아야 하는 것만 남기는 편이 낫다.

한계와 주의점

이 repo는 강력하지만 모든 팀에 그대로 맞지는 않는다.

첫째, GitHub/Linear/local markdown 같은 issue tracker 중심 workflow를 전제로 한다. 이미 Jira나 Notion 중심으로 강하게 굳어진 팀은 setup skill을 자기 환경에 맞게 조정해야 한다.

둘째, 사용자가 skill을 기억하고 호출해야 하는 부분이 있다. user-invoked skill은 context load를 줄이지만, 사람이 사용할 타이밍을 알아야 한다.

셋째, skill이 많아질수록 운영 규칙이 필요하다. README, plugin.json, bucket README, SKILL.md 간 정합성을 유지해야 한다. 이 repo는 CLAUDE.md에 그 규칙을 명시해둔다.

넷째, skill은 좋은 engineering judgment를 대체하지 않는다. skill은 agent가 과정을 놓치지 않게 돕지만, 무엇이 중요한 behavior인지, 어떤 issue가 좋은 vertical slice인지는 여전히 판단이 필요하다.

다섯째, 너무 강한 skill은 agent를 느리게 만들 수 있다. 모든 작업에 grilling, domain modeling, ADR을 다 적용하면 과하다. 요청의 위험도와 규모에 맞춰 skill을 골라야 한다.

우리 작업에 적용한다면

이 repo에서 바로 가져올 만한 아이디어는 세 가지다.

첫째, 글 작성이나 분석 작업에도 “completion criterion”을 둔다. 예를 들어 “도식 3개 이상”, “빌드 통과”, “URL 200 확인”처럼 끝을 명확히 한다.

둘째, LLM Wiki 작업에는 CONTEXT.md 같은 domain glossary가 중요하다. QMD, GGUF, HyDE, rerank 같은 용어가 계속 나오므로, 용어를 한 곳에 모으면 이후 글의 일관성이 좋아진다.

셋째, 큰 주제는 vertical slice로 쪼갠다. “LLM Wiki 전체 설명”보다 “GGUF”, “Query Expansion”, “Rerank”, “HyDE”처럼 한 글이 하나의 개념을 끝까지 설명하는 방식이 더 읽기 쉽다.

정리

mattpocock/skills는 agent에게 더 많은 자유를 주는 repo가 아니다. 반대로 agent가 흔히 실패하는 지점을 작은 절차로 묶어 자유도를 줄인다.

좋은 점은 통제권을 사용자가 유지한다는 것이다. GSD, BMAD, Spec-Kit처럼 전체 process를 agent에게 통째로 맡기기보다, 필요한 skill만 골라 쓴다.

핵심 철학은 명확하다.

Agent의 출력은 매번 달라도 된다. 하지만 agent가 밟는 과정은 예측 가능해야 한다.

이 repo의 skill들은 그 과정을 안정화하기 위한 작은 engineering playbook이다.