/spec → /plan → /build → /test → /review → /code-simplify → /ship이라는 개발 생애주기 커맨드 8개가 입구이고, Claude Code뿐 아니라 Gemini CLI·Cursor·Windsurf·Copilot 등 9개 환경 설치 가이드가 함께 옵니다. (저장소: addyosmani/agent-skills · Markdown+셸 · TrendShift 17위 · 오픈소스)이 레포가 무엇을 하는 물건인가.
스킬 하나하나가 "단계 + 검증 게이트 + 합리화 방지 표"로 짜인 구조화된 워크플로입니다. 예컨대 TDD 스킬엔 Red-Green-Refactor와 테스트 피라미드(80/15/5)가, 코드 리뷰 스킬엔 ~100줄 변경 사이징과 Nit/Optional/FYI 심각도 라벨이 들어 있습니다 — 구글류 엔지니어링 문화의 정수를 에이전트가 따르게 만든 것.
구성은 3층입니다. 커맨드 8개(생애주기 진입점) → 스킬 24개(실제 워크플로, 작업 내용에 따라 자동 발동) → 레퍼런스 체크리스트(보안·접근성·성능·테스트 패턴). 여기에 전문 페르소나 에이전트 4종(code-reviewer·security-auditor·test-engineer·web-performance-auditor)과 훅 2종이 곁들여집니다.
트렌딩 이유 · 경쟁 대비 장점.
스킬 모음 레포는 흔해졌지만, 이 레포의 차별점은 셋입니다. 첫째, 저자의 권위 — 웹 성능·엔지니어링 문화 분야에서 가장 많이 읽히는 저자 중 하나가 직접 만들고 다듬습니다. 둘째, "무엇을 해라"가 아니라 "어떻게 빠져나가지 못하게 할까"를 설계했다는 점 — 스킬마다 들어 있는 anti-rationalization(합리화 방지) 표는 에이전트가 "이번엔 테스트를 건너뛰어도 되겠지"라고 둘러대는 패턴을 미리 차단합니다. 셋째, 9개 환경 동시 지원 — 특정 CLI 종속이 없습니다.
| 비교 항목 | 흔한 스킬 모음 | addyosmani/agent-skills |
|---|---|---|
| 구조 | 팁 나열형 마크다운 | 단계 + 검증 게이트 + 합리화 방지 표 |
| 발동 | 사용자가 직접 지정 | 커맨드 7개 + 작업 맥락 자동 발동 |
| 근거 | 개인 취향 | Hyrum's Law·Chesterton's Fence 등 검증된 원칙 인용 |
| 이식성 | Claude Code 전용 多 | Claude·Gemini·Cursor·Windsurf·Copilot·Kiro·OpenCode·Codex·Antigravity CLI |
"시간이 없으니 테스트는 나중에", "간단한 변경이라 리뷰 불필요" — 사람 주니어가 하는 실수를 에이전트도 똑같이 합니다. 지시만으론 안 막힙니다.
각 스킬의 anti-rationalization 표는 "이런 핑계가 나오면 이렇게 응답하라"를 명시합니다. doubt-driven-development 스킬은 한발 더 나가 — 모든 비자명한 결정을 CLAIM→EXTRACT→DOUBT→RECONCILE 절차로 신선한 컨텍스트의 적대적 리뷰어에게 검증시킵니다.
마크다운이 본체, 셸과 JS는 접착제.
| 레이어 | 구성 | 역할 |
|---|---|---|
| 스킬 | skills/ 24개 SKILL.md | 본체 — 생애주기 23개 + using-agent-skills 메타 스킬(어떤 스킬을 쓸지 매핑). |
| 커맨드 | .claude/commands/ 8개 + .gemini/commands/ 8개 | 같은 커맨드를 Claude는 .md로, Gemini는 .toml로 — 포맷별 이중 유지. |
| 에이전트 | agents/ 4종 | code-reviewer·security-auditor·test-engineer·web-performance-auditor 페르소나 정의. |
| 훅 | hooks/ (셸 스크립트) | sdd-cache(스펙 캐싱)·simplify-ignore(단순화 제외 목록)·session-start. |
| 레퍼런스 | references/ 5개 체크리스트 | 보안·접근성·성능·테스트·오케스트레이션 — 스킬이 참조하는 부록. |
| 품질 | scripts/validate-skills.js + CI | 스킬 형식 검증 + 플러그인 설치 테스트 워크플로. |
| 배포 | .claude-plugin/ 마켓플레이스 | /plugin marketplace add addyosmani/agent-skills 한 줄 설치. |
/build 한 번에 무엇이 움직이는가.
대표 흐름 — "기능 하나 만들어줘"가 들어오면: ① 요구가 모호하면 interview-me 스킬이 "한 번에 한 질문" 인터뷰로 진짜 요구를 캐냅니다(~95% 확신까지). ② /spec이 목표·구조·테스트·경계를 PRD로 박제하고, ③ /plan이 수용 기준 딸린 원자적 작업으로 쪼갭니다. ④ /build는 얇은 수직 슬라이스로 — 구현→테스트→검증→커밋을 반복하고, ⑤ /review는 5축 리뷰와 변경 사이징(~100줄)을 강제합니다. 각 단계의 게이트를 통과해야 다음으로 — 에이전트가 "한 방에 다 짜기"로 폭주하는 걸 구조적으로 막는 설계입니다.
주방에 비유하면, 보통의 프롬프트는 "맛있게 만들어줘"라고 말하는 손님이고, 이 스킬 팩은 미슐랭 주방의 운영 매뉴얼입니다 — 검수 스테이션(게이트)이 있고, "바쁘니까 손 안 씻어도 되겠지" 같은 핑계 목록(합리화 방지 표)에 반박이 미리 적혀 있는.
어떤 폴더가 무슨 일을 하나.
| 위치 | 주목할 점 |
|---|---|
docs/skill-anatomy.md | 스킬을 어떻게 짜야 하는지의 해부도 — 내 스킬 만들 때 첫 참고서. |
skills/doubt-driven-development/ | 이 팩의 사상이 가장 진하게 담긴 스킬 — "확신에 찬 답 ≠ 맞는 답". |
hooks/sdd-cache-*.sh | 스펙 주도 개발의 스펙을 훅으로 캐싱 — 마크다운+셸 조합의 실전 예. |
.github/workflows/test-plugin-install.yml | "플러그인이 실제로 설치되는가"를 CI로 검증 — 스킬 레포의 품질 관리. |
이 레포에서 배울 만한 것 + 어디를 보면 되는지.
지시("테스트를 써라")가 아니라 예상 회피("간단해서 테스트 불필요" → 반박)를 적는 방식은 에이전트뿐 아니라 팀 문서·코드리뷰 가이드에도 이식할 수 있는 테크닉입니다. 아무 SKILL.md나 열어 표를 비교해 보세요.
Hyrum's Law(관측 가능한 모든 동작은 누군가 의존한다), Chesterton's Fence(이유 모르는 울타리는 허물지 마라), Rule of 500, DAMP over DRY, Beyoncé Rule — 스킬들을 읽는 것만으로 시니어들의 공용어를 익히게 됩니다.
.claude(md)·.gemini(toml)·docs의 Cursor/Windsurf/Copilot/Kiro 가이드 — 포맷별 이중 유지의 비용과 전략을 한 레포에서 비교할 수 있습니다.
CLAIM→EXTRACT→DOUBT→RECONCILE→STOP — 긴 세션에서 가정이 슬그머니 "사실"이 되는 문제를, 신선한 컨텍스트의 반증 지향 리뷰어로 끊는 절차. 고위험 작업의 워크플로 설계에 그대로 응용 가능합니다.
돌리려면 무엇이 필요한가.
| 항목 | 요구사항 |
|---|---|
| 권장 환경 | Claude Code — /plugin marketplace add addyosmani/agent-skills 두 줄 설치. |
| 대안 환경 | Gemini CLI(skills install)·Cursor(.cursor/rules)·Windsurf·OpenCode·Copilot·Kiro·Codex·Antigravity CLI — docs/ 가이드 참조. |
| SSH 주의 | 마켓플레이스가 SSH 클론을 시도 — 키가 없으면 HTTPS URL로 추가. |
| 본질 | 스킬은 평범한 마크다운 — 시스템 프롬프트를 받는 어떤 에이전트에도 이식 가능. |
난이도별로 손에 익히는 단계.
플러그인 설치 후 작은 기능 하나를 /spec→/plan→/build→/test→/review→/ship으로 끝까지 만들어 봅니다. 평소(스킬 없이)와 결과물·과정이 어떻게 다른지 기록하세요.
모호한 아이디어("뭔가 가계부 같은 거")를 던지고 "interview me"를 발동시켜, 한-질문-씩 인터뷰가 요구를 어디까지 구체화하는지 경험합니다.
내가 자주 시키는 작업(예: 엑셀 보고서 생성)에 대해 "에이전트가 댈 만한 핑계 5개 + 반박"을 표로 만들어 기존 스킬에 합쳐 봅니다 — skill-anatomy.md를 교본으로.
이 레포의 구조(.claude-plugin + skills/ + validate-skills.js)를 본떠 내 도메인 스킬 3개짜리 마켓플레이스 레포를 만들고 실제 설치까지 검증합니다.
한 주씩 따라가는 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | 설치 + 생애주기 커맨드 체험 | README · 실습 1 |
| 2주차 | 스킬 해부학 — 좋은 스킬의 구조 | docs/skill-anatomy.md · using-agent-skills |
| 3주차 | 인용된 엔지니어링 원칙 원전 읽기 | Software Engineering at Google · Hyrum's Law |
| 4주차 | 자기검증 패턴 — doubt-driven 정독 | 해당 SKILL.md · 실습 3 |
| 5주차 | 내 스킬 팩 설계·배포 | 실습 4 · Claude Code 플러그인 문서 |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| 스킬 | 에이전트용 구조화 절차서 — 발동 조건·단계·검증 게이트 포함. |
| 합리화 방지 표 | 에이전트가 절차를 건너뛰며 댈 핑계와 그 반박을 미리 적은 표. |
| 검증 게이트 | 다음 단계로 못 넘어가게 막는 통과 조건. |
| Hyrum's Law | API의 관측 가능한 모든 동작은 결국 누군가 의존하게 된다는 법칙. |
| Chesterton's Fence | 존재 이유를 모르는 코드는 이유를 알기 전까지 지우지 말라는 원칙. |
| DAMP over DRY | 테스트 코드는 중복 제거(DRY)보다 서술적 명확함(DAMP)을 우선. |
| 테스트 피라미드 80/15/5 | 단위/통합/E2E 테스트의 권장 비율. |
| 수직 슬라이스 | UI부터 저장까지 얇게 관통하는 구현 단위 — 한 층씩 다 만들기의 반대. |
| doubt-driven | 비자명한 결정마다 반증 지향 리뷰를 끼워 넣는 작업 자세. |
| PRD | Product Requirements Document — 만들 것의 목표·범위·기준 명세. |