AI 스킬 설계의 6가지 함정 — Matt Pocock Skills v1.0.0이 체계화한 「예측 가능한 AI 매뉴얼」 작성법

tldr

Matt Pocock(Total TypeScript 저자)이 Claude Code용 스킬셋을 v1.0.0으로 정식 출시했다. GitHub 133k 스타. 주목해야 할 점은 스킬의 내용보다, 스킬 작성법을 체계화한 메타 스킬인 「writing-great-skills」의 존재다. AI에게 전달하는 지시서(스킬) 설계에는 6가지 실패 패턴이 있으며, 이는 모두 「예측 가능성 (Predictability)」이라는 하나의 원칙으로 수렴된다. 본 기사에서는 리포지토리를 실제로 clone하여 분석한 결과를 정리한다.

「스킬」이란 무엇인가

스킬이란 AI에게 전달하는 영속적인 업무 매뉴얼을 의미한다. 프롬프트가 "오늘 이것 좀 해줘"라는 일회성 지시라면, 스킬은 "이 현장에서 일하는 동안 계속 이 규칙에 따라 움직여줘"라는 절차서에 해당한다. Claude Code에서는 슬래시 커맨드 (/skill-name)로 호출할 수 있다.

Matt Pocock의 리포지토리에는 약 30개의 스킬이 포함되어 있으며, 6개의 카테고리로 정리되어 있다.

engineering/ — 코드 워크 (TDD, 버그 진단, PRD 생성 등) -
productivity/ — 비코드 워크플로우 (브레인스토밍, 핸드오프 등) -
misc/ — 가끔 사용하는 것 -
personal/ — 개인 환경용 (비공개 취급) -
in-progress/ — 개발 중 -
deprecated/ — 폐기됨

하지만 본 기사의 주제는 개별 스킬이 아니라, 이들을 뒷받침하는 설계론이다.

6가지 핵심 개념

1. User-invoked 와 Model-invoked — 2종류의 스킬

Matt Pocock은 모든 스킬을 "누가 호출할 수 있는가"라는 하나의 축으로 분류한다.

Model-invoked는 AI가 자율적으로 발화할 수 있는 스킬이다. description 필드(설명문)를 가지며, AI는 이 설명문을 항상 컨텍스트 윈도우 (Context Window)에 올려두고 있다. AI가 작업 중에 "아, 지금 이 스킬이 필요하겠구나"라고 판단하여 자동으로 호출할 수 있다.

비유하자면, 주방 조리대 위에 항상 펼쳐져 있는 레시피 카드와 같다. 언제든 참조할 수 있지만, 조리대 공간을 차지한다.

User-invoked는 인간이 명시적으로 호출하는 스킬이다. disable-model-invocation: true를 설정하여 description을 AI로부터 숨긴다. AI는 존재조차 모르기 때문에, 인간이 슬래시 커맨드로 지정했을 때만 발화한다.

선반에 넣어둔 레시피 북 같은 것이다. 조리대를 압박하지 않지만, 인간이 "그 책이 어디 있었지"라고 기억하고 있지 않으면 사용할 수 없다.

이 설계의 배경에는 2가지 비용이 있다.

Context Load — Model-invoked 스킬의 description이 컨텍스트 윈도우를 상시 소비하는 비용. 스킬이 늘어날수록 AI의 "조리대"가 좁아져 주의력이 분산된다 -
Cognitive Load — User-invoked 스킬의 존재를 인간이 기억해야 하는 비용. 스킬이 늘어날수록 인간의 "어떤 스킬을 언제 사용할 것인가"에 대한 판단 부하가 높아진다

어느 쪽이든 비용은 반드시 발생한다. 공짜 스킬은 존재하지 않는다.

판단 기준: "AI가 자신의 판단으로 사용할 필요가 있는가?"가 Yes라면 Model-invoked, No라면 User-invoked이다. 브레인스토밍처럼 아이디어 단계에서 인간이 의도적으로 시작하는 것은 User-invoked. 버그 진단처럼 코딩 중에 AI가 자율적으로 판단해야 하는 것은 Model-invoked이다.

User-invoked 스킬이 너무 많아져 Cognitive Load가 문제가 될 경우, Matt Pocock은 **Router Skill (라우터 스킬)**로 해결한다. ask-matt라는 하나의 User-invoked 스킬이 다른 모든 User-invoked 스킬을 안내하는 접수 창구 역할을 한다. 외워야 할 스킬이 하나로 줄어든다.

2. Leading Word — 한 단어로 동작을 규정하기

Leading Word란, AI의 사전 학습에 이미 존재하는 한 단어를 「암호」로 사용하여, 스킬 내의 여러 지시를 압축하는 기법이다.

예를 들어, Matt Pocock의 grilling(벽치기 인터뷰) 스킬에는 "relentlessly"라고 적혀 있다. 단 한 단어뿐이지만, 이 단어가 있는 것만으로 AI 인터뷰의 깊이가 달라진다. AI는 사전 학습 (Pre-training)을 통해 "relentless"가 사용된 방대한 문맥을 알고 있으며, 그 모든 것이 "적당히 하지 마라, 끝까지 파고들어라"라는 뉘앙스를 담고 있기 때문이다.

Leading Word에는 두 가지 효과가 있다.

실행 시의 효과: 스킬 본문에서 Leading Word를 반복함으로써 AI의 행동 방향성을 안정시킨다. Matt Pocock은 이를 "한 단어 주위에 분산된 정의가 축적된다"라고 표현한다.

발화 시의 효과: 스킬의 description(설명)에 Leading Word를 넣어두면, 사용자가 평소 대화나 코드에서 같은 단어를 사용했을 때 AI가 해당 스킬을 자동으로 연결하여 발화하기 쉬워진다. 공통 언어가 접착제 역할을 하는 것이다.

중요한 것은 기존의 단어를 사용하는 것이다. 조어(造語)도 사용할 수 있지만, AI의 사전 학습에 없는 단어는 정의 문장에 토큰 비용 (Token Cost)이 발생한다. 사전 학습된 단어라면 그 비용이 제로가 된다.

3. No-op Test — 말하지 않아도 하는 일은 쓰지 마라

No-op (No Operation)란, 써 놓아도 쓰지 않아도 AI의 행동이 변하지 않는 지시를 말한다.

전형적인 예는 "정중하게 대응해 주세요", "사용자의 의도를 이해해 주세요"와 같은 지시이다. Claude도 GPT도 아무 말 하지 않아도 그렇게 한다. 기본 동작과 동일한 것을 쓰고 있을 뿐이므로, 토큰을 소비하면서 아무것도 만들어내지 못하고 있다.

Matt Pocock의 판단 기준은 단순하다.

그 행을 삭제하고 스킬을 작동시켰을 때, 출력이 변하는가? 변하지 않는다면 그 행은 No-op이다.

주의할 점이 두 가지 있다.

인간의 직관으로 판단하지 말 것: "정중하게 해라"가 효과가 있을지는 인간의 감각으로는 알 수 없다. 실제로 스킬에서 삭제한 뒤 출력을 비교하는 실험만이 진실을 말해준다.

모델 의존성: Claude에서는 No-op이지만 GPT에서는 효과가 있는 지시가 있을 수 있다. 같은 Claude라도 버전이 바뀌면 No-op이 아니게 될 수도 있다. 모델이 업데이트될 때마다 재검증이 필요하다.

No-op을 발견했다면 단순히 삭제하는 것이 아니라 Leading Word로 교체하는 것이 상급 기술이다. "be thorough" (No-op)를 "relentless" (강력한 Leading Word)로 바꾸는 것이다. 약한 암호를 강력한 암호로 교체하는 이미지다.

4. Premature Completion — 다음 공정이 보이면 대충 한다

Premature Completion (조기 완료)은 AI가 다음 단계를 의식한 나머지, 현재 단계를 충분히 수행하지 않고 마무리해 버리는 현상이다.

스킬 내에 Step 1부터 Step 5까지 전부 적혀 있으면, Step 1을 조사하는 도중에 Step 5의 리포트 작성을 의식하게 되어 조사가 얕아진다.

Matt Pocock은 2단계 방어 기제를 정의하고 있으며, 사용 순서가 중요하다.

제1방어: Completion Criterion (완료 기준)을 명확히 하기

"조사한다"가 아니라 "모든 API 엔드포인트의 응답 형식을 확인하고, undocumented 필드가 존재하지 않음을 검증한다"와 같이, AI가 기계적으로 "완료/미완료"를 판정할 수 있는 수준까지 구체화한다. 모호한 목표는 "이 정도면 됐지"라는 태도를 허용한다. 이 수정은 비용이 적게 들고 국소적이다.

제2방어: 이후의 공정을 숨기기 (스킬 분할)

Step 1 스킬에는 Step 1에 관한 내용만 적고, Step 2 이후는 별도의 스킬로 분리한다. AI의 시야에서 이후의 공정을 지워버리는 것이다. 다만 스킬이 늘어나면 Context Load(컨텍스트 부하)나 Cognitive Load(인지 부하)가 증가하므로, 제1방어로 해결되지 않을 때에만 사용한다.

Matt Pocock의 grill-with-docs 스킬은 이 원칙을 실천한 사례로, 내용은 단 두 줄뿐이다.

Run a `/grilling` session, using the `/domain-modeling` skill.

두 줄의 User-invoked 스킬이 두 개의 Model-invoked 스킬을 조합할 뿐이다. 이후의 공정은 완전히 보이지 않는다.

5. Deep Module — 작은 창구, 거대한 뒷모습

Deep Module (깊은 모듈)은 John Ousterhout의 "A Philosophy of Software Design"에서 유래한 개념으로, Matt Pocock은 이를 스킬 설계 전체에 적용하고 있다.

Deep Module (깊은 모듈): 작은 인터페이스(창구) 뒤에 방대한 처리(뒷단)가 숨겨져 있는 구조. 편의점에서 "삼각김밥 주세요"라고 말하면 바로 나오는 것과 같다. 그 이면에서는 매입, 제조, 배송, 검수, 진열, 재고 관리가 돌아가고 있다.

Shallow Module (얕은 모듈): 인터페이스와 구현이 비슷한 정도로 복잡한 구조. 각 창구가 도장만 찍어주는 식으로 여러 단계를 거치며 떠넘기기만 하는 구조.

Matt Pocock은 스킬의 구조 자체를 Deep Module로 설계하고 있다.

codebase-design

(Model-invoked) — Deep Module 어휘 체계의 공통 정의 -
domain-modeling

(Model-invoked) — 도메인 모델 (Domain Model)의 구축 및 업데이트 -
grilling

(Model-invoked) — 인터뷰 루프 (Interview Loop)의 공통 엔진

이러한 Model-invoked 스킬들이 "공유 부품"으로서 여러 User-invoked 스킬로부터 호출된다. grill-with-docs는 grilling + domain-modeling을, improve-codebase-architecture는 grilling + domain-modeling + codebase-design을 조합한다. 창구는 2줄이지만, 뒷단은 수백 줄에 달한다.

삭제 테스트: 모듈을 삭제했을 때 어떤 일이 일어날지 상상해 본다. 삭제해도 복잡성이 사라지지 않고 옆으로 옮겨갈 뿐이라면 그 모듈은 Shallow이다. 삭제했을 때 복잡성이 실제로 사라진다면 Deep Module로서 가치가 있다.

6. Information Hierarchy (정보 계층) — 어디까지 보여주고, 어디서부터 숨길 것인가

Information Hierarchy (정보 계층)는 스킬 내의 정보를 "AI가 언제 필요로 하는가"에 따라 3단계로 나누는 설계 기법이다.

In-skill step — SKILL.md 내의 절차. 최우선적으로 항상 보임 -
In-skill reference — SKILL.md 내의 참고 정보. 절차 다음에 보임 -
External reference — 별도 파일로 분리된 상세 내용. 필요할 때만 읽어들임

도서관 설계와 같다. 안내판에는 서가 위치만, 서가에는 저자명 인덱스(Index)가 있고, 책을 펼쳐야 비로소 본문이 나온다. 모든 정보를 안내판에 적는다면 안내판은 제 기능을 하지 못할 것이다.

정보를 아래 계층으로 옮기는 작업을 Matt Pocock은 **Progressive Disclosure (단계적 공개)**라고 부른다. SKILL.md에는 절차만 남기고, 상세한 규칙이나 예외 패턴은 별도 파일(예: GLOSSARY.md)로 밀어낸다.

여기서 중요한 것이 **Context Pointer (컨텍스트 포인터)**를 작성하는 방식이다.

<!-- NG: 포인터의 목적지만 명시 -->
자세한 내용은 GLOSSARY.md를 참조하십시오.
<!-- OK: 언제 읽어야 하는지 조건을 명시 -->
...

포인터의 목적지가 아니라, 포인터의 문구가 AI의 행동을 결정한다. 목적지가 아무리 좋은 문서일지라도 문구가 모호하면 AI는 읽으러 가지 않는다.

모든 것은 「예측 가능성」으로 귀결된다

Matt Pocock은 스킬 설계의 최상위 원칙을 **Predictability (예측 가능성)**라고 정의한다.

예측 가능성이란 "매번 같은 출력을 내는 것"이 아니라, "매번 같은 프로세스로 동작하는 것"을 의미한다. 브레인스토밍이라면 출력은 매번 다른 것이 당연하다. 하지만 "10개를 도출한다 → 3개로 압축한다 → 심층 분석한다"라는 프로세스는 매번 동일해야 한다.

6가지 개념은 모두 이 예측 가능성을 높이기 위해 존재한다.

User-invoked / Model-invoked → 스킬이 "언제 발화하는가"를 예측 가능하게 함 -
Leading Word → AI의 "행동 방향성"을 예측 가능하게 함 -
No-op Test → "효과 없는 지시"를 배제하여, 남은 지시의 효과를 예측 가능하게 함 -
Premature Completion (조기 종료) 대책 → "각 단계의 깊이"를 예측 가능하게 함 -
Deep Module → "무엇을 호출하면 무엇이 일어나는가"를 예측 가능하게 함 -
Information Hierarchy → "무엇을 언제 읽는가"를 예측 가능하게 함

6가지 실패 패턴

Matt Pocock이 GLOSSARY.md에서 정의한 실패 패턴을 정리한다.

Premature Completion (조기 완료) — 다음 공정이 보인다는 이유로 현재 공정을 건너뛴다. AI의 출력이 얕을 때 의심해야 한다. 완료 기준(Definition of Done)의 명확화 → 스킬 분할 순으로 대응한다.

Duplication (중복) — 같은 의미를 두 곳에 적는다. 한 곳을 수정하고 다른 한 곳을 잊어버리면 AI가 혼란을 겪는다. Single Source of Truth (하나의 의미는 한 곳에만)로 대응한다.

Sediment (퇴적) — 오래된 지시사항이 삭제되지 않고 축적된다. 추가는 쉽지만 삭제는 용기가 필요하기 때문에, 오래된 지층과 새로운 지층이 혼재되어 유효한 지시가 무엇인지 알 수 없게 된다. 정기적인 Pruning (가지치기)으로 대응한다.

Sprawl (확산) — 모든 행이 살아있지만 단순히 너무 길다. AI의 주의력(Attention)이 전체에 얇게 퍼져 어떤 지시도 어중간하게 적용된다. Progressive Disclosure (상세 내용을 별도 파일로 밀어내기)로 대응한다.

No-op (무효화) — 적어도 AI의 동작이 변하지 않는 지시사항이다. 토큰만 소비하고 아무것도 만들어내지 못한다. 삭제하거나 더 강력한 Leading Word로 교체하여 대응한다.

전부 Model-invoked 문제 (저자 추가) — "AI가 자동으로 사용해 주는 것이 편리하다"고 생각하여 모든 스킬에 description을 붙이면, Context Load가 팽창하여 전체 정밀도가 떨어진다. "AI가 자율적으로 판단할 필요가 있는가?"를 매번 질문해야 한다.

리포지토리 도입 방법

npx skills@latest add mattpocock/skills

대화 형식으로 스킬을 선택하고, 어떤 코딩 에이전트(Coding Agent)에 설치할지 지정한다. 처음에는 /setup-matt-pocock-skills를 실행하여 Issue tracker (GitHub Issues / Linear / 로컬 파일), triage 라벨, 문서 배치를 설정한다.

마치며

Matt Pocock의 스킬 설계론의 근저에는 뺄셈의 미학이 있다.

• 이 한 줄을 지워도 AI의 동작이 변하지 않는다면 지운다 (No-op Test)
• 이 정보를 지금 보여줄 필요가 없다면 숨긴다 (Progressive Disclosure)
• 이 스킬을 AI에게 상시 보여줄 필요가 없다면 보여주지 않는다 (User-invoked)

덧셈보다 뺄셈이 더 어렵고 용기가 필요하다. 하지만 AI에게 일을 맡기려면 매뉴얼을 쓰는 방식이야말로 성과를 결정한다. Claude Code에 국한된 이야기가 아니라, 시스템 프롬프트 (System Prompt) 설계, GPTs 구축, 사내 AI 규칙 책정 등 모든 것에 적용할 수 있는 원칙이다.

참고 자료

• Matt Pocock Skills v1.0.0 릴리스 노트
• 리포지토리 본체
• skills.sh (인스톨러)
• A Philosophy of Software Design — John Ousterhout 저 (Deep Module의 출처)
• The Pragmatic Programmer — David Thomas & Andrew Hunt 저 (Tracer Bullet의 출처)
• Domain-Driven Design — Eric Evans 저 (Ubiquitous Language의 출처)

Discussion