[심층분석] Claude Code의 숨은 무기, '스킬'을 공개합니다 — Matt Pocock의 .claude 디렉터리 전격 해부

들어가며: '스킬'이라는 새로운 흐름

최근 AI 코딩 도구를 쓰는 개발자들 사이에서 조용히 번지고 있는 키워드가 하나 있어요. 바로 '에이전트 스킬(Agent Skill)'입니다. 이게 뭐냐면, 쉽게 말해 AI 코딩 어시스턴트(Claude Code 같은 도구)에게 "이런 상황에서는 이렇게 일해줘"라고 미리 정해둔 작업 매뉴얼이라고 보시면 돼요. 사람으로 치면 신입사원에게 건네는 업무 가이드 같은 거죠.

TypeScript 커뮤니티에서 유명한 교육자이자 콘텐츠 크리에이터인 Matt Pocock이 자신의 .claude 디렉터리에 있던 개인 스킬 모음집을 통째로 GitHub에 공개했어요. 저장소 이름도 단순하게 mattpocock/skills. 그동안 본인이 실무에서 갈고닦아온 '나만의 AI 작업 레시피'를 그대로 꺼내놓은 거예요.

이게 왜 중요하냐면요, AI 코딩 도구를 처음 써본 분들은 대부분 비슷한 경험을 하거든요. "오, 신기하다" 하고 몇 번 써보다가, 막상 실무에 적용하려니 결과물이 들쭉날쭉해서 결국 다시 손으로 짜게 되는. 그 격차를 메워주는 게 바로 이 '스킬' 개념이에요. 단순한 프롬프트 모음이 아니라, 반복 가능한 워크플로우를 정형화한 자산이라는 점에서 의미가 큽니다.

이번 글에서는 이 저장소가 왜 흥미로운지, 어떤 스킬들이 들어있는지, 그리고 한국 개발자들이 어떻게 활용할 수 있을지를 차근차근 풀어볼게요.

'Agent Skill'이라는 게 도대체 뭔가요?

먼저 용어부터 짚고 갈게요. Agent Skill은 Claude Code, Cursor 같은 AI 코딩 도구에서 "특정 작업을 수행하는 절차"를 마크다운 파일로 저장해둔 단위예요. 예를 들어 tdd라는 이름의 스킬을 호출하면, AI가 자동으로 "테스트를 먼저 작성하고, 실패시키고, 최소 코드로 통과시키고, 리팩터링한다"는 TDD 루프를 따라가게 되는 거죠.

비유하자면 이래요. 회사에 새로 들어온 후배에게 매번 "보고서는 이런 양식으로, 회의록은 저런 흐름으로 써"라고 일일이 설명하는 게 귀찮잖아요? 그래서 사내 위키에 템플릿을 정리해두면, 후배가 알아서 그걸 보고 따라 하죠. 스킬도 똑같아요. AI에게 일관된 일하는 방식을 학습시키는 위키 페이지 같은 겁니다.

Matt Pocock의 저장소에서는 이걸 한 단계 더 발전시켰어요. npx skills@latest add mattpocock/skills/<스킬이름> 한 줄이면 내 프로젝트의 .claude 디렉터리에 해당 스킬이 설치되거든요. npm 패키지 설치하듯이 스킬을 설치하는 거예요. 이게 의외로 큰 변화인데, 이전까지는 다들 자기 프롬프트를 자기 컴퓨터에만 쌓아두고 있었거든요. 이제는 스킬을 공유 가능한 오픈소스 자산으로 다루기 시작한 거죠.

저장소 안을 들여다보면

공개된 스킬들을 카테고리별로 살펴볼게요. 이 분류만 봐도 "아, 이 사람이 평소에 어떻게 일하는지"가 그대로 드러나서 재미있어요.

1. 기획·설계 단계 스킬

• to-prd: 지금까지 대화한 내용을 PRD(Product Requirements Document, 제품 요구사항 문서)로 정리해서 GitHub 이슈로 자동 등록해줘요. 따로 인터뷰하지 않고 그동안 나눈 대화만 가지고 합성해주는 게 포인트예요.
• to-issues: 큰 계획이나 PRD를 잘게 쪼개서 "한 사람이 한 번에 집어 들 수 있는" 크기의 GitHub 이슈들로 분해해줍니다. 여기서 핵심 키워드가 'vertical slice(수직 슬라이스)'인데요, 쉽게 말해 "화면 한쪽 구석이라도 좋으니, 사용자가 실제로 쓸 수 있는 기능 단위로 자른다"는 뜻이에요. UI만 만들고 백엔드는 나중에, 이런 식으로 자르지 않는다는 거죠.
• grill-me: 이름부터 재미있죠. "나를 굽다(grill)"라는 표현 그대로, AI가 내 계획을 끈질기게 추궁해줘요. "이 결정의 다른 분기는요?", "이 가정은 왜 맞다고 생각해요?" 하면서 의사결정 트리의 모든 가지를 따져 묻는 스킬이에요. 혼자 기획할 때 사각지대를 줄이는 데 유용하겠죠.
• design-an-interface: 모듈 하나의 인터페이스를 여러 서브 에이전트가 병렬로 각각 다른 스타일로 설계해줍니다. 여기서 오케스트레이션(orchestration)이라는 개념이 등장하는데, 쉽게 말하면 "여러 AI가 각자 맡은 일을 하도록 지휘하는 것"이에요. 한 명의 AI가 답을 하나 내놓는 게 아니라, 여러 AI가 동시에 다른 답을 내놓고 비교하는 방식이죠.
• request-refactor-plan: 사용자 인터뷰를 거쳐 "아주 작은 커밋 단위"로 쪼갠 리팩터링 계획을 만들어 GitHub 이슈로 등록해줘요.

2. 개발 실행 단계 스킬

• tdd: 클래식한 TDD(Test-Driven Development, 테스트 주도 개발) 루프를 AI가 대신 운전해줘요. "빨강(테스트 실패) → 초록(통과) → 리팩터링" 사이클을 한 슬라이스씩 처리합니다. TDD를 머리로는 알지만 손이 잘 안 가는 분들에게 특히 유용할 것 같아요.
• triage-issue: 버그를 받아서 코드베이스를 직접 탐색하고, 근본 원인을 찾아낸 다음, TDD 기반 수정 계획까지 포함된 GitHub 이슈를 만들어줍니다. 그냥 "고쳐줘"가 아니라 "문서로 남기고 추적 가능하게 만들어줘"라는 점이 다르죠.
• improve-codebase-architecture: 코드베이스에서 "더 깊게 파고들 만한 지점"을 찾아주는데, 이때 CONTEXT.md의 도메인 언어와 docs/adr/의 의사결정 기록을 참고해요. 여기서 ADR(Architecture Decision Record)이 뭔지 잠깐 설명하면, "왜 이 기술을 골랐는지, 왜 이 구조를 선택했는지"를 짧게 기록해두는 문서예요. 나중에 "근데 이거 왜 이렇게 만들었지?" 싶을 때 답을 찾을 수 있게 해주죠.
• migrate-to-shoehorn: 특정 라이브러리(shoehorn)로 마이그레이션해주는 매우 구체적인 스킬이에요.
• scaffold-exercises: 학습용 연습문제 골격을 자동 생성해줍니다. 교육 콘텐츠를 만드는 Matt 본인의 색깔이 강하게 드러나는 스킬이죠.

3. 도구·환경 정비 스킬

• git-guardrails-claude-code: AI가 마음대로 git push --force 같은 위험한 명령을 못 하도록 가드레일을 설치해줘요. 이게 의외로 중요한데, AI에게 자율성을 주면서도 "실수해도 복구 가능한 범위" 안에서만 움직이게 하는 거거든요.
• setup-pre-commit: pre-commit 훅을 자동 세팅해줘요.
• github-triage, triage-issue: GitHub 이슈 관리 자동화.
• obsidian-vault: 옵시디언 노트와 연결.
• caveman: 이름이 재미있죠. 추측건대 "원시인처럼 단순하게" 작업하라는 모드 같아요.
• zoom-out: 디테일에 너무 빠졌을 때 한 발짝 물러나서 큰 그림을 보게 해주는 스킬이에요.

4. 도메인 모델링 계열

• domain-model, ubiquitous-language: 둘 다 도메인 주도 설계(DDD)의 핵심 개념이에요. "유비쿼터스 언어"라는 건, 쉽게 말해 "개발자도 기획자도 디자이너도 같은 단어를 같은 뜻으로 쓰자"는 약속이에요. 이걸 코드와 문서에 일관되게 반영하도록 도와주는 스킬이죠.

5. 메타 스킬

• write-a-skill: 스킬을 만드는 스킬. 일종의 자기 복제 도구인데, 이게 있어야 사용자가 자기만의 스킬을 빠르게 추가할 수 있어요.

설계 철학: '바이브 코딩'을 넘어서

Matt Pocock의 스킬들을 쭉 훑어보면 일관된 철학이 보여요.

첫째, 모든 결과물은 추적 가능해야 한다는 거예요. PRD든, 리팩터링 계획이든, 버그 수정이든 결국 GitHub 이슈로 떨어져요. 채팅창에서 흘러가버리는 게 아니라 영구 보관소로 옮겨지는 거죠.

둘째, 작게 자른다는 원칙이에요. 'vertical slice', 'tiny commits', 'red-green-refactor' 같은 키워드가 반복되거든요. AI에게 큰 덩어리를 맡기면 환각(hallucination)이 늘고 검증이 어려워지는데, 작은 단위로 쪼개면 인간이 따라가기 쉬워져요.

셋째, 인간이 의사결정 트리의 주인이라는 점이에요. grill-me 스킬이 대표적인데, AI가 답을 내놓는 게 아니라 사용자가 답하도록 압박해요. AI를 "답을 주는 신탁"이 아니라 "질문을 잘하는 동료"로 쓰는 방식이죠.

이 철학이 중요한 이유는, 요즘 유행하는 '바이브 코딩(vibe coding)'의 반대편에 서 있기 때문이에요. 바이브 코딩이라는 건, 쉽게 말해 "감으로 AI에게 던지고, 결과물이 마음에 안 들면 다시 던지기"를 반복하는 스타일이거든요. 빠르긴 한데, 일정 규모를 넘어가면 코드베이스가 엉망이 되기 쉬워요. Matt의 스킬들은 그 반대편에서 "AI를 쓰되, 엔지니어링 규율은 지키자"고 말하는 거죠.

다른 접근법과 비교해보면

Cursor Rules / .cursorrules

Cursor는 .cursorrules라는 파일에 "이 프로젝트에서는 이런 규칙으로 코딩해"를 써두는 방식을 씁니다. 이건 상시 적용되는 규칙에 가까워요. "우리는 항상 TypeScript strict 모드를 쓴다" 같은 거죠.

반면 Claude의 스킬은 호출형 워크플로우예요. 필요할 때 "이번엔 TDD 모드로 가자" 하고 불러내는 식이죠. 둘은 충돌하는 게 아니라 보완 관계예요. 규칙은 항상 켜두고, 워크플로우는 상황에 맞게 골라 쓰는 거죠.

GitHub Copilot Workspace, Cline, Aider

Copilot Workspace는 "이슈 → 계획 → 구현"의 흐름을 GitHub이 직접 통합해서 제공해요. 편하긴 한데, 절차가 GitHub에 묶여 있어요.

Matt의 접근은 로컬 파일 기반이라는 점이 달라요. 마크다운 파일 몇 개라서 어떤 도구에든 옮겨 쓸 수 있고, 팀원과 PR로 리뷰할 수도 있어요. "플랫폼 락인(특정 회사 도구에 갇히는 것)"이 없다는 게 큰 장점이죠.

Anthropic Skills 공식 문서와의 관계

Anthropic도 공식적으로 Skills 개념을 밀고 있는데, Matt의 저장소는 그 위에서 동작하는 개인 컬렉션 사례예요. 마치 npm 위에 lodash가 올라가는 것처럼, 공식 인프라 위에 커뮤니티 자산이 쌓이기 시작한 시점이라고 보면 됩니다.

한국 개발자에게 주는 시사점

자, 이제 실무 얘기로 넘어가볼게요. 한국에서 일하는 분들에게 이게 어떤 의미인지요.

시나리오 1: 1인 개발자 / 사이드 프로젝트

혼자 사이드 프로젝트 하시는 분이라면, 일단 tdd와 to-issues만 깔아도 효과를 볼 수 있어요. 평소에 "테스트 짜야지" 하면서도 손 안 가던 분들이 "AI야, TDD 모드로 이 기능 만들어줘" 한 줄이면 빨강-초록-리팩터링 사이클을 강제로 따라가게 되거든요. npx skills@latest add mattpocock/skills/tdd 한 번 실행하는 데 1분도 안 걸려요.

시나리오 2: 5~20명 규모 스타트업

이 규모에서 가장 골치 아픈 게 "사람마다 AI 쓰는 방식이 다 달라서 코드 스타일이 갈라지는" 문제예요. 이때 팀 공용 .claude/skills 디렉터리를 git으로 관리하면, 모두가 같은 워크플로우를 공유하게 돼요. 신입이 들어와도 "우리 팀은 이 스킬들을 써" 한마디로 온보딩이 끝나죠.

특히 git-guardrails-claude-code는 거의 필수라고 봐요. AI가 실수로 main에 강제 푸시하는 사고, 생각보다 흔하거든요.

시나리오 3: 대기업 / SI

대기업에서는 보안 이슈로 외부 GitHub 저장소를 그대로 못 쓰는 경우가 많죠. 그럴 땐 이 저장소를 참고용 레퍼런스로 보고, 사내에 비슷한 구조의 스킬 저장소를 만드는 걸 추천해요. 도메인이 금융이면 "규제 준수 체크 스킬", 커머스면 "결제 흐름 검증 스킬" 같은 식으로 자기 도메인에 맞춰 변형하면 됩니다.

학습 로드맵 제안

1. 1주차: 저장소를 클론해서 README를 정독하고, tdd와 to-issues 두 개만 직접 써보기.
2. 2주차: write-a-skill을 써서 본인의 작업 패턴 하나를 스킬로 직접 만들어보기. (예: "PR 설명 자동 작성")
3. 3주차: 팀원과 공유하고, 팀 공용 스킬 저장소를 사내에 셋업하기.
4. 4주차: ADR(docs/adr/)와 CONTEXT.md를 같이 도입해서 improve-codebase-architecture 스킬이 제 성능을 내도록 환경 정비.

도입 시 주의할 점

• 무비판적 복붙은 금물: Matt의 스타일이 모든 팀에 맞지는 않아요. 예를 들어 to-prd는 영문 PRD 스타일이라, 한국 팀에서 그대로 쓰면 어색할 수 있어요. 한 번 읽어보고 톤을 자기 팀에 맞게 수정하세요.
• 스킬도 코드처럼 리뷰: 스킬 추가는 PR로 받고, 변경 시 리뷰하는 문화가 필요해요. 안 그러면 "왜 이 스킬이 여기 있지?" 하는 유령 자산이 쌓여요.
• 민감 정보 주의: 스킬 안에 사내 URL, API 엔드포인트, 키 같은 게 들어가지 않도록 조심하세요.

마무리: 스킬 생태계의 시작점

이번 공개가 의미 있는 건, 한 사람의 노하우가 "블로그 글"이나 "트윗"이 아니라 실행 가능한 자산으로 풀렸다는 점이에요. 글로 "이렇게 일하세요"라고 쓰는 것과, 명령어 한 줄로 그 일하는 방식이 내 컴퓨터에 설치되는 건 완전히 다른 차원의 공유잖아요.

앞으로 1~2년 안에 npm처럼 "스킬 마켓플레이스"가 자리 잡을 가능성이 높다고 봐요. 도메인별, 언어별, 회사별 스킬 컬렉션이 쏟아질 거고, 그중 일부는 사실상의 표준으로 굳을 거예요. 지금 이 흐름의 초입에 들어와 있는 거죠.

그리고 더 흥미로운 건, AI 코딩의 경쟁력이 점점 "누가 어떤 스킬을 어떻게 조합하는가"로 옮겨가고 있다는 점이에요. 모델 성능 차이는 점점 좁혀지고 있고, 결국 차이를 만드는 건 사용자의 워크플로우 설계 능력이거든요. 이건 좋은 소식이에요. 모델을 만드는 빅테크가 아니어도 누구나 자기만의 우위를 쌓을 수 있다는 뜻이니까요.

여러분에게 묻고 싶은 것

• 지금 AI 코딩 도구를 쓰면서 "매번 똑같이 시키는데 결과가 다르게 나와서 답답한 작업"이 있나요? 그게 바로 첫 번째 스킬로 만들 후보예요.
• 팀에서 AI 워크플로우를 표준화한 경험이 있다면, 어떤 충돌과 합의 과정을 거쳤나요?
• Matt의 스킬 중에 "이건 한국 팀 정서엔 안 맞을 것 같다" 싶은 게 있다면 어떤 거고, 왜 그렇게 느꼈나요?