Skills - AI 에이전트를 위한 실제 엔지니어링 스킬

1. 프로젝트 개요

Skills(Matt Pocock 제작)는 AI 에이전트 "스킬"의 오픈소스 모음입니다. 재사용 가능하고 구성 가능한 명령어 세트로, Claude Code 및 Codex와 같은 코딩 에이전트에게 빠르지만 신뢰할 수 없는 코드 생성 대신 규율 있는 실제 소프트웨어 엔지니어링 관행을 가르칩니다.

2. 배경 및 포지셔닝

Skills는 개발자들이 AI 코딩 에이전트를 사용할 때 겪는 네 가지 반복적인 실패 패턴을 해결하기 위해 만들어졌습니다.

개발자 의도와 에이전트 출력 간의 불일치 — grill-me 및 grill-with-docs와 같은 구조화된 인터뷰 스킬로 완화합니다.
프로젝트 명확성을 저해하는 에이전트의 장황함 — 공유 도메인 언어와 에이전트를 프로젝트 용어에 기반하도록 유지하는 CONTEXT.md 규칙으로 해결합니다.
약한 피드백 루프로 인한 깨진 코드 — 테스트 주도 개발(tdd) 및 구조화된 디버깅(diagnosing-bugs)으로 해결합니다.
빠른 에이전트 주도 개발 하의 아키텍처 붕괴 — improve-codebase-architecture와 같은 설계 중심 스킬로 방지합니다.

크고 올인원 "에이전트 프레임워크" 프로젝트와 달리, Skills는 의도적으로 작고 독단적이지 않게 유지됩니다. 각 스킬은 모놀리식 시스템의 일부가 아닌 독립적이고 편집 가능한 Markdown 파일입니다. 이로 인해 팀이 필요한 정확한 부분만 채택하거나 수정, 포크, 축소하기 쉬우며, 전체 규범적 워크플로우를 도입할 필요가 없습니다.

3. 기능 카테고리

🛠️ 엔지니어링 스킬 — 사용자 호출형(8개 스킬): 개발자가 워크플로우를 조율하기 위해 명시적으로 트리거합니다.

ask-matt — 작업에 적합한 스킬을 찾도록 도와주는 라우터
grill-with-docs — 프로젝트의 도메인 모델을 구축하는 인터뷰 세션
triage — 이슈 상태 관리 및 우선순위 지정
improve-codebase-architecture — 아키텍처 개선 사항 제안 및 제시
implement — TDD가 내장된 기능 구축
목적: 일반적인 고수준 엔지니어링 워크플로우에 대한 명시적 진입점을 개발자에게 제공합니다.

🤖 엔지니어링 스킬 — 모델 호출형(8개 스킬): 에이전트가 작업 중에 적용 시점을 결정합니다.

tdd — 테스트 주도 개발 루프를 강제합니다.
diagnosing-bugs — 구조화된 가설 기반 디버깅 방법론
research — 출처 인용이 필요한 조사 워크플로우
domain-modeling — 일관된 프로젝트 용어를 강화하고 유지합니다.
code-review — 이중 축(정확성 + 사양 준수) 검토 기준을 적용합니다.
목적: 개발자가 요청하지 않아도 에이전트의 기본 동작에 엔지니어링 규율을 직접 내장합니다.

📈 생산성 스킬 — 사용자 호출형(4개 스킬): 개발자가 트리거하는 워크플로우 도우미입니다.

grill-me — 대규모 작업 전 철저한 계획 인터뷰
handoff — 다른 에이전트 세션에 작업을 넘기기 위한 대화 요약 생성
teach — 온보딩을 위한 다중 세션 스킬 교육
writing-great-skills — 새 스킬 작성에 대한 참조 가이드
목적: 계획, 온보딩, 세션 간 연속성을 간소화합니다.

🔁 생산성 스킬 — 모델 호출형(1개 스킬): 백그라운드 워크플로우 지원입니다.

grilling — 다른 스킬이 사용하는 재사용 가능한 인터뷰 루프
목적: 다른 인터뷰 스타일 스킬이 호출하는 공유 빌딩 블록을 제공합니다.

4. 주요 특징

설계상 구성 가능 — 모든 스킬은 작고 독립적인 SKILL.md 파일이므로 팀은 필요한 것만 채택하고 나머지는 자유롭게 편집할 수 있습니다.
이중 호출 모델 — 스킬은 사용자 호출형(사용자가 요청)과 모델 호출형(에이전트가 자동 적용)으로 나뉘어 에이전트 동작을 세밀하게 제어할 수 있습니다.
내장 TDD 규율 — tdd 및 implement 스킬은 에이전트가 코드 작성 전 테스트를 먼저 작성하도록 유도하여 "약한 피드백 루프로 인한 깨진 코드" 실패 패턴을 직접 해결합니다.
추측 대신 구조화된 디버깅 — diagnosing-bugs 및 research는 에이전트가 즉흥적으로 처리하는 대신 가설을 세우고 출처를 인용하도록 요구합니다.
도메인 언어 기반 — CONTEXT.md 및 domain-modeling은 에이전트가 일반적인 표현 대신 프로젝트의 실제 용어를 사용하도록 유지합니다.
다중 설치 경로 — 관리되는 자동 업데이트 Claude Code 플러그인으로 작동하거나, Codex 및 기타 에이전트의 경우 npx skills를 통해 편집 가능한 파일로 작동합니다.

5. 역할별 사용 사례

일반 개발자: grill-me 및 implement를 사용하여 모호한 기능 요청을 범위가 명확하고 테스트로 보호된 구현으로 전환하고, handoff를 사용하여 세션 간 작업을 재개합니다.
프로젝트/기술 리더: improve-codebase-architecture 및 code-review를 사용하여 에이전트가 더 많은 코드를 기여함에 따라 아키텍처 및 검토 기준을 일관되게 유지합니다.
코드베이스에 AI 에이전트를 온보딩하는 팀: setup-matt-pocock-skills, CONTEXT.md 및 domain-modeling을 사용하여 에이전트에게 공유 어휘를 제공하고 첫날부터 불일치 출력을 줄입니다.

6. 시작하기

필요한 것 찾기 — 저장소에서 스킬 카탈로그와 카테고리를 탐색하거나 에이전트 세션 내에서 라우터 스킬에 요청합니다.

/ask-matt

설치/통합:

# Claude Code 플러그인(관리형, 자동 업데이트)
claude plugins install mattpocock-skills
# 또는 Claude Code 세션 내에서:
/plugin install mattpocock-skills

# Codex 및 기타 에이전트(편집 가능한 로컬 파일)
npx skills@latest add mattpocock/skills

# 저장소당 1회 설정
/setup-matt-pocock-skills

기여 — 스킬은 의도적으로 작고 적응하기 쉽습니다. 저장소를 포크하고 SKILL.md를 편집하거나 추가한 후 writing-great-skills의 지침에 따라 풀 리퀘스트를 엽니다.

7. 프로젝트 구조

skills/
├── .agents/            # 에이전트 구성 파일
├── .claude-plugin/      # Claude Code 플러그인 구성
├── .github/workflows/   # CI 워크플로우
├── docs/                # 문서
├── scripts/             # 빌드 및 유틸리티 스크립트
├── skills/
│   ├── engineering/     # 코드 중심 스킬(tdd, code-review 등)
│   └── productivity/    # 일반 워크플로우 스킬(grill-me, handoff 등)
├── AGENTS.md            # 에이전트 대상 문서
├── CLAUDE.md            # Claude 특정 설정 메모
├── CONTEXT.md           # 프로젝트 도메인 모델 및 용어
└── LICENSE              # MIT 라이선스

각 스킬은 전용 SKILL.md와 함께 자체 디렉토리에 있으며, 언제 어떻게 사용해야 하는지 설명하여 컬렉션을 쉽게 탐색하고 확장할 수 있게 합니다.

8. 관련 생태계

의존성: Claude Code(Anthropic의 코딩 에이전트 CLI) 및 Codex — 스킬이 설계된 두 가지 주요 에이전트 런타임; 설치 및 업데이트에 사용되는 skills npm 패키지/CLI(npx skills).
보완 도구: 사용자 정의 스킬/플러그인 로딩을 지원하는 모든 Markdown 기반 에이전트는 각 SKILL.md가 독립적인 명령어 세트이므로 원칙적으로 이러한 스킬 파일을 사용할 수 있습니다.

9. 라이선스

✅ 개인 또는 상업 프로젝트에서 코드를 사용, 수정, 재배포할 수 있습니다(MIT 라이선스 허용).
✅ 저장소를 포크하고 팀의 워크플로우에 맞게 개별 스킬을 조정할 수 있습니다.
❌ 재배포된 사본에서 원본 저작권 및 라이선스 고지를 제거하지 마십시오.
ℹ️ MIT 라이선스는 소프트웨어를 "있는 그대로" 보증 없이 제공합니다. 프로덕션 사용 전에 저장소의 LICENSE 파일에서 전체 약관을 검토하십시오.

10. FAQ

Q: 이 스킬을 사용하려면 Claude Code가 필요한가요?
A: 아니요 — Claude Code 사용자는 플러그인 마켓플레이스를 통해 설치할 수 있고, Codex 및 기타 에이전트 사용자는 npx skills@latest add mattpocock/skills로 편집 가능한 파일을 설치할 수 있습니다.

Q: 스킬을 최신 상태로 유지하려면 어떻게 하나요?
A: Claude Code 플러그인은 자동 업데이트됩니다. 수동으로 설치한 파일의 경우 npx skills update를 실행하십시오.

Q: 사용자 호출형과 모델 호출형 스킬의 차이점은 무엇인가요?
A: 사용자 호출형 스킬은 사용자가 명시적으로 트리거하며(예: /grill-me), 모델 호출형 스킬(예: tdd, diagnosing-bugs)은 관련 상황에서 에이전트가 자동으로 적용합니다.

Q: 직접 스킬을 작성할 수 있나요?
A: 네 — 저장소의 writing-great-skills 스킬에서 작성 지침과 규칙을 확인하십시오.

Q: 설치 후 필수 설정 단계가 있나요?
A: 네 — 저장소당 한 번 /setup-matt-pocock-skills를 실행하여 이슈 추적, 트리아지 라벨, 문서 위치를 구성하십시오.

11. 빠른 링크

저장소: https://github.com/mattpocock/skills
라이선스: https://github.com/mattpocock/skills/blob/main/LICENSE
이슈: https://github.com/mattpocock/skills/issues
토론/커뮤니티: 저장소의 이슈 및 풀 리퀘스트를 통해

12. 요약

Skills는 AI 코딩 에이전트가 규율 있는 엔지니어처럼 행동하도록 만드는 가볍고 편집 가능한 도구 키트를 팀에 제공합니다. 코드 작성 전에 계획하고, 배포 전에 테스트하며, 프로젝트의 실제 도메인 언어에 기반을 유지합니다. 이미 Claude Code 또는 Codex에 의존하고 있으며 무거운 프레임워크를 도입하지 않고 더 일관되고 검토 준비가 된 출력을 원하는 개발자와 기술 리더에게 가장 적합합니다.