npx skills add mattpocock/skills 한 줄로 설치하고, /setup-matt-pocock-skills로 저장소별 설정을 마친 뒤 /ask-matt로 상황에 맞는 스킬을 안내받는다.
(저장소: mattpocock/skills · MIT · 마크다운 100% 문서 기반 · User-invoked/Model-invoked 이원 체계 · Changesets로 버전 관리되는 npm 패키지 · TrendShift 트렌딩)
이 저장소가 대체 무엇인가.
README의 자기소개는 명확하다: "My agent skills that I use every day to do real engineering - not vibe coding." ("바이브 코딩이 아니라 진짜 엔지니어링을 하기 위해 매일 쓰는 내 에이전트 스킬들.") GSD·BMAD·Spec-Kit 같은 프레임워크는 프로세스 전체를 가져가 버리지만, 이 스킬들은 작고, 적응하기 쉽고, 조합 가능하게(composable) 설계됐다고 못박는다.
구조적으로는 스킬 하나하나가 별개가 아니라 서로를 호출하는 그래프를 이룬다. 사용자가 /grill-with-docs로 아이디어를 다듬으면, 그 결과가 /to-prd → /to-issues → /implement(내부에서 /tdd 구동) → /code-review로 이어지는 "메인 플로우"를 탄다. 버그·요청이 쌓이면 /triage가 이 플로우로 합류하는 "온램프" 역할을 한다. 처음 온 사람은 /ask-matt 라우터에게 "지금 뭘 써야 하냐"고 물어보면 된다.
SKILL.md 파일 하나(+선택적 참고 파일들). 사람이 슬래시 명령으로 직접 부르거나(user-invoked), 에이전트가 상황을 보고 스스로 골라 쓴다(model-invoked). 코드가 아니라 "이 상황에선 이렇게 하라"는 규율을 자연어로 적은 문서라는 점이 핵심이다.CHANGELOG.md의 1.0.0 항목이 명시하듯, 이 저장소는 "스킬 분류 체계를 Commands/Skills에서 User-invoked/Model-invoked로 전면 개명"했다. user-invoked 스킬은 사람이 타이핑해야만 실행되고(disable-model-invocation: true), model-invoked 스킬은 에이전트가 알아서 판단해 부를 수도 있다. 그리고 규칙 하나가 그래프 전체를 지탱한다 — "user-invoked 스킬은 model-invoked 스킬을 부를 수 있지만, 다른 user-invoked 스킬은 절대 부를 수 없다." 라우터(/ask-matt)가 방향을 잃지 않게 만드는 설계다.
"바이브 코딩의 반대말" · 검증된 저자의 신뢰도 · 프레임워크가 아니라 조합 가능한 부품.
README가 짚는 4가지 실패 모드가 있다. ① 에이전트가 원하는 걸 안 만든다 — "아무도 자기가 정확히 뭘 원하는지 모른다"(The Pragmatic Programmer 인용)는 근본 문제. ② 에이전트가 너무 장황하다 — 프로젝트 고유 용어(도메인 언어)를 모른 채 20단어로 설명할 걸 1단어면 될 걸 풀어 쓴다. ③ 코드가 그냥 안 돌아간다 — 피드백 루프(타입체크·테스트) 없이 날아다닌다. ④ 진흙탕(ball of mud)이 만들어진다 — 에이전트가 코딩 속도를 높이는 만큼 소프트웨어 엔트로피도 가속시킨다.
① 정렬 문제 → /grilling 기반 끈질긴 인터뷰(/grill-me, /grill-with-docs). ② 장황함 → 도메인 공용어를 CONTEXT.md에 박아두는 /domain-modeling. ③ 안 돌아가는 코드 → Red-Green-Refactor 루프의 /tdd와 /diagnosing-bugs. ④ 진흙탕 → John Ousterhout의 A Philosophy of Software Design에서 가져온 Deep Module(깊은 모듈) 원칙을 전 스킬에 관통시키는 /codebase-design과 /improve-codebase-architecture.
| 비교 대상 | 차이점 |
|---|---|
| 개별 프롬프트 스니펫 모음 | 이 저장소는 스킬들이 서로를 호출하는 파이프라인(idea→ship)을 이룬다. 낱개 재사용이 아니라 플로우 자체가 산출물 |
| GSD·BMAD·Spec-Kit류 풀 프레임워크 | README가 직접 대비한다 — 이들은 "프로세스 전체를 가져가 버려서(own the process) 버그 해결이 어려워진다". 이 스킬들은 작고 갈아 끼우기 쉽다 |
| Claude Code 기본 내장 동작 | TDD·트리아지·코드 리뷰를 상태 기계·이축 리뷰·병렬 서브에이전트 같은 구체적 규율로 명문화. 즉흥적 판단에 맡기지 않음 |
단발성 개인 .claude 폴더 | Changesets로 버전 관리되는 npm 패키지, 문서 사이트(aihero.dev), 플러그인 매니페스트까지 갖춘 제품화된 스킬 배포 체계 |
일반 프롬프트 모음이 "레시피 카드 뭉치"라면, 이 저장소는 "코스 요리 전체 진행표 + 각 요리사(서브에이전트)의 담당 파트 매뉴얼"이다. 카드 한 장(스킬 하나)만 봐도 쓸 수 있지만, 진짜 힘은 전채(그릴링) → 메인(PRD/이슈/TDD) → 플레이팅(코드 리뷰)이 한 흐름으로 이어지고, 각 단계가 다음 단계에 정확히 무엇을 넘겨야 하는지까지 정의돼 있다는 데 있다.
①검증된 저자의 신뢰도. Matt Pocock은 TypeScript 교육 분야에서 이미 인지도가 높은 인물로, "이 사람이 실제로 매일 쓰는 워크플로"라는 후광이 크다.
②설치 마찰이 거의 없다. npx skills@latest add mattpocock/skills 한 줄, 이후 /setup-matt-pocock-skills 한 번으로 저장소별 설정(이슈 트래커·트리아지 라벨·문서 위치)이 끝난다.
③"엔지니어링 고전"을 관통하는 근거. The Pragmatic Programmer, Domain-Driven Design(Eric Evans), Extreme Programming Explained(Kent Beck), A Philosophy of Software Design(Ousterhout) — 스킬 하나하나가 특정 실패 모드와 특정 고전 개념을 짝지어 놓아, "왜 이렇게 설계했는지"가 항상 근거를 갖는다.
④살아있는 저장소. CHANGELOG.md를 보면 라우터 신설, 공유 설계 스킬 분리, 이름 변경, 스킬 폐기가 활발하게 일어난다 — 방치된 프롬프트 모음이 아니라 계속 다듬어지는 시스템이라는 인상을 준다.
코드가 아니라 문서가 제품이다 — 마크다운 100% + npm 패키징 + Changesets 릴리스.
이 저장소를 "기술 스택"으로 나누는 건 처음엔 어색하다. 실행 파일이 없기 때문이다. 하지만 스킬을 패키지처럼 버전 관리하고 배포하는 인프라는 분명히 존재하고, 그 자체가 배울 거리다.
| 구성 요소 | 역할 |
|---|---|
SKILL.md | 스킬의 본체. YAML 프론트매터(name·description·disable-model-invocation·argument-hint) + 마크다운 지침 |
| 보조 참고 파일 | GLOSSARY.md(writing-great-skills), DEEPENING.md/DESIGN-IT-TWICE.md(codebase-design), tests.md/mocking.md(tdd), HTML-REPORT.md(improve-codebase-architecture) — "본문은 짧게, 상세는 참조 파일로" 원칙(Progressive Disclosure) |
CONTEXT.md / docs/adr/*.md | 스킬이 아니라 스킬이 읽고 쓰는 산출물. 도메인 용어집과 아키텍처 결정 기록(ADR) |
| 도구 | 역할 |
|---|---|
npx skills@latest | Vercel이 만든 오픈 에이전트 스킬 CLI. npx skills add mattpocock/skills로 대화형 설치, npx skills update <name>로 갱신 |
Changesets (@changesets/cli) | npm 패키지처럼 CHANGELOG.md를 자동 생성하고 시맨틱 버전(현재 1.0.1)을 매긴다. .changeset/*.md 파일 하나하나가 "이번 변경은 major/minor/patch"라는 선언 |
GitHub Actions (release.yml) | main에 푸시될 때마다 changesets/action이 자동으로 "버전 올림" PR을 만든다(changeset version → PR → 머지 시 태그) |
.claude-plugin/plugin.json | Claude Code 플러그인 매니페스트. "승격된(promoted)" 20개 스킬 경로만 나열 — 실험적/개인용 스킬은 제외 |
npm (package.json) | private: true인 npm 패키지로 저장소 자체를 감쌈. 의존성은 @changesets/cli·@changesets/changelog-github뿐 |
scripts/link-skills.sh | 저장소 안의 모든 스킬을 ~/.claude/skills·~/.agents/skills에 심볼릭 링크로 연결. git pull만으로 로컬 설치본이 최신화됨(메인테이너 전용, "수정 요청 승인 안 함"이라 명시) |
scripts/list-skills.sh | 모든 SKILL.md 경로를 찾아 정렬 출력하는 한 줄짜리 유틸 |
docs/engineering/*.md, docs/productivity/*.md | "승격된" 두 버킷(engineering·productivity)의 스킬마다 사람이 읽는 소개 페이지. aihero.dev/skills-<name>로 발행됨 |
.agents/writing-docs.md | 문서 페이지를 쓰는 규칙 자체를 담은 메타 문서 — 고정 프레임(Quickstart·"What it does"·"When to reach for it"·"Where it fits") + 자유 서술 섹션 구조를 강제 |
이 저장소에 컴파일할 코드는 없다. 그런데도 Changesets로 시맨틱 버저닝, GitHub Actions로 자동 릴리스, npm 패키지 메타데이터, 별도 문서 사이트까지 갖췄다. "콘텐츠(마크다운 지침)"와 "소프트웨어 배포 인프라"를 분리해서, 스킬이 바뀔 때마다 사용자가 npx skills update로 정확히 무엇이 바뀌었는지(CHANGELOG) 알고 갱신할 수 있게 만든 것이 이 스택의 핵심 통찰이다.
idea→ship 메인 플로우 · 온램프 · 라우터(ask-matt) · 이축 코드 리뷰.
ask-matt/SKILL.md는 이 저장소 전체의 지도(map)다. 여기 적힌 "메인 플로우 → 온램프 → 코드베이스 헬스 → 밑바닥 어휘 레이어 → 세션 넘기기 → 독립형"이라는 6단 구조를 그대로 시스템 구조도로 옮기면 이렇다.
.agents/invocation.md가 정의하는 이 저장소의 축 하나. User-invoked는 사람이 이름을 타이핑해야만 실행되며(disable-model-invocation: true), description은 사람이 읽는 한 줄 요약이다. Model-invoked는 기본값으로, description에 "Use when the user wants…, mentions…" 같은 트리거 문구를 풍부하게 넣어 에이전트가 자동으로 골라 쓰게 한다. 판단 기준은 "재사용 가능한가"가 아니라 "모델이 스스로 이걸 유용하게 부를 수 있는가"다.
"user-invoked 스킬은 model-invoked 스킬을 부를 수 있지만, 다른 user-invoked 스킬은 절대 부를 수 없다"는 규칙이 .agents/invocation.md에 명시돼 있다. 이유는 간단하다 — user-invoked 스킬은 description이 없으므로(또는 사람 전용 문구이므로) 다른 스킬이 그것을 "발견"할 수 없다. 이 제약 덕분에 호출 그래프가 사이클 없이 한 방향으로만 깊어진다: 사람이 최상위 흐름을 시작하고, 그 흐름이 내부적으로 재사용 가능한 부품(model-invoked)을 끌어다 쓴다.
/domain-modeling과 /codebase-design은 "무언가를 실행"하기보다 다른 스킬들이 일관된 용어를 쓰게 강제하는 역할을 한다. 예를 들어 codebase-design/SKILL.md는 "Module, Interface, Depth, Seam, Adapter" 같은 용어를 정의하며 "component, service, API, boundary 같은 단어로 대체하지 말 것"이라고 못박는다. improve-codebase-architecture와 tdd 모두 이 어휘를 그대로 가져다 쓴다 — 한 곳에서 정의한 개념이 여러 스킬에서 똑같은 이름으로 재사용되는 구조다.
code-review 스킬은 diff 하나를 두 개의 독립된 질문으로 쪼갠다 — "Standards"(저장소의 코딩 표준 + Fowler 코드 스멜 기준을 지키는가)와 "Spec"(원래 이슈/PRD가 요구한 것을 충실히 구현했는가). 이 둘을 병렬 서브에이전트로 각각 돌려서 한쪽 판단이 다른 쪽 컨텍스트를 오염시키지 않게 한 뒤, 결과를 나란히 보고한다. "정확성"과 "스타일"을 같은 에이전트가 동시에 재느라 흐려지는 문제를 구조적으로 막는다.
/triage는 이슈(그리고 외부 PR도 "코드가 붙은 이슈"로 취급)를 고정된 트리아지 역할(role) 사이의 상태 기계로 이동시킨다. "PR은 코드가 첨부된 이슈다 — 같은 역할, 같은 상태, 같은 기계, 몇 가지만 PR용 델타로 표시"라는 문장이 이 설계를 요약한다. 트리아지 라벨 문자열은 저장소마다 다를 수 있어, /setup-matt-pocock-skills가 이를 한 번 물어보고 고정한다.
| 수단 | 동작 | 언제 |
|---|---|---|
/handoff | 대화를 마크다운 핸드오프 문서로 압축 → 새 세션을 열어 그 문서를 참조하며 이어감(포크) | 스레드가 꽉 찼거나, /prototype 같은 곁가지로 갈라져야 할 때 |
/compact(내장) | 같은 대화 안에서 이전 턴들을 요약(연속) | 단계 사이 의도적인 휴식 지점. 단계 중간에는 쓰지 말 것(에이전트가 길을 잃을 수 있음) |
ask-matt는 이 구분을 "handoff forks; compact continues"(핸드오프는 갈라지고, 컴팩트는 이어진다) 한 문장으로 정리한다. 또한 "Smart Zone"(최신 모델 기준 약 12만 토큰) 개념을 언급하며, 세션이 /to-issues 전에 이 구간에 가까워지면 성능 저하 상태로 밀어붙이지 말고 /handoff하라고 권한다.
"버킷(bucket)" 폴더로 승격 여부를 표현하는 구조 — 38개 스킬이 6개 폴더에 나뉘어 있다.
가장 눈에 띄는 설계는 "버킷 = 승격 상태"라는 규칙이다. CLAUDE.md가 명시하듯, engineering/·productivity/에 있는 스킬은 반드시 최상위 README·플러그인 매니페스트·docs 페이지에 등장해야 하고, 나머지 4개 버킷(misc·personal·in-progress·deprecated)의 스킬은 절대 등장하면 안 된다. 폴더 이동 하나가 "이 스킬은 공식 지원 대상"이라는 선언이 되는 셈이다.
SKILL.md 본문은 짧게 유지하고, 상세 내용(예시·긴 목록·부가 설명)은 같은 폴더의 별도 파일(tests.md, DEEPENING.md, GLOSSARY.md 등)로 분리하는 패턴. writing-great-skills/SKILL.md가 이를 "Bold terms are defined in GLOSSARY.md — look them up there"처럼 명시적으로 실천한다. 에이전트가 필요할 때만 참조 파일을 읽게 해 컨텍스트 낭비를 줄인다.이 저장소에서 "무엇을 배울 수 있는가" — 개념 → 코드 위치 → 실습 아이디어.
codebase-design/SKILL.md는 Ousterhout의 개념을 단순 요약하지 않고, "Depth as ratio of implementation-lines to interface-lines"(원저자 정의)를 의도적으로 기각하고 "Depth-as-leverage"(호출자가 배우는 인터페이스 단위당 얻는 행동량)로 재정의한다. 원전을 그대로 베끼지 않고 왜 다르게 정의했는지 "Rejected framings" 섹션에 남겨 두는 태도 자체가 배울 점이다.
실습: 자신의 프로젝트에서 함수/클래스 하나를 골라 "삭제 테스트(deletion test)" — 이걸 지우면 복잡도가 사라지는가, 아니면 호출부 N곳으로 흩어지는가 — 를 적용해 깊은 모듈인지 판별해 보기.
writing-great-skills/SKILL.md는 "A skill exists to wrangle determinism out of a stochastic system. Predictability — the agent taking the same process every run — is the root virtue"라는 문장으로 시작한다. 스킬 작성이 "좋은 프롬프트 쓰기"가 아니라 확률적 시스템에서 결정론을 짜내는 엔지니어링이라는 관점을 제시한다.
실습: .agents/invocation.md와 writing-great-skills/SKILL.md를 나란히 읽고, 자신이 반복하는 작업 하나를 골라 user-invoked/model-invoked를 판정한 뒤 SKILL.md 초안을 써 보기.
tdd/SKILL.md가 "Horizontal slicing" 안티패턴을 명시적으로 경고한다 — 테스트를 다 쓰고 나중에 구현을 다 쓰는 방식은 "상상 속의 행동을 검증하게 되고, 실제 변화에 둔감해진다"는 것. 대신 한 seam, 한 테스트, 한 최소 구현을 반복하는 수직 슬라이스 루프를 강제한다. to-issues 스킬도 같은 개념("tracer-bullet vertical slices")으로 이슈를 쪼갠다 — 하나의 개념이 코드 레벨과 프로젝트 관리 레벨 양쪽에서 반복되는 걸 확인할 수 있다.
실습: 기존 기능 하나를 수평 분할(모든 UI→모든 API→모든 DB)로 짰다면, 같은 기능을 수직 슬라이스(한 경로가 UI-API-DB를 관통)로 다시 짜 보고 두 접근의 커밋 히스토리를 비교.
.agents/invocation.md가 짚는 미묘한 구분이 있다 — "단순히 CONTEXT.md를 어휘 참고용으로 읽는 것은 domain-modeling 스킬이 아니다. 용어를 능동적으로 다듬고, 엣지 케이스로 스트레스 테스트하고, ADR을 쓰는 것만이 domain-modeling이다." "읽기"와 "능동적으로 갱신하기"를 서로 다른 층위로 구분하는 이 통찰은 DDD를 실전에 적용할 때 흔히 놓치는 지점이다.
실습: 자신의 프로젝트에 CONTEXT.md가 없다면, 자주 쓰는 도메인 용어 3개를 골라 "Avoid: ..." 형식으로 유의어를 배제하며 정의해 보기(이 저장소의 CONTEXT.md 자체가 좋은 템플릿).
code-review의 Standards/Spec 이축 병렬 리뷰, improve-codebase-architecture의 Explore 서브에이전트 활용, codebase-design/DESIGN-IT-TWICE.md의 "여러 방향으로 다른 설계를 동시에 만들어 비교"까지 — 서로 다른 관점의 판단을 한 컨텍스트에 몰아넣지 않고 병렬 서브에이전트로 분리하는 패턴이 저장소 전체에 반복된다.
실습: Claude Code의 Agent(Task) 도구로 같은 코드 diff에 대해 "표준 준수"와 "스펙 충실도"를 묻는 서브에이전트 2개를 병렬로 띄워 보고, 결과를 합쳐 리포트를 만들어 보기.
misc/git-guardrails-claude-code/SKILL.md는 PreToolUse 훅으로 git push --force·git reset --hard·git clean·git branch -D 같은 파괴적 명령을 실행 전에 가로채 차단하는 셸 스크립트를 생성한다. "승격 안 된(misc)" 버킷에 있지만, Claude Code 훅 시스템을 실전에서 어떻게 쓰는지 보여주는 가장 구체적인 예제다.
실습: 이 스킬을 설치해 settings.json에 등록되는 훅 설정을 직접 열어 보고, 자신이 자주 실수하는 명령(예: 특정 브랜치로 강제 체크아웃) 하나를 추가로 차단하는 규칙을 넣어 보기.
GPU도 서버도 필요 없다 — 진짜 요구사항은 "AI 에이전트 + 규율을 지킬 의지".
| 항목 | 요구/권장 |
|---|---|
| Node.js | npx skills@latest 실행용. v18+ 권장(패키지 자체는 packageManager: npm@10.9.4 명시) |
| AI 코딩 에이전트 | Claude Code가 1순위 대상(PreToolUse 훅·Agent/Task 서브에이전트 도구 등 Claude Code 전용 기능 다수 사용). ~/.agents/skills 경로 존재로 보아 Agent-Skills 표준을 따르는 다른 하네스와도 호환 시도 |
| 이슈 트래커 | GitHub(기본) 또는 Linear, 로컬 마크다운 파일 컨벤션. /setup-matt-pocock-skills가 최초 1회 물어봄 |
| Git | 모든 엔지니어링 스킬의 전제. resolving-merge-conflicts·code-review는 git 히스토리를 직접 조회 |
GitHub CLI(gh) | GitHub를 이슈 트래커로 쓸 때 to-issues·to-prd·triage가 활용(인증 완료 상태 필요) |
| Husky·lint-staged | misc/setup-pre-commit이 설치·설정하는 대상. 이 스킬을 쓸 프로젝트에만 필요 |
이 저장소 자체는 마크다운 + 소량의 셸 스크립트이므로 특별한 하드웨어 요구사항이 없다. 다만 실제로 "작동"하려면 에이전트 쪽의 컨텍스트 관리 능력이 중요하다.
npx skills@latest add mattpocock/skills로 설치할 스킬과 대상 에이전트를 고르고, /setup-matt-pocock-skills를 먼저 실행해야 나머지 엔지니어링 스킬(트리아지·PRD·이슈 분해)이 제대로 동작한다. README가 "Make sure you select /setup-matt-pocock-skills"라고 굵게 강조하는 이유다.
ask-matt가 경고하는 지점이다 — 그릴링·PRD·이슈 분해는 하나의 끊기지 않은 컨텍스트 윈도에서 진행돼야 사고가 이어지는데, 최신 모델 기준 약 12만 토큰(Smart Zone)을 넘어서면 추론 품질이 떨어진다. 이 구간에 다가가면 성능 저하 상태로 밀어붙이지 말고 /handoff로 새 세션을 열라고 명시한다. 즉 이 스킬 시스템은 "충분히 긴 컨텍스트"가 아니라 "컨텍스트 관리 규율"을 전제로 설계됐다.
난이도별로 손을 움직여 보는 5가지.
사이드 프로젝트 하나에 설치하고, 먼저 셋업부터 끝낸다.
# 1) 설치 (대화형으로 스킬·대상 에이전트 선택)
npx skills@latest add mattpocock/skills
# 2) 저장소별 설정 (이슈 트래커·트리아지 라벨·문서 위치)
/setup-matt-pocock-skills
# 3) 뭘 써야 할지 모르겠으면 라우터에게
/ask-matt/ask-matt가 제시하는 "메인 플로우/온램프/독립형" 분류를 자신의 현재 상황과 맞춰 보며 어떤 스킬부터 쓸지 감을 잡는다.
코드베이스가 없는 아이디어 하나(사이드 프로젝트 기획, 이번 주 할 일 등)를 놓고 /grill-me를 실행한다. 질문이 한 번에 하나씩 오는지, 각 질문에 추천 답이 딸려 오는지 관찰하고, "결정 트리의 모든 가지가 해소될 때까지" 실제로 몇 번의 질문이 필요한지 세어 본다.
코드베이스가 있는 프로젝트에서 작은 기능 하나를 골라 전체 파이프라인을 끊기지 않는 한 세션에서 통과시킨다: 1) /grill-with-docs로 아이디어 정리(CONTEXT.md·ADR 갱신 확인), 2) /to-prd로 PRD 발행, 3) /to-issues로 수직 슬라이스 이슈 분해. 이슈가 여러 개면 이슈마다 새 세션을 열어 /implement를 돌리고, 내부적으로 /tdd가 red→green을 어떻게 반복하는지 커밋 단위로 관찰한다.
어느 정도 규모 있는 기존 프로젝트에 /improve-codebase-architecture를 실행한다. 생성되는 HTML 리포트에서 각 후보 카드의 Problem/Solution/Benefits/Before-After 다이어그램/추천 강도(Strong·Worth exploring·Speculative)를 확인하고, 하나를 골라 /grilling 루프로 실제 설계까지 밀어붙인다. "삭제 테스트"를 스스로도 적용해 리포트의 판단에 동의하는지 검증한다.
자신이 반복하는 워크플로 하나를 골라 writing-great-skills와 .agents/invocation.md를 참고해 새 SKILL.md를 작성한다. user-invoked/model-invoked를 판정하고, 이 저장소의 실제 CLAUDE.md 규칙(버킷 배치·README 동기화·docs 페이지·플러그인 매니페스트 갱신)을 그대로 따라 fork에 추가해 본다. 가능하면 .changeset/에 변경 선언 파일까지 만들어 Changesets 워크플로를 끝까지 체험한다.
4주 코스 — 인터뷰 기법부터 나만의 스킬 배포까지.
| 주차 | 주제 | 구체적 목표 |
|---|---|---|
| 1주차 | 메인 플로우 익히기 | ask-matt/SKILL.md 정독 → 실제 사이드 프로젝트에 설치·셋업 → /grill-me//grill-with-docs로 그릴링 세션 최소 2회 체험 → "추천 답이 딸린 한 번에 한 질문" 패턴이 왜 효과적인지 정리 |
| 2주차 | PRD·이슈·TDD 파이프라인 | /to-prd·/to-issues·/implement·/tdd 4개 SKILL.md를 원문으로 읽고 각각의 "정의하는 제약"을 한 문장으로 요약 → 실전 기능 하나를 파이프라인 전체로 통과시켜 보기 |
| 3주차 | 설계 철학 원전 읽기 | A Philosophy of Software Design(Ousterhout) 핵심 장 발췌 읽기 → codebase-design/SKILL.md의 "Rejected framings"와 대조하며 이 저장소가 원전을 어떻게 재해석했는지 분석 → /improve-codebase-architecture를 자신의 코드베이스에 실행 |
| 4주차 | 스킬 저작 & 생태계 기여 | writing-great-skills·.agents/writing-docs.md를 참고해 자기 스킬 1~2개 작성 → Changesets로 버전 선언 → skills.sh/aihero.dev 생태계에서 다른 공개 스킬 저장소(예: obra/superpowers)와 설계 방식을 비교 |
The Pragmatic Programmer(Thomas & Hunt) — 그릴링과 피드백 루프의 근거. Domain-Driven Design(Eric Evans) — Ubiquitous Language와 domain-modeling의 근거. Extreme Programming Explained(Kent Beck) — "매일 설계에 투자하라"는 improve-codebase-architecture의 존재 이유. A Philosophy of Software Design(Ousterhout) — Deep Module과 codebase-design 전체 어휘의 근원. 네 권을 원전으로 짚어 두면 이 저장소의 모든 스킬이 "왜 이렇게 설계됐는지" 근거를 갖고 이해된다.
이 프로젝트를 읽을 때 반복 등장하는 용어 정리.
| 키워드 | 뜻 |
|---|---|
| SKILL.md | 스킬의 본체 파일. YAML 프론트매터(name·description·disable-model-invocation) + 마크다운 지침 |
| User-invoked | 사람이 타이핑해야만 실행되는 스킬. disable-model-invocation: true |
| Model-invoked | 에이전트가 상황을 보고 자동으로 판단해 부를 수도 있는 스킬(기본값) |
| 버킷 (Bucket) | 스킬을 담는 6개 폴더(engineering·productivity·misc·personal·in-progress·deprecated). engineering·productivity는 "승격됨" |
| 승격 (Promoted) | README·플러그인 매니페스트·docs 페이지에 반드시 등장해야 하는 버킷(engineering·productivity)의 상태 |
| ask-matt | 전체 스킬 그래프를 안내하는 라우터. 메인 플로우·온램프·독립형으로 지도를 나눔 |
| 메인 플로우 (Main flow) | grill-with-docs → to-prd → to-issues → implement(내부 tdd) → code-review로 이어지는 idea→ship 경로 |
| 온램프 (On-ramp) | triage·diagnosing-bugs처럼 외부에서 발생한 일을 메인 플로우로 합류시키는 진입점 |
| Deep Module (깊은 모듈) | 작은 인터페이스 뒤에 많은 행동을 숨긴 모듈. Ousterhout 개념을 이 저장소는 "leverage(레버리지)" 관점으로 재정의 |
| Seam (심) | Michael Feathers 개념. 모듈의 인터페이스가 위치하는 지점 — 코드 편집 없이 동작을 바꿀 수 있는 자리 |
| Deletion test (삭제 테스트) | 모듈을 지웠을 때 복잡도가 사라지면 통과(shallow), 호출부로 흩어지면 실패(진짜 깊은 모듈) |
| Ubiquitous Language / CONTEXT.md | DDD의 공용 도메인 언어. 이 저장소에선 CONTEXT.md 파일에 능동적으로 기록·갱신 |
| Vertical Slicing / Tracer Bullet | 한 seam·한 테스트·한 최소 구현을 반복하는 수직 분할 방식. 이슈 분해(to-issues)와 TDD 양쪽에서 쓰임 |
| Two-axis review (이축 리뷰) | code-review 스킬의 핵심. Standards(코딩 표준)와 Spec(원 요구사항 충실도)을 병렬 서브에이전트로 각각 판단 |
| Smart Zone | 모델이 날카롭게 추론하는 컨텍스트 구간(최신 모델 기준 약 12만 토큰). 넘기기 전에 handoff 권장 |
| Handoff vs Compact | Handoff=새 세션으로 포크(대화 보존), Compact=같은 세션에서 이전 턴 요약(연속) |
| Changesets | 스킬 저장소를 npm 패키지처럼 시맨틱 버전 관리·CHANGELOG 자동 생성하는 도구 |
| npx skills | Vercel이 만든 오픈 에이전트 스킬 CLI. npx skills add owner/repo로 설치 |
원본을 직접 확인하고 싶을 때.