이 저장소가 풀려는 문제
AI 코딩 에이전트가 빠르게 코드를 만들면서 아키텍처를 망가뜨리는 일은 이제 흔합니다. 에이전트가 사용자의 의도를 잘못 이해하고, 프로젝트 용어를 못 맞추고, 만든 코드가 동작하지 않는 문제도 반복됩니다.
mattpocock/skills는 이 문제를 슬래시 커맨드 형태의 작업 지시서로 해결합니다. 에이전트가 무작정 코드를 고치지 않고, 정해진 흐름을 따르게 만듭니다.
요구사항 정렬 → 도메인 언어 정리 → PRD 작성 → 이슈 쪼개기 → TDD 구현 → 버그 진단 → 아키텍처 개선. AI가 이 순서를 스스로 따르게 만드는 것이 이 저장소의 핵심입니다.
설치와 초기화
프로젝트 루트에서 한 줄로 설치합니다.
1# 설치 2npx skills@latest add mattpocock/skills 3 4# 설치 UI에서 스킬 선택 후 5# 에이전트 안에서 초기화 실행 6/setup-matt-pocock-skills
/setup-matt-pocock-skills는 이슈 트래커 설정, triage 라벨 매핑, 도메인 문서 위치를 물어봅니다. 이 정보는 다른 모든 스킬이 참조하는 기반이 됩니다.
초기화가 끝나면 프로젝트에 AGENTS.md 또는 CLAUDE.md, docs/agents/ 문서들이 생성됩니다. 여기에 이슈 트래커 방식, triage 라벨, 도메인 용어가 저장됩니다.
12개 스킬 한눈에 보기
핵심 스킬 깊이 보기
/grill-me, /grill-with-docs — 요구사항 압박 면접
사용자가 아이디어나 설계를 던지면, 에이전트가 모든 의사결정 분기를 하나씩 질문하면서 빈틈을 채웁니다. /grill-with-docs는 여기에 프로젝트의 CONTEXT.md와 ADR을 읽고 기존 도메인 용어와 충돌하는지 검증까지 합니다.
/to-prd, /to-issues — 기획을 개발 단위로 분해
/to-prd는 대화 맥락을 종합해 PRD를 만듭니다. 핵심은 사용자를 다시 인터뷰하지 않고 이미 있는 대화를 활용한다는 점입니다.
/to-issues는 PRD를 vertical slice로 쪼갭니다. horizontal slice가 아니라 tracer bullet 방식의 얇고 완성 가능한 end-to-end 단위입니다.
2. API 만들기
3. UI 만들기
4. 테스트 만들기
2. 사용자가 오늘의 운동 완료를 기록할 수 있다 (schema + API + UI + test 포함)
3. 운동 완료 시 코인 보상 내역을 볼 수 있다 (schema + API + UI + test 포함)
/tdd — 테스트 하나, 구현 하나
이 스킬은 "테스트 먼저 전부 작성 → 구현 전부 작성"이 아니라 한 테스트 → 한 구현 → 다음 테스트 방식의 vertical red-green-refactor 루프를 강제합니다.
- 테스트는 구현 세부사항이 아니라 public interface의 행동을 검증
- 내부 함수명 변경 때문에 깨지는 테스트는 나쁜 테스트
- 한 번에 하나의 테스트만 추가
- GREEN 상태 전에는 refactor 금지
- 테스트 이름은 프로젝트 도메인 glossary와 맞춤
/diagnose — 추측 금지, 재현 먼저
이 스킬은 "코드 읽고 바로 수정"이 아니라 재현 루프부터 구축하는 보수적 디버깅을 강제합니다.
/improve-codebase-architecture — Deep Module 찾기
코드베이스에서 테스트 가능성과 AI 탐색성을 기준으로 얕은 모듈을 deep module로 개선할 기회를 찾습니다. 바로 refactor 코드를 작성하지 않고, 먼저 후보 목록을 제시한 뒤 사용자가 고른 후보에 대해 grilling loop로 들어갑니다.
이 스킬은 CONTEXT.md와 ADR을 읽고, 현재 도메인 언어와 과거 설계 결정을 존중합니다. 새 용어를 만들지 않고 기존 용어 내에서 개선안을 제시합니다.
실무 워크플로우 조합
새 기능 개발
버그 수정
가벼운 시작 조합
작은 프로젝트에서 모든 스킬을 쓰는 것은 과합니다. 처음에는 이 네 가지만 시작하세요.
| 스킬 | 용도 | 바로 쓰는 상황 |
|---|---|---|
/setup | 초기화 | 프로젝트 처음 시작할 때 |
/tdd | 테스트 루프 | 기능 구현할 때마다 |
/diagnose | 버그 진단 | 버그 리포트 들어올 때 |
/zoom-out | 코드 이해 | 모르는 코드 영역 만났을 때 |
기획과 이슈 관리까지 에이전트에 맡기고 싶을 때만 /grill-with-docs, /to-prd, /to-issues, /triage, /improve-codebase-architecture를 추가하세요.
이 저장소의 핵심 가치
이 저장소는 "AI가 코드를 더 많이 쓰게 하는 도구"가 아닙니다. AI가 덜 위험하게, 더 실무적인 순서로 일하게 만드는 운영 프레임워크입니다.
- 무작정 구현하지 않고 질문과 정렬부터 하게 만든다
- 요구사항 → PRD → 이슈 → TDD → 디버깅까지 연결된 파이프라인
CONTEXT.md와 ADR을 통해 에이전트가 프로젝트의 언어와 설계 결정을 기억하게 만든다
주의할 점
/to-prd, /to-issues, /triage는 이슈 트래커와 triage label vocabulary를 전제로 동작합니다. /setup-matt-pocock-skills에서 이 설정을 대충하면 잘못된 라벨 생성, 기존 워크플로우 충돌, ready-for-agent 기준 모호화 등의 문제가 생깁니다.
또한 이 저장소는 CONTEXT.md에 "Claude Code가 로드하는 agent skills" 모음이라고 명시되어 있습니다. Codex, Cursor, 다른 에이전트에서도 개념적으로는 활용 가능하지만, 실제 설치와 호출 UX는 각 도구의 skill 지원 방식에 맞게 옮겨야 합니다.
/write-a-skill — 나만의 스킬 만들기
이 스킬을 사용하면 자신만의 커스텀 스킬을 만들 수 있습니다. 스킬 구조는 다음과 같습니다.
SKILL.md의 description은 에이전트가 어떤 스킬을 로드할지 판단하는 유일한 정보입니다. 1024자 이하, 3인칭, "Use when..." 트리거를 포함해야 합니다.
- Suno 스타일 음악 프롬프트 생성 스킬
- Runway/Seedance 15초 영상 프롬프트 분할 스킬
- Flutter App Store 심사 대응 체크리스트 스킬
- AI 영상 제작 — 캐릭터 일관성, 배경 일관성, lip-sync 규칙 자동 포함 스킬
- 유튜브 썸네일/설명/쇼츠 변환 스킬
추천 첫 사용 순서
1# 1. 설치 2npx skills@latest add mattpocock/skills 3 4# 2. 초기화 5/setup-matt-pocock-skills
그리고 실제 작업에서는 목적에 따라 조합하세요.
| 상황 | 조합 |
|---|---|
| 새 기능 | /grill-with-docs → /to-prd → /to-issues → /tdd |
| 버그 수정 | /diagnose → /tdd |
| 구조 개선 | /zoom-out → /improve-codebase-architecture |
| 나만의 자동화 | /write-a-skill |