본문 바로가기
AI 생성 글 정리/tech_github

mattpocock/skills — “vibe coding”을 엔지니어링 루프로 바꾸는 Agent Skill 컬렉션

by Honbul 2026. 5. 19.

 

한 줄 요약: mattpocock/skills는 Claude Code, Codex 등 코딩 에이전트가 요구사항 정렬, PRD/이슈 분해, TDD, 디버깅, 아키텍처 개선을 반복 가능한 절차로 수행하게 만드는 Markdown 기반 스킬 모음이다.

 


그림: 저장소 내 원본 시각 자료는 README의 외부 skills.sh 배지 정도로 제한적이다. 본 리포트의 figures/ 이미지는 저장소 구조와 워크플로를 설명하기 위해 생성한 분석 다이어그램이다.

Quick Links

구분 링크 비고
GitHub 저장소 https://github.com/mattpocock/skills README, 소스 구조, Issues, Discussions
skills.sh 프로젝트 페이지 https://www.skills.sh/mattpocock/skills 설치 수, 개별 skill 페이지, npx skills add 명령
skills.sh 문서 https://www.skills.sh/docs skill 개념, CLI, badge, API 설명
설치 명령 npx skills@latest add mattpocock/skills README의 30초 Quickstart 기준
GitHub Discussions https://github.com/mattpocock/skills/discussions 커뮤니티 질문 및 사용 패턴 논의
Wiki https://github.com/mattpocock/skills/wiki 2026-05-19 확인 기준 별도 Wiki는 없고 저장소 루트로 리다이렉트됨
논문 없음 이 저장소는 논문 기반 프로젝트가 아니라 실무용 skill corpus에 가깝다

프로젝트 개요

mattpocock/skills는 독립 실행 애플리케이션이 아니라 에이전트가 필요할 때 읽는 절차 지식 패키지다.

각 skill은 보통 SKILL.md 하나와 선택적 보조 문서·스크립트로 구성된다. SKILL.md 상단에는 name, description, 경우에 따라 argument-hint, disable-model-invocation 같은 front matter가 있으며, 이 설명이 에이전트가 어떤 skill을 로드할지 판단하는 핵심 단서가 된다.

 

저장소의 철학은 큰 프레임워크로 개발 과정을 대신 소유하는 것이 아니라, 소프트웨어 엔지니어링의 기본 루프를 얇고 조합 가능한 스킬로 쪼개는 것이다.

README는 네 가지 실패 모드—요구 불일치, 장황한 언어, 피드백 없는 코드 생성, “ball of mud” 아키텍처—를 중심으로 skill들을 배치한다.

Key Features

1. 요구사항 정렬: /grill-me와 /grill-with-docs

/grill-me는 사용자의 계획이나 설계를 무작정 구현하지 않고, 의사결정 트리의 각 분기를 한 번에 하나씩 질문해 공유된 이해에 도달하게 한다.

/grill-with-docs는 여기에 도메인 용어집인 CONTEXT.md와 아키텍처 결정 기록인 ADR을 결합한다.

사용자가 모호하거나 충돌하는 용어를 쓰면 즉시 정정하고, 결정이 굳어지는 순간 CONTEXT.md 또는 ADR에 기록한다.


그림: 요구사항 정렬 → PRD → vertical slice 이슈 → triage → TDD/diagnose → 아키텍처 개선으로 이어지는 전체 흐름이다.

2. PRD와 이슈 분해: /to-prd, /to-issues

/to-prd는 현재 대화와 코드베이스 이해를 바탕으로 PRD를 합성하고 이슈 트래커에 게시한다.

특징은 추가 인터뷰를 하지 않는다는 점이다. 이미 확보한 맥락을 정리해 문제, 해결책, 사용자 스토리, 구현 결정, 테스트 결정, 범위 제외 항목으로 구성한다.

 

/to-issues는 PRD나 계획을 “tracer bullet”식 vertical slice 이슈로 나눈다.

즉, DB·API·UI·테스트 같은 계층별 horizontal slice가 아니라, 작지만 end-to-end로 동작하고 독립 검증 가능한 단위로 쪼갠다.

각 slice는 AFK 또는 HITL로 구분되어 자동 에이전트에게 넘길 수 있는지 판단한다.

 


그림: PRD/이슈 관련 skill은 issue tracker, triage label, domain docs 설정을 필요로 하므로 /setup-matt-pocock-skills가 선행 설정을 담당한다.

3. Triage 상태 머신: /triage

/triage는 이슈를 하나의 category role(bug 또는 enhancement)과 하나의 state role(needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix)로 관리한다.

모든 triage 코멘트에는 AI가 생성했다는 disclaimer를 붙이도록 되어 있어, 사람이 읽는 issue tracker에서 provenance를 명시한다.

 

버그 이슈는 grilling보다 재현을 먼저 시도한다.

재현 결과가 확인되면 agent brief가 더 견고해지고, 정보가 부족하면 needs-info로 돌려 구체적인 질문을 남긴다. Enhancement가 wontfix인 경우 .out-of-scope/ 지식베이스에 기록해 같은 제안이 반복되는 것을 줄이는 설계도 있다.


그림: unlabeled issue는 needs-triage를 거쳐 정보 요청, agent-ready, human-ready, wontfix로 이동한다. reporter가 응답하면 needs-info에서 다시 평가된다.

4. 테스트 주도 개발: /tdd

/tdd의 핵심은 red-green-refactor를 “한 테스트 → 한 구현” 단위로 수행하는 것이다.

이 skill은 테스트가 구현 세부사항이 아니라 public interface의 observable behavior를 검증해야 한다고 강조한다.

또한 “모든 테스트를 먼저 쓰고 모든 구현을 나중에 하는” horizontal slicing을 반패턴으로 규정한다.

이 관점은 에이전트가 미래 기능을 추측해 과잉 구현하는 것을 줄인다.

하나의 tracer bullet을 만들고, 그 결과에서 배운 점을 다음 테스트에 반영하기 때문에 테스트가 실제 동작에 더 민감해진다.

5. 디버깅 discipline: /diagnose

/diagnose는 하드 버그와 성능 회귀를 위한 6단계 루프다.

먼저 빠르고 결정적인 feedback loop를 만든 뒤, 재현, 가설 수립, instrumentation, fix + regression test, cleanup + post-mortem을 진행한다.

재현 루프가 없으면 추측으로 넘어가지 말라는 규칙이 강하다.

 

비결정적 버그도 “깨끗한 재현”이 아니라 재현율을 높이는 방향으로 다룬다.

예를 들어 loop를 100회 돌리고, 병렬화하고, timing window를 좁혀 1% flake를 디버깅 가능한 수준으로 끌어올리는 방식이다.

 


그림: /tdd와 /diagnose는 모두 에이전트가 빠르고 결정적인 pass/fail 신호를 확보하도록 설계되어 있다.

6. 아키텍처 개선: /improve-codebase-architecture

/improve-codebase-architecture는 shallow module을 deep module로 바꾸는 “deepening opportunity”를 찾는다.

여기서 module은 함수, 클래스, 패키지, slice 등 interface와 implementation을 가진 모든 단위를 뜻한다.

좋은 module은 interface는 작고 implementation은 깊다. 즉, 호출자는 적게 알아도 많은 동작을 얻는다.

 

이 skill은 단순 리팩터링 제안기가 아니다.

CONTEXT.md의 도메인 용어와 docs/adr/의 과거 결정을 읽어, 현재 코드가 어디서 이해 비용을 키우는지, 어디서 테스트 seam이 약한지, 어디서 locality와 leverage가 부족한지를 찾는다.

기존 ADR과 충돌하는 제안은 “실제 마찰이 충분히 크면 재논의할 후보”로 표시한다.


그림: GitHub tree, README reference, plugin manifest, skills.sh registry가 서로 다른 공개 표면을 이룬다. 특히 README는 misc까지 설명하지만 .claude-plugin/plugin.json은 engineering/productivity 중심이다.

7. 생산성·안전 보조 skill

/caveman은 토큰 절약을 위해 응답을 극도로 압축하는 모드다.

/handoff는 현재 대화 내용을 새 에이전트가 이어받을 수 있는 handoff 문서로 압축한다.

/write-a-skill은 새 skill을 작성할 때 SKILL.md, reference 파일, script 분리 기준을 제시한다.

git-guardrails-claude-code는 Claude Code hook으로 git push, git reset --hard, git clean, git branch -D 같은 위험한 git 명령을 차단한다.

setup-pre-commit은 Husky, lint-staged, Prettier, typecheck, test를 pre-commit hook에 묶는 보조 skill이다.

Tech Stack

영역 구성 버전/상태
Skill 정의 SKILL.md + front matter + Markdown 절차 문서 버전 고정 없음
Manifest .claude-plugin/plugin.json mattpocock-skills 이름으로 installable skill 경로 선언
설치 npx skills@latest add mattpocock/skills README는 latest 사용. 고정 버전 없음
실행 환경 Claude Code, Codex 등 agent runtime 저장소는 특정 모델에 종속되지 않는다고 설명
스크립트 Bash: scripts/link-skills.sh, scripts/list-skills.sh, diagnose/scripts/hitl-loop.template.sh, git guardrail hook GitHub language 위젯은 Shell 100%로 표시하지만 실제 핵심 콘텐츠는 Markdown
Issue tracker GitHub, GitLab, local markdown, 기타 freeform workflow /setup-matt-pocock-skills가 선택 및 문서화
GitHub/GitLab CLI gh, glab setup skill 설명에 등장. 버전 고정 없음
Pre-commit Husky, lint-staged, Prettier setup-pre-commit에서 Husky v9+ 언급, package version 고정 없음
Git guardrail dependency Bash + jq hook script가 JSON tool input에서 command를 읽기 위해 jq 사용
License MIT License Copyright 2026 Matt Pocock

Architecture


그림: skills.sh/npx로 설치된 Markdown skill들이 agent runtime에 의해 선택적으로 로드되고, per-repo config, domain docs, issue tracker, feedback loop와 연결되는 구조다.

 

아키텍처를 세 층으로 보는 것이 가장 명확하다.

  1. Distribution layer: GitHub 저장소와 skills.sh가 skill corpus를 배포한다.
    README에는 Quickstart와 reference가 있고, .claude-plugin/plugin.json은 설치 가능한 skill 경로를 선언한다.
  2. Skill corpus layer: skills/engineering, skills/productivity, skills/misc, skills/personal, skills/in-progress, skills/deprecated가 bucket 역할을 한다.
    안정적으로 홍보되는 것은 top-level README의 engineering/productivity/misc이고, personal/in-progress/deprecated는 plugin이나 README 노출에서 제외되어야 한다는 규칙이 CLAUDE.md에 적혀 있다.
  3. Runtime integration layer: 각 프로젝트에서 /setup-matt-pocock-skills가 issue tracker, triage label vocabulary, domain docs layout을 기록한다.
    이후 /to-prd, /to-issues, /triage 같은 hard-dependency skill은 이 설정 없이는 정확히 작동하기 어렵고, /diagnose, /tdd, /improve-codebase-architecture, /zoom-out 같은 soft-dependency skill은 설정이 있으면 더 좋은 용어와 맥락을 사용한다.

소스 구조 요약

mattpocock/skills
├── .claude-plugin/
│   └── plugin.json                 # installable skills 경로 선언
├── .out-of-scope/                  # 반복 거절/범위 제외 지식베이스
├── docs/adr/
│   └── 0001-explicit-setup-pointer-only-for-hard-dependencies.md
├── scripts/
│   ├── link-skills.sh              # 로컬 ~/.claude/skills symlink 생성
│   └── list-skills.sh              # SKILL.md 목록 출력
├── skills/
│   ├── engineering/                # daily code work
│   ├── productivity/               # non-code workflow tools
│   ├── misc/                       # rarely used tools
│   ├── personal/                   # author setup 전용, 비홍보
│   ├── in-progress/                # 개발 중, 비홍보
│   └── deprecated/                 # 더 이상 사용하지 않는 skill
├── CLAUDE.md                       # 저장소 유지보수 규칙
├── CONTEXT.md                      # 이 저장소 자체의 도메인 용어집
├── LICENSE
└── README.md

설계상 흥미로운 지점

  • README와 plugin manifest의 노출 표면 차이: README는 engineering 10개, productivity 4개, misc 4개를 모두 reference에 담는다.
    반면 .claude-plugin/plugin.json은 engineering 10개와 productivity 4개만 선언한다.
    CLAUDE.md에는 engineering/productivity/misc가 README와 plugin에 있어야 한다는 규칙이 있어, 현재 snapshot에서는 misc 노출 정책이 약간 애매하다.
  • Hard dependency vs soft dependency 분리: ADR-0001은 setup pointer를 모든 skill에 반복하지 않고, issue tracker/label mapping이 없으면 잘못된 출력이 나오는 skill에만 명시하자는 결정을 기록한다.
  • 문서의 역할을 제한: CONTEXT.md는 spec도 scratchpad도 아니며, 구현 상세가 없는 용어집이어야 한다.
    ADR은 되돌리기 어렵고, 맥락 없이는 놀랍고, 실제 trade-off가 있었던 결정에만 만든다.

Usage & Setup

1. 설치

npx skills@latest add mattpocock/skills

 

설치 과정에서 사용할 skill과 대상 coding agent를 선택한다. README는 /setup-matt-pocock-skills를 반드시 선택하라고 안내한다.

2. 초기 설정

/setup-matt-pocock-skills

 

이 skill은 repo를 탐색한 뒤 세 가지를 한 번에 하나씩 묻는다.

A. Issue tracker: GitHub / GitLab / local markdown / 기타
B. Triage label vocabulary: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix
C. Domain docs: single-context 또는 multi-context

 

그 결과 다음과 같은 문서가 생성되거나 갱신된다.

AGENTS.md 또는 CLAUDE.md
└── ## Agent skills

docs/agents/
├── issue-tracker.md
├── triage-labels.md
└── domain.md

3. 일반적인 개발 사용 순서

/grill-with-docs     # 요구사항·도메인 용어·설계 결정 정렬
/to-prd              # 현재 대화 맥락을 PRD로 합성
/to-issues           # PRD를 vertical slice 이슈로 분해
/triage              # 이슈 상태와 agent-readiness 판단
/tdd                 # 하나의 behavior test와 구현을 반복
/diagnose            # 버그 또는 성능 회귀를 재현·측정·수정
/improve-codebase-architecture  # 구조적 마찰을 deep module 후보로 정리
/handoff             # 다음 에이전트 세션으로 넘길 요약 생성

4. 로컬 Claude CLI에 직접 symlink하는 보조 스크립트

저장소에는 설치 CLI와 별개로 로컬 symlink를 만드는 스크립트도 있다.

bash scripts/link-skills.sh
bash scripts/list-skills.sh

 

link-skills.sh는 skills/ 아래의 SKILL.md를 찾아 ~/.claude/skills에 symlink한다. 단, deprecated 경로는 제외한다. list-skills.sh는 모든 SKILL.md 경로를 정렬해 출력한다.

Discussions & Wiki 분석

Wiki

2026-05-19 기준 https://github.com/mattpocock/skills/wiki는 별도 wiki 콘텐츠를 보여주지 않고 저장소 루트로 리다이렉트된다.

따라서 장문 공식 문서는 README, skill별 SKILL.md, CONTEXT.md, docs/adr/, skills.sh 문서가 사실상 문서 체계 역할을 한다.

Discussions

Discussions에는 2026-05-17 생성된 “Welcome to Discussions!” 공지와 2026-05-17의 PRD lifecycle 질문이 확인된다.

특히 PRD lifecycle 논의는 이 저장소의 철학을 잘 드러낸다.

커뮤니티 답변은 PRD를 장기 문서라기보다 완료 후 의미가 약해지는 planning artifact로 보는 쪽에 수렴했고, maintainer인 Matt Pocock은 “가능한 한 코드는 문서가 되어야 하며, /grill-with-docs는 코드가 제공하지 못하는 얇은 문서층—용어 정의와 혼란스러운 아키텍처 결정—을 제공하기 위해 만들었다”는 취지로 답했다.

 

이 관점은 프로젝트의 문서 철학을 요약한다. PRD는 계획과 분해를 위한 checkpoint이고, 장기 지식은 코드, CONTEXT.md, ADR, issue history에 남긴다.

Personal Insights

의료 AI 관점

의료 AI 시스템에서는 “에이전트가 빨리 코드를 쓰는 것”보다 검증 가능한 추적성이 중요하다. 이 저장소의 구조는 그 요구와 잘 맞는 부분이 있다.

  • CONTEXT.md는 clinical term, cohort definition, phenotype, endpoint, exclusion criteria 같은 도메인 용어를 표준화하는 데 유용하다. 의료 문서에서 같은 단어가 임상·보험·연구 맥락마다 다르게 쓰이는 문제를 줄일 수 있다.
  • ADR은 “왜 이 triage 기준을 썼는가”, “왜 이 모델 inference threshold를 선택했는가”, “왜 특정 EHR field를 제외했는가” 같은 되돌리기 어려운 결정을 남기는 데 적합하다.
  • /diagnose의 재현 우선 원칙은 의료 AI regression 분석에 중요하다.
    임상 안전 이슈를 “느낌상 원인”으로 고치는 것은 위험하므로, failing test, captured trace, fixture, differential loop가 먼저 필요하다.
  • 다만 PHI/PII, 규제 검증, model monitoring, calibration drift, clinical validation protocol은 저장소의 scope 밖이다.
    의료 AI에 적용하려면 별도 skill로 data-governance, clinical-safety-review, model-eval, audit-log-review 같은 절차를 추가해야 한다.

Bioinformatics 관점

Bioinformatics 파이프라인은 실험 조건, reference genome, annotation version, sample metadata, batch effect, container image, random seed에 강하게 의존한다.

mattpocock/skills의 가장 큰 장점은 이런 복잡성을 작은 검증 가능한 loop로 자르는 사고방식이다.

  • /to-issues의 vertical slice는 “QC만 구현”, “alignment만 구현” 같은 horizontal ticket보다, 작은 샘플셋을 끝까지 통과시키는 demoable slice에 더 잘 맞는다.
  • /diagnose의 differential loop는 “old pipeline vs new pipeline”, “reference v1 vs v2”, “parameter A vs B” 비교에 직접 대응된다.
  • /prototype의 logic branch는 variant calling state machine, sample eligibility, QC gate, report generation rule을 빠르게 검증하는 데 유용하다.
  • 한계는 provenance와 reproducibility를 formal하게 다루지 않는다는 점이다.
    Bioinformatics용으로는 workflow-provenance, nf-core/snakemake-debug, data-versioning, benchmark-fixture skill이 추가되면 실전성이 커진다.

Autonomous Agent 개발 관점

이 저장소는 “자율 에이전트에게 더 많은 자유를 주는” 프로젝트가 아니라,

자율성을 feedback loop와 human control 아래에 두는 프로젝트다. 그 점이 중요하다.

  • /triage는 agent-ready와 human-ready를 분리한다.
    이는 autonomous agent 운영에서 위임 가능성과 human-in-the-loop 필요성을 구분하는 최소 장치다.
  • /setup-matt-pocock-skills는 repo별 issue tracker와 label vocabulary를 먼저 정렬한다.
    에이전트가 외부 시스템을 변경하기 전에 운영 계약을 명확히 하는 방식이다.
  • git-guardrails-claude-code는 에이전트의 도구 권한을 제한하는 작은 보안 패턴이다.
    완전한 sandbox는 아니지만, 위험한 git 명령을 hook으로 차단한다는 점에서 실용적이다.
  • /handoff는 장기 작업에서 context compaction을 의식적으로 수행하게 한다.
    이는 장시간 autonomous workflow에서 memory drift를 줄이는 데 중요하다.

추가하면 좋은 autonomous-agent용 확장 skill은 다음과 같다.

/eval-before-merge        # 변경 전후 평가 지표 비교
/tool-permission-audit    # agent tool 권한과 위험 명령 점검
/rollback-plan            # agent가 만든 변경의 rollback 가능성 검토
/telemetry-review         # 에이전트 작업 후 runtime metric/log 확인
/prompt-injection-review  # 외부 issue/comment/docs를 읽을 때 instruction injection 방어

종합 평가

mattpocock/skills의 핵심 가치는 prompt 모음이 아니라 AI coding을 기존 소프트웨어 엔지니어링 루프에 다시 묶는 것이다.

구현보다 앞서는 요구 정렬, 도메인 언어, vertical slice, red-green-refactor, 재현 가능한 디버깅, deep module 설계가 반복적으로 강조된다.

장점은 다음과 같다.

  • Skill 단위가 작아 복사·수정·조합이 쉽다.
  • 특정 모델에 강하게 묶이지 않고, Markdown procedural knowledge로 이동성이 높다.
  • CONTEXT.md와 ADR을 사용해 에이전트가 “프로젝트 언어”를 학습하도록 유도한다.
  • 이슈 트래커와 triage role을 활용해 자동화 가능한 작업과 사람이 판단해야 하는 작업을 분리한다.
  • TDD와 diagnose가 “빠른 pass/fail 신호”를 중심으로 코드 품질을 제어한다.

한계도 명확하다.

  • 저장소 자체에는 테스트 스위트나 정량 벤치마크가 없다.
  • 설치/registry 표면과 현재 GitHub tree 사이에 일부 count·노출 차이가 보인다.
  • 의료 AI나 Bioinformatics처럼 규제·데이터 lineage·검증 프로토콜이 필요한 영역에는 도메인 특화 skill이 추가되어야 한다.
  • PRD 이후 장기 product documentation을 어디에 둘지는 프로젝트별 관례가 필요하다.

Sources

'AI 생성 글 정리 > tech_github' 카테고리의 다른 글

TradingAgents — 실제 트레이딩 데스크를 모사한 멀티 에이전트 LLM 금융 분석 프레임워크  (0) 2026.05.19
Sniffnet — Rust 기반 크로스플랫폼 네트워크 트래픽 모니터  (0) 2026.05.19
CloakBrowser — 소스 레벨 지문 패치 기반 Stealth Chromium 자동화 브라우저  (0) 2026.05.19
Local Deep Research — 로컬·프라이버시 중심 에이전틱 리서치 어시스턴트  (0) 2026.05.19
andrej-karpathy-skills — Karpathy 관찰을 Claude/Cursor용 코딩 에이전트 행동 규칙으로 패키징한 프로젝트  (0) 2026.05.19

관련글

티스토리툴바