# mattpocock/skills

> 스킬 35개는 안 받았습니다. 받은 건 그 스킬들을 어떻게 쓸지 스스로 규정한 문서 한 장이고, 그 자를 대보니 제 스킬 96개 중 1개만 통과했습니다.

- 수치: 96 중 1
- 사람이 보는 화면: https://aitryed.com/ko/teardowns/harness/mattpocock-skills/
- 반대 언어: https://aitryed.com/en/teardowns/harness/mattpocock-skills/index.md
- 저장소: https://github.com/mattpocock/skills
- 이 사이트 안내(AI용): https://aitryed.com/ko/llms.txt

---

**유명 개발자가 자기 AI 설정을 통째로 공개한 창고입니다. 설치는 안 했습니다 — 그리고 안 한 이유가 «이 창고 자신이 쓴 문서» 때문입니다. 대신 그 문서 한 장을 자로 삼아 제 도구 96개를 재 봤더니, 통과한 게 1개였습니다.**

> **[도판]** Matt Pocock이 본인 에이전트 디렉터리를 통째로 공개한 레포. 공식 마켓플레이스 플러그인으로도 출하된다.
>
> 스킬 서른다섯 개가 성숙도별 다섯 버킷에 나뉘어 있고, 승격된 두 버킷 스물다섯 개만 플러그인으로 출하된다. 배포 경로는 자동 갱신되는 구독형과 파일을 복사해 내가 소유하는 소유형 둘이고, 둘 다 깔면 스킬이 두 벌이 된다.

## 이 창고가 파는 것

AI에게 시킬 수 있는 **명령 묶음 35개**입니다.

특이한 건 **자기 소개 방식**입니다. 「우리가 전부 관리해 드립니다」가 아니라 <strong>「우리는 당신의 작업 방식을 뺏지 «않는다»」</strong>를 앞에 겁니다. 경쟁하는 쪽을 대놓고 지목합니다.

## 문제 진단이 좋았습니다

AI에게 코딩을 시킬 때 나는 문제 넷을 이렇게 정리합니다.

| 문제 | 왜 그런가 |
|---|---|
| **원하는 걸 안 만들어 준다** | **아무도 자기가 뭘 원하는지 정확히 모른다** |
| **말이 너무 길어진다** | 우리 팀 은어를 모르니 **한 단어면 될 걸 스무 단어로** 씀 |
| **코드가 안 돌아간다** | 확인할 방법이 없으면 **눈 감고 나는 것**과 같음 |
| **엉망진창이 된다** | AI가 코딩을 빠르게 하면 **엉망이 되는 속도도 같이 빨라짐** |

마지막 줄이 특히 좋습니다. **속도가 빨라지면 좋은 것만 빨라지는 게 아닙니다.**

## 그런데 설치를 안 했습니다 — 이 창고 자신의 논리 때문입니다

여기가 재미있는 자리입니다.

이 창고에 **교리 문서 한 장**이 실려 있습니다. 거기서 <strong>「상시 로드되는 것을 최소화하라」</strong>고 말합니다.

그런데 **이 창고를 설치하면 도구 설명 25개가 매 대화마다 자동으로 실립니다.**

즉 **자기가 하지 말라고 쓴 것을, 설치하면 하게 됩니다.**

그래서 안 깔았습니다. <strong>이 창고의 논리를 따른 결과가 「이 창고를 안 깐다」</strong>였습니다.

## 대신 그 문서 한 장을 가져왔습니다 — 「부하가 두 종류다」

이 창고에서 제가 실제로 가져온 것입니다. 그리고 이게 35개 도구보다 값이 컸습니다.

AI에게 도구를 붙일 때 생기는 부담이 **두 종류**인데, 보통 이 둘을 섞어서 생각합니다.

| 부담 | 누가 지나 | 어떻게 해야 하나 |
|---|---|---|
| **기계가 지는 부담** | 매 대화마다 자동으로 실리는 모든 글자. **쓰든 안 쓰든 매번** 실림 | **줄여야 함** |
| **사람이 지는 부담** | 「뭐가 있고 언제 꺼낼지」를 사람이 기억해야 함 | ⚠**줄이면 안 됨** |

두 번째 줄이 핵심입니다. **사람이 지는 부담은 줄이는 게 목표가 아닙니다.**

왜냐면 — **사람이 「이럴 땐 이걸 쓴다」를 아는 것 자체가 색인 역할**이기 때문입니다. 그걸 없애려고 전부 자동으로 켜지게 만들면, **기계 쪽 부담이 폭발**합니다.

**둘을 섞어서 「부담을 줄이자」고 하면 방향을 잘못 잡습니다.**

## 그 자로 제 것을 재 봤습니다 — 96개 중 1개

제 도구 96개를 그 기준으로 재 봤습니다.

**「부를 조건이 제대로 걸려 있는 것」이 1개**였습니다.

나머지 95개는 조건이 없거나 모호해서, **설명문 20,672자가 매 대화마다 자동으로 실리고** 있었습니다. 쓰든 안 쓰든요.

이게 앞에서 본 「도구를 깔아 놓고 한 번도 안 켰다」의 **비용 쪽 이야기**입니다. 안 켜도 **비용은 매번 나갑니다.**

## 또 하나 가져온 것 — 「끝났다」를 어떻게 정의할 것인가

AI에게 일을 시킬 때 **「됐다/안 됐다」를 구분 못 하면**, **진짜 끝나기 전에 끝냅니다.** 그리고 한 번 「끝났다」 쪽으로 기울면 그쪽으로 계속 미끄러집니다.

완료 조건에 갖춰야 할 속성이 둘이라고 합니다.

**하나 — 경계가 날카로울 것.**

「이해에 도달했다」 같은 건 **경계가 없습니다.** 어디까지가 이해인지 아무도 모릅니다. 그러면 AI가 <strong>아무 데서나 「도달했다」</strong>고 합니다.

**둘 — 요구가 강제력을 가질 것.**

이 대비가 좋았습니다.

| 이렇게 쓰면 | 결과 |
|---|---|
| 「변경 목록을 만들어라」 | **철저함을 강제하지 못함** — 목록만 만들면 끝 |
| **「수정된 모든 항목이 설명될 것」** | **철저함을 강제함** — 하나라도 빠지면 조건 미달 |

두 문장은 비슷해 보이는데 **강제력이 완전히 다릅니다.** 앞엣것은 **행동**을 요구하고, 뒤엣것은 **상태**를 요구합니다. 상태를 요구해야 빠짐이 드러납니다.

## 정리 — 35개가 아니라 1장이었습니다

이 편의 결론입니다.

| 무엇 | 가져왔나 |
|---|---|
| 도구 35개 | **안 가져옴** — 설치하면 이 창고 자신의 규칙을 어김 |
| **교리 문서 한 장** | **가져옴** |

그리고 그 한 장으로 **제 것 96개 중 95개가 걸렸습니다.**

**남의 도구를 안 가져와도, 남의 «자»는 가져올 수 있습니다.** 그리고 자가 도구보다 값이 클 때가 있습니다.

## 여기부터는 자세한 기록입니다

**설치는 안 했습니다 — 이 레포 자신의 논리 때문입니다.** 플러그인을 깔면 스킬 설명 25개가 매 턴 상시 컨텍스트에 얹히는데, 그게 정확히 이 레포가 하지 말라고 쓴 것입니다. 대신 **그 교리 문서 한 장을 자로 삼아 제 스킬 96개를 재봤습니다.** 결과가 이 페이지입니다 — **호출 축이 걸려 있는 건 1개**였고, 나머지 95개의 설명 20,672자가 매 턴 상시 로드되고 있었습니다.



## 무엇을 파는 레포인가

**슬래시 커맨드 묶음이다.** 다만 셀링포인트가 "프로세스를 소유하는 프레임워크가 **아니라는** 것"이다. README가 경쟁자를 직접 지목한다.

> 그런 접근은 프로세스를 대신 소유해서 돕는다. 그러면서 **통제권을 뺏고, 프로세스 자체의 버그를 고치기 어렵게 만든다.** 이 스킬들은 작고, 고치기 쉽고, 조합 가능하게 설계됐다.

그리고 스킬을 나열하지 않는다. **에이전트가 자주 망하는 실패 모드 넷을 축으로 놓고, 각각에 처방 스킬을 붙인다.**

| 실패 모드 | 진단 | 처방 |
|---|---|---|
| **원하는 걸 안 만든다** | *"아무도 자기가 뭘 원하는지 정확히 모른다"* — 사람과 에이전트 사이의 소통 격차 | 압박 질문 세션 |
| **너무 장황하다** | 프로젝트 은어를 모르니 한 단어면 될 걸 스무 단어로 쓴다 | 공유 어휘 문서 + 도메인 모델링 |
| **코드가 안 돌아간다** | 피드백 루프 부재. 타입·브라우저·자동 테스트가 없으면 눈 감고 난다 | TDD · 버그 진단 |
| **진흙 공을 만들었다** | 에이전트가 코딩을 가속하면 **소프트웨어 엔트로피도 같이 가속된다** | 코드베이스 설계 |

두 번째 항목의 예시가 노골적이다. **BEFORE:** "코스 안 섹션 안의 레슨이 '실체화'될 때(파일시스템에 자리를 받을 때) 생기는 문제" → **AFTER:** "실체화 연쇄에 문제가 있다." 그리고 이걸 감성이 아니라 **토큰 논리로 정당화한다** — 공유 언어가 있으면 에이전트가 사고에 쓰는 토큰이 준다.

스타는 **207,586개**인데 기여자는 3명이다. 생후 6개월에 20만은 저자의 뉴스레터 청중이 만든 숫자지 코드 검증량이 아니다. 다만 **포크가 17,928개**로 스타 대비 11.6 대 1이라, [Odysseus](/ko/teardowns/harness/odysseus/index.md)의 450 대 1보다는 훨씬 건전하다 — 실제로 가져다 쓰는 비율이 있다는 뜻이다.

## 실제로 가져온 것 — 두 개의 부하

값어치는 스킬 35개가 아니라 **그 스킬들을 어떻게 쓸지 규정한 교리 문서 한 장**에 있다. 첫 문장이 목표를 정확히 규정한다.

> 같은 레버가 각각을 예측 가능하게 만든다 — 에이전트가 매 실행마다 **같은 프로세스를 밟게** 하는 것이지, 같은 출력을 내게 하는 게 아니다.

그 문서의 축이 **비용이 두 종류**라는 것이다.

| 부하 | 누가 지나 | 처방 |
|---|---|---|
| **컨텍스트 부하** | 기계 — 상시 로드되는 모든 줄. 발동하든 안 하든 매 턴 토큰과 주의력을 쓴다 | **최소화 대상** |
| **인지 부하** | 사람 — 뭐가 있고 언제 꺼낼지. 사람이 색인 노릇을 한다 | ⚠**최소화 대상이 아니다** |

두 번째가 반직관적이다. **사람의 인지 부하는 줄여야 할 비용이 아니라 주체성의 값**이라는 것. 판단이 필요한 자리에는 남기고, 아닌 자리에서만 없앤다.

여기서 나온 실무 규칙이 셋 더 있다.

**점진적 공개는 토큰 최적화가 아니라 분산 레버다.** 공개했어야 할 참조 자료를 본문에 두면 스텝이 파묻히고, 그 스텝에 주의가 가는 일이 **동전던지기**가 된다. 가독성이 아니라 편차의 문제다.

**부정으로 조종하면 오히려 끌어온다.** 금지된 행동이 컨텍스트로 들어와 더 접근 가능해진다 — *"코끼리를 생각하지 마"*, 그러면 코끼리밖에 없다. 부정은 약한 수식어라 강하게 활성화된 개념이 그걸 짓밟고, **금지가 절반쯤 지시로 읽힌다.** 긍정 목표를 진술해서 금지된 쪽은 입에 올리지 않는 게 맞다.

**no-op을 사냥한다.** 모델이 기본값으로 이미 지키는 지시는 부하만 내고 아무 말도 안 한다. 판정 기준은 <strong>"기본값 대비 행동이 바뀌나"</strong>이고, 독자 기준이 아니라 모델 기준이다. 그래서 no-op이냐 아니냐로 두 사람이 다투면 그건 기본값에 대한 이견이고 — **토론이 아니라 문서를 실행해서 결판낸다.**

## 완료 조건에 두 속성이 있다

에이전트가 "됐다/안 됐다"를 구분 못 하면 **조기 완료**가 일어난다. 진짜 끝나기 전에 끝내고, 주의가 '끝났음' 쪽으로 미끄러진다.

| 속성 | 무엇 |
|---|---|
| **명료성** | 경계가 모호하면("이해에 도달했다") 조기 완료를 부른다. 경계를 먼저 날카롭게 |
| **요구도** | **"수정된 모든 모델이 설명될 것"은 철저함을 강제하고, "변경 목록을 만들어라"는 안 한다** |

가장 강한 기준은 **확인 가능하면서 소진적**인 것이다. 요구도는 별도 스텝으로 쓰이지 않고 문구에 잠복한다.

## 재본 결과 — 96개 중 1개

> **[도판]** 교리를 읽었으니 자를 대봤다. 실측일 기준 <code>~/.claude/skills/</code> 폴더 102개 · 문서 96개.
>
> 내 스킬 96개를 사각형 96개로 그렸다. 호출 축이 걸려 있는 것은 단 하나이고 나머지 95개의 설명이 매 턴 상시 로드된다.

이 레포의 유일한 분류 축이 **사용자호출 / 모델호출**이다. 판정 질문 하나 — **"모델이 이걸 자율적으로 집는 게 유용한가?"**

| | 모델호출 (기본) | 사용자호출 |
|---|---|---|
| 설명문 | 모델용 — 트리거 문구를 풍부하게 | 사람용 — 슬래시 목록에서 읽는 한 줄 |
| 부하 | 영구 컨텍스트 부하 ↔ 발견 가능성 | **컨텍스트 부하 0** ↔ 인지 부하 |
| 도달 | 모델 또는 사람 — 모델호출은 사람 접근을 **포함한다** | 사람만 |

**제 것에서 가장 선명한 사례가 하나 나왔다.** 한 스킬의 설명문이 스스로 이렇게 쓰고 있었다 — *"명시 호출 전용 — 일반 작업 중에 이해 확인 질문으로 사용자를 붙잡지 않는다."*

**정책은 산문으로 선언돼 있는데, 하네스가 강제하는 플래그는 안 걸려 있다.** Matt의 축으로 읽으면 이건 **사용자호출 스킬을 모델호출로 배포한 것**이다 — 모델이 집을 수 있는 상태로 두고 본문에 "집지 마"라고 쓴 셈이고, 위에서 본 **부정 실패 모드가 정확히 이 모양**이다. 플래그 한 줄이 그 산문 전체를 대체한다.

⚠ 그렇다고 96개 전부에 거는 건 오답이다. 상당수는 모델호출이 **필수**다 — 오케스트레이터가 부르는 파이프라인 스킬들이 그렇다. **축의 값어치는 전환이 아니라 96개를 그 질문으로 한 번 통과시키는 것**이고, 걸기 전에 그 스킬을 부르는 에이전트·훅이 있는지 먼저 확인해야 한다.

## 안 가져온 것과 그 이유

**플러그인 설치는 기각.** 근거 넷이 전부 실측이다.

- **설명 25개가 상시 컨텍스트에 추가된다.** 이미 95개가 무제한 로드 중인 환경에 얹는 건 **저자 본인 교리에 정면 위배**
- **중복** — TDD·코드리뷰·인계·리서치가 제 쪽에 이미 같은 역할로 있다
- **전제 불일치** — 엔지니어링 스킬 대부분이 특정 이슈트래커 배선을 요구하는데 제 실작업 도구엔 어댑터가 없다
- **언어** — 설명문이 영어라 한국어 발화에 대한 모델호출 적중률이 제 기존 스킬보다 낮다

**대신 세 가지를 규율로 가져왔다.** 「이건 안 한다」를 이유와 함께 못 박은 폴더를 두는 것(제 기각 목록은 지금 약어로만 살아 있어서 **왜** 기각했는지가 안 실려 있다), 리뷰를 두 축으로 나누되 **병합·재랭킹을 금지**하는 것(서식 지적이 커버리지 누락을 가리는 걸 막는다), 그리고 질문을 하나씩 왕복하지 말고 **지금 물을 수 있는 것 전부를 한 라운드로 묶되 각각에 추천안을 붙이는 것**.

마지막 것에 붙은 한 줄이 좋다 — **"사실을 찾는 건 내 일이지 사용자 일이 절대 아니다. 내가 직접 찾아볼 수 있는 걸 사용자에게 묻지 마라. 결정은 사용자 것이다."**

## 반면교사도 있다

**이 레포엔 테스트가 없다.** 자동 검증은 플러그인 매니페스트 유효성 검사 정도고, 스킬 본문의 품질은 저자의 손 검증에 의존한다. *"문서를 실행해서 결판낸다"*는 교리가 있는데 **그 실행이 CI에 없다.** 이 축에서는 제 쪽이 앞선다 — 문서와 현실을 대조하는 린터 둘이 기계로 돌고 있다.

**"프로세스를 소유하지 않는다"는 주장에도 반례가 있다.** 상위 엔지니어링 스킬 몇은 이슈트래커 스키마·라벨 어휘·문서 배치를 상당히 규정한다. README가 때리는 경쟁자들과 **정도의 차이지 종류의 차이는 아니다.** 진짜로 "작고 조합 가능"한 건 생산성 버킷과 압박 질문 계열이다.

그리고 예제는 전부 웹·타입스크립트 편향이다. **가져올 건 어휘와 규율이지 예제가 아니다.**