한 번 뜯어보는 mattpocock/skills

오늘 GitHub 좀 돌아다니다가, mattpocock/skills 라는 레포를 봤다.

근데 스타가 무슨 115k. 포크 10.1k.

도대체 무슨 레포길래 이런 미친 숫자를 찍었지?

싶어서 들어가봤다.

레포 이름은 Skills For Real Engineers. 본인이 매일 쓰는 Claude Code 스킬들을 정리해서 오픈소스로 풀어놓은 거다. skills.sh 기준 누적 설치가 2.6M 회 라고 한다.

이 정도면 안 뜯어볼 수가 없다.

그래서 일단 설치해놓고, 하나씩 봐봤다. 오늘은 그 정리를 좀 하려고 한다.

Matt 이 잡고자 하는 4가지 실패 모드

Matt 은 GSD, BMAD, Spec-Kit 같은 기존 접근법들을 한 줄로 비판한다. (셋 다 “AI 한테 개발 어떻게 시킬지” 를 정해주는 큰 프레임워크들이다.)

“프로세스를 떠안아주면서 동시에 본인의 통제권을 빼앗는다.”

내가 지난 글들에서 다뤘던 vibe slop 같은 개념을 이야기하는 거 같다.

그래서 그가 만든 건 작고, 적응 가능하고, 조합 가능한 스킬들. 큰 프레임워크 대신, 필요할 때 필요한 거 하나씩 가져다 쓰는 방식.

이 스킬들이 잡으려는 네 가지 흔한 실패 모드부터 정리해보자.

1. 에이전트가 내가 원하는 걸 안 한다: Misalignment

“아무도 자기가 정확히 뭘 원하는지 모른다.” — David Thomas & Andrew Hunt, The Pragmatic Programmer

가장 흔한 실패 모드다.

나는 에이전트가 알아들었다고 생각했는데, 결과물을 보면 전혀 다른 걸 만들어왔다. 한 번씩은 다 겪어봤을 거다.

Matt 의 해결책: grilling session. 쉽게 말해 — 에이전트가 나한테 거꾸로 인터뷰하는 거다. 시키는 일을 바로 시작하지 말고, “이거 정말 이런 뜻이야?” 를 계속 캐묻게 만든다.

2. 에이전트가 너무 수다스럽다: Verbosity

“공유 언어가 있으면, 개발자 간 대화와 코드 표현이 같은 도메인 모델에서 파생된다.” — Eric Evans, Domain-Driven Design

도메인 전문가와 개발자는 처음엔 다른 언어를 쓴다. 비즈니스 쪽은 “고객 결제 흐름” 이라고 부르는 걸, 개발자는 “checkout pipeline” 이라고 부르는 식.

AI 에이전트도 마찬가지인데, 프로젝트의 톤을 모르니까 1 단어로 끝낼 걸 20 단어로 풀어서 쓴다.

해결책: 공유 언어 문서. CONTEXT.md 라는 파일에 프로젝트의 jargon (= 팀의 용어 사전) 을 정리해두면, 에이전트가 점점 더 정확하고 간결해진다.

3. 코드가 안 굴러간다: Non-functional Code

“항상 작고 의도적인 발걸음을 떼라. 피드백 속도가 너의 속도 제한이다.” — The Pragmatic Programmer

피드백 루프 부족이 원인.

타입, 브라우저 접근, 자동 테스트. 즉 코드 짠 직후에 “이게 작동하나?” 를 빨리 확인할 수 있는 장치들. 특히 자동 테스트는 red-green-refactor 가 핵심이라고 한다. (이건 뒤에 /tdd 에서 자세히.)

4. 진흙 공: Ball of Mud

“최고의 모듈은 깊다. 단순한 인터페이스 뒤에 많은 기능이 있다.” — John Ousterhout, A Philosophy of Software Design

AI 가 코딩 속도를 올린 만큼, 소프트웨어 엔트로피도 같이 가속된다는 거. 즉 — 코드가 점점 알아볼 수 없는 진흙 공이 되어간다. (이게 진짜 vibe slop 의 핵심이지.)

Matt 의 해결책: 코드 디자인을 신경 쓰는 것 자체 가 새로운 AI 시대의 차별점이라는 거다.

설치

설치 자체는 진짜 단순하다. 한 줄.

npx skills@latest add mattpocock/skills

실행하면 인터랙티브 프롬프트가 뜬다. 어떤 스킬 / 어떤 에이전트 / 셋업 옵션을 차례로 물어본다.

지원 에이전트는 Claude Code, Cursor, GitHub Copilot, Codex CLI 등.

설치되면 글로벌로 깔린다. 내 환경 기준으로 보면:

~/.agents/skills/  →  ~/.claude/skills/ symlink

~/.agents/skills/ 가 원본 디렉터리고, 각 에이전트별 디렉터리 (~/.claude/skills/ 등) 가 거기로 심볼릭 링크로 연결돼있다. 즉 한 번 설치하면 모든 에이전트에서 같은 스킬 풀을 본다. Cursor 에서 쓰든 Claude Code 에서 쓰든 같은 스킬 깔린 거.

설치 후 /setup-matt-pocock-skills 한 번 돌리면 프로젝트별 셋업 (이슈 트래커, 라벨, 문서 위치) 까지 끝난다.

내가 설치한 스킬들

전체 18개 중 내가 골라서 설치한 건 7개 + Vercel Labs 의 /find-skills.

카테고리별로 정리해보면 이렇다.

각 스킬마다 슬래시 명령 외에 자연어 트리거 도 따로 있는데, 일상적인 표현으로 말하면 에이전트가 알아서 발동시키는 식이다. (이건 뒤에 따로 정리)

디버깅·아키텍처

/diagnose

어려운 버그·성능 회귀를 위한 체계적 진단 루프.

재현 → 최소화 → 가설 → 계측 → 수정 → 회귀 테스트

각 단계를 풀면:

• 재현: 일단 버그를 의도적으로 다시 일으킬 수 있는 방법 찾기
• 최소화: 그 재현 과정을 최소 코드로 줄여서 원인 범위 좁히기
• 가설: “이게 원인일 것 같다” 후보 세우기
• 계측: 로그/print 박아서 가설이 맞는지 검증
• 수정: 진짜 원인 잡으면 고치기
• 회귀 테스트: 같은 버그 다시 안 나오게 테스트 추가

핵심은 “빠르고 결정론적인 pass/fail 피드백 루프를 먼저 만든다” 는 거. “고쳐봤는데 되네?” 가 아니라 “이렇게 하면 100% 깨지고, 이렇게 고치면 100% 통과” 를 만들어놓고 들어간다는 뜻.

단발성 stack trace 보고 끝나는 거랑은 차원이 다르다. 30분 이상 잡고 가는 본격 디버깅용.

• 자연어 트리거: “이 버그 좀 진단해줘”, “이거 왜 자꾸 깨져?”, “성능이 갑자기 떨어졌어”
• 슬래시: /diagnose

/improve-codebase-architecture

“shallow module” 을 찾아서 “deep module” 로 합치는 리팩터링 후보를 찾아준다.

쉽게 말하면 — shallow module 은 인터페이스만 두껍고 속은 별 거 없는 모듈이다. 한 줄짜리 헬퍼 함수가 결국 한 줄짜리 동작을 부르는 식. 그냥 직접 짜는 거랑 비용 차이가 없다. 포장만 큼직한 박스.

반대로 deep module 은 호출은 단순한데 안에서는 복잡한 일을 다 처리하는 모듈이다. 대표적인 예가 Unix 의 open / read / write / close. 함수 네 개로 디스크, SSD, 네트워크 파일 시스템까지 다 다룬다. 인터페이스 뒤에 진짜 깊이가 있는 거.

/improve-codebase-architecture 는 코드베이스를 훑어서 “여기 shallow 한 거 몇 개가 합치면 deep 해질 수 있겠다” 같은 후보를 뽑아준다.

흥미로운 건, HTML 리포트로 before/after 다이어그램 을 그려서 임시 디렉토리에 띄운다.

본격 리팩터 결정 전에 한 번 돌려보기 좋은 모양.

• 자연어 트리거: “이 코드 구조 개선해줘”, “리팩터할 거 찾아봐”
• 슬래시: /improve-codebase-architecture

계획·의사결정 압박

/grill-me

계획·디자인을 결정 트리 형태로 한 질문씩 압박 해서 합의에 도달. 각 질문마다 추천 답변까지 같이 제시한다. 의사결정 누락을 잡아내는 용도.

결정 트리라는 게 — “이 기능 만든다” 면 → “그럼 사용자 인증은 어떻게 할 거야?” → “OAuth 면 어떤 프로바이더 쓸 거야?” → “프로바이더가 fail 하면 어떻게 처리해?” 식으로 결정이 결정을 부르고, 그 모든 가지를 다 따라가면서 캐묻는다는 뜻.

오늘 사이드로 만들고 있는 앱 설계할 때 첫 질문 들어갔던 게 이거였는데, “흔한 인터뷰 봇” 정도가 아니라 진짜 미친 듯이 캐묻는다.

실제로 써본 인상 — 진짜 마음에 든다.

기능 하나 구현하자고 던졌는데, 질문이 20개 가 나왔다. 처음엔 “이게 뭐 이렇게 많아” 싶었는데, 하나하나 보니까 다 내가 놓치고 있던 디테일 이었다.

대충 이런 종류의 질문들이 나온다:

• 이 기능 쓰는 유저는 인증된 상태여야 하는가, 익명도 허용하는가?
• 데이터 저장 실패하면 retry 할 건가, 그냥 에러 띄울 건가? retry 면 몇 번, 어떤 간격으로?
• 같은 데이터를 두 디바이스에서 동시에 수정하면 어떻게 처리?
• 오프라인 상태에서는 동작하게 할 건가, 막을 건가?
• 이전에 X 기능에서 정의한 패턴이 있는데, 그거랑 일관성 있게 갈 건가 아니면 새로 정의할 건가?
• UI 의 로딩 / 빈 상태 / 에러 상태 각각 어떻게 표시?
• 이 동작 결과를 분석 이벤트로 남길 건가? 남기면 어떤 속성으로?
• …

20개 다 답하다 보면 — 사실상 기능 명세서가 한 번에 완성되는 효과다. 평소에 “감으로” 결정하던 부분들이 다 명시적으로 결정되고 가니까, 그 다음에 코드 짜는 단계가 진짜 깔끔해진다.

이걸 안 하고 바로 코드 시키면 — 결국 중간에 에이전트가 자기 멋대로 결정하고 가거나, 내가 다시 멈춰서 보완하느라 시간이 더 든다.

계획 단계 30분 투자로 구현 단계 2시간 줄이는 그런 감각.

• 자연어 트리거: “이 계획 좀 grill해줘”, “이 디자인 stress-test 해줘”
• 슬래시: /grill-me

/grill-with-docs

/grill-me 의 강화판.

차이점: 프로젝트의 CONTEXT.md (= 팀 용어 사전) 과 docs/adr/ (= “왜 이렇게 결정했는지” 를 기록한 폴더) 을 참조하면서 grilling.

ADR = Architecture Decision Record. “왜 PostgreSQL 대신 SQLite 골랐는지”, “왜 Redux 안 쓰기로 했는지” 같은 의사결정의 이유 를 한 페이지짜리 문서로 박아두는 거. 6개월 뒤에 본인이 봐도 이해되도록.

이 두 가지를 참조하니까:

• 용어 충돌·모호함을 잡아낼 수 있고 (“네가 말한 ‘주문’ 이 CONTEXT.md 에 있는 ‘주문’ 이랑 같은 거야 다른 거야?”)
• 결정이 정해지면 CONTEXT.md / ADR 을 그 자리에서 업데이트 해준다

도메인이 복잡한 프로젝트에 적합하다고 한다.

CONTEXT.md 가 자동 관리된다는 게 진짜 좋다. Matt 본인이 “이게 이 레포에서 가장 cool 한 기법일 수도 있다” 고 한 거.

Matt 이 든 예시:

• BEFORE: “코스의 섹션 안의 레슨이 ‘real’ 해질 때 (즉 파일 시스템에 자리 잡을 때) 의 문제가 있다”
• AFTER: “materialization cascade 문제가 있다”

같은 말인데 후자는 그 프로젝트의 공유 언어로 압축된 거. 한 번 셋업해두면 모든 세션에서 이 언어가 살아남는다.

• 자연어 트리거: “도메인 모델과 함께 grill해줘”
• 슬래시: /grill-with-docs

TDD

/tdd

Red-green-refactor 사이클. (실패하는 테스트 → 통과시키는 최소 구현 → 정리/리팩터링 → 반복.)

핵심 안티패턴 경고: “테스트 다 쓰고 코드 다 쓰는 수평 슬라이싱” 금지.

수평 슬라이싱이 뭐냐면 — “기능에 들어갈 테스트 10개를 미리 다 짜놓고, 그 다음에 구현 10개를 한꺼번에 한다” 는 식이다. 흔히 하는 실수.

이게 왜 나쁘냐면:

• 상상한 행동을 검증하게 됨 (실제 동작이 아님)
• 사용자가 실제로 하는 일보다 데이터 구조 모양을 보게 됨
• 진짜 변화에 둔감해짐 (구현 바꿔도 테스트는 그대로 통과해버림)

대신: 한 테스트 → 그 한 테스트 통과시킬 한 구현 → 다음 사이클. 이게 수직 슬라이싱 또는 tracer bullet 방식.

tracer bullet = 예광탄. 군에서 어둠 속에서 한 발씩 쏴서 궤도 보고 다음 발 쏘는 방식. TDD 도 똑같이 한 발씩 쏴서 맞는지 보고 다음 발.

• 자연어 트리거: “TDD로 이 기능 만들어줘”, “red-green-refactor로 가자”
• 슬래시: /tdd

메타·유틸

/find-skills (Vercel Labs)

이건 Matt 거 아니다. Vercel Labs 에서 만든 별도 스킬. 새 스킬 찾을 때 유용해서 같이 깔아뒀다.

“이런 거 해주는 스킬 없나?” 물으면 skills.sh 검색 해서 후보 제안.

필터링 기준:

• 1K+ install 인 것만 추천 (스팸 컷)

• 공식 출처 (vercel-labs, anthropics) 우선

• 자연어 트리거: “React 테스팅 스킬 찾아줘”, “PR 리뷰 도와주는 스킬 있어?”

• 슬래시: /find-skills

/caveman

이건 좀 웃긴 거다.

응답 토큰을 75% 압축 시키는 모드. 즉 AI 가 평소 길게 늘어놓는 응답을 동굴인처럼 짧게 끊어서 답하게 만든다.

관사·꾸밈말·인사말 다 제거. 단, 기술 정확도는 유지.

“stop caveman” 또는 “normal mode” 외칠 때까지 모든 응답에 적용된다. 단, 파괴적 작업 경고나 다단계 절차 같은 모호함 위험 상황에선 자동으로 일시 해제된다. (위험한 작업인데 너무 짧게 답하면 사고나니까.)

예시 변환:

일반:    "Sure! I'd be happy to help. The issue is likely caused by..."
캐이브맨: "Bug in auth middleware. Token expiry check use < not <=. Fix:"

이름은 좀 깨는데 — 써보니 진짜 만족이다.

가장 체감되는 효과는 컨텍스트 차는 속도가 눈에 띄게 줄어들었다는 거. 평소 같으면 한 세션에 작업 3~4개 하면 컨텍스트 거의 다 차서 compact 해야 했는데, caveman 켜두면 같은 작업량에 컨텍스트 여유가 한참 남는다.

응답 가독성이 좀 떨어지는 건 사실이지만, 근데 그게 중요한 시점이 아니면 켜두는 게 그냥 이득이다.

• 자연어 트리거: “caveman 모드”, “간결하게 답해”, “토큰 줄여”
• 슬래시: /caveman

/setup-matt-pocock-skills

mattpocock 스킬을 새 프로젝트마다 한 번씩 깔아주는 셋업 도구.

처음 그 프로젝트에서 mattpocock 스킬을 쓸 때, docs/agents/ 폴더 구조나 이슈 트래커 컨벤션 같은 걸 자동으로 만들어준다.

일회성이라 평소엔 안 부른다.

• 슬래시: /setup-matt-pocock-skills

자연어 vs 슬래시 — 이게 좀 인상적이었다

위에서 보면 알겠지만, 스킬마다 슬래시 명령 (/diagnose) 도 있고 자연어 트리거 (“이거 왜 자꾸 깨져?”) 도 있다.

원리는 — 각 SKILL.md 안에 “이런 표현이 나오면 발동” 이라는 트리거 패턴이 정의되어 있고, 메인 에이전트가 그걸 매칭해서 자동으로 해당 스킬을 호출하는 방식이다.

슬래시 외워서 칠 필요 없이, 그냥 자연스럽게 “이거 좀 진단해줘” 하면 알아서 /diagnose 가 발동된다는 거.

다만 일반적으로 메인 에이전트의 자동 위임이 항상 깔끔하게 도는 건 아닌 거 같다. 확실하게 발동시키고 싶으면 슬래시로 명시해주는 게 안전. 어느 표현이 잘 먹히는지는 써보면서 감을 잡아야 할 듯.

마치며

뜯어보고 일단 설치까지 해본 결과 — 스타 115k 가 그냥 나온 게 아니라는 게 보였다.

위에서 언급한 4가지 실패 모드는 진짜 AI 코딩 하면서 누구나 부딪히는 것들이다.

나도 같은 문제 의식으로 본인 나름의 방식은 굴려왔는데, Matt 처럼 그걸 명령어 한 줄짜리 도구로 누구나 가져다 쓰게 만들어 놓을 정도까지는 못 갔다.

그게 차이고, 부러운 지점이다.

당분간 — /grill-me 와 /improve-codebase-architecture 두 개 위주로 굴려볼 생각이다.

/caveman 은 이미 거의 항상 켜둔 상태고.

한 달쯤 굴려보면 뭔가 또 정리할 게 나올 거 같다.

마침.