agent-skills - AI 코딩 에이전트를 위한 프로덕션급 엔지니어링 스킬 모음
AI 코딩 에이전트가 스펙·테스트·보안 리뷰를 건너뛰는 문제를 해결하기 위해, 구글 클라우드 AI 디렉터 Addy Osmani가 시니어 엔지니어 수준의 워크플로우를 구조화된 스킬로 패키징한 오픈소스
개발 생명주기 전체(정의→계획→빌드→검증→리뷰→배포)에 대응하는 7개 슬래시 커맨드와 19개 스킬로 구성
/spec 무엇을 만들지 정의 : "코드 전에 스펙"
/plan 구현 방법 계획 : "소규모 아토믹 태스크로"
/build 점진적 구현 : "한 번에 하나의 슬라이스만"
/test 동작 증명 : "테스트는 증거"
/review 머지 전 품질 게이트 : "코드 헬스 개선"
/code-simplify 코드 단순화 : "영리함보다 명료함"
/ship 프로덕션 배포 : "빠를수록 더 안전함"
상황에 따라 적절한 스킬이 자동 활성화됨. 예) API 설계 시 api-and-interface-design, UI 구현 시 frontend-ui-engineering 등
Google 엔지니어링 문화의 핵심 원칙들(Hyrum's Law, Beyonce Rule, Chesterton's Fence, Shift Left 등)이 단계별 워크플로우에 직접 내장
19개 스킬 전체 목록
Define (무엇을 만들지 명확화)
idea-refine: 발산/수렴 사고를 구조화해 막연한 아이디어를 구체적 제안으로 전환
spec-driven-development: 코드 작성 전 목표·명령·구조·코드 스타일·테스트·경계를 포괄하는 PRD 작성
Plan (분해)
planning-and-task-breakdown: 스펙을 수용 기준과 의존성 순서가 있는 소규모·검증 가능한 태스크로 분해
Build (코드 작성)
incremental-implementation: 얇은 수직 슬라이스 방식으로 구현·테스트·검증·커밋, 피처 플래그와 롤백 친화적 변경 지원
test-driven-development: Red-Green-Refactor, 테스트 피라미드(80/15/5), DAMP over DRY, Beyonce Rule 적용
context-engineering: 올바른 정보를 올바른 시점에 에이전트에 제공 (rules 파일, 컨텍스트 패킹, MCP 통합)
frontend-ui-engineering: 컴포넌트 아키텍처, 디자인 시스템, 상태 관리, 반응형 디자인, WCAG 2.1 AA 접근성
api-and-interface-design: 계약 우선 설계, Hyrum's Law, One-Version Rule, 오류 시맨틱, 경계 유효성 검사
Verify (동작 증명)
browser-testing-with-devtools: Chrome DevTools MCP를 통한 실시간 런타임 데이터(DOM 검사, 콘솔 로그, 네트워크 트레이스, 성능 프로파일링)
debugging-and-error-recovery: 5단계 트리아지(재현→국소화→축소→수정→방어), stop-the-line 규칙
Review (병합 전 품질 게이트)
code-review-and-quality: 5축 리뷰, 변경 규모(~100줄), 심각도 레이블(Nit/Optional/FYI), 리뷰 속도 기준
code-simplification: Chesterton's Fence, Rule of 500, 정확한 동작 유지하며 복잡성 축소
security-and-hardening: OWASP Top 10 예방, 인증 패턴, 시크릿 관리, 의존성 감사, 3계층 경계 시스템
performance-optimization: 측정 우선 접근법, Core Web Vitals 목표, 프로파일링 워크플로우, 번들 분석
Ship (배포)
git-workflow-and-versioning: 트렁크 기반 개발, 원자적 커밋, 변경 규모(~100줄), 커밋-as-세이브포인트 패턴
ci-cd-and-automation: Shift Left, Faster is Safer, 피처 플래그, 품질 게이트 파이프라인
deprecation-and-migration: 코드-as-부채 마인드셋, 강제적/권고적 폐기 방식, 좀비 코드 제거
documentation-and-adrs: Architecture Decision Records, API 문서, 인라인 문서화 기준 ('왜'를 문서화)
shipping-and-launch: 출시 전 체크리스트, 피처 플래그 생명주기, 단계적 롤아웃, 롤백 절차, 모니터링 설정
에이전트 페르소나
타겟 리뷰를 위해 3개의 전문가 페르소나를 사전 구성
code-reviewer: 시니어 스태프 엔지니어 관점, "스태프 엔지니어가 승인할 수준인가?" 기준의 5축 코드 리뷰
test-engineer: QA 전문가 관점, 테스트 전략·커버리지 분석·Prove-It 패턴
security-auditor: 보안 엔지니어 관점, 취약점 탐지·위협 모델링·OWASP 평가
레퍼런스 체크리스트
스킬이 필요 시 참조하는 4개의 빠른 참조 자료들
testing-patterns.md: 테스트 구조, 명명, 모킹, React/API/E2E 예시, 안티패턴
security-checklist.md: 커밋 전 체크, 인증, 입력 유효성 검사, 헤더, CORS, OWASP Top 10
performance-checklist.md: Core Web Vitals 목표, 프론트엔드/백엔드 체크리스트, 측정 명령어
accessibility-checklist.md: 키보드 내비게이션, 스크린 리더, 시각 디자인, ARIA, 테스트 도구
스킬 설계 원칙
프로세스, 산문이 아님: 스킬은 에이전트가 따르는 워크플로우로, 단계·체크포인트·종료 기준을 포함하며 참고 문서가 아님
합리화 방지: 모든 스킬에 에이전트가 단계를 건너뛰기 위해 사용하는 흔한 변명("나중에 테스트 추가할게요")과 반박 논리가 내장됨
검증은 협상 불가: 모든 스킬은 증거 요건(테스트 통과, 빌드 출력, 런타임 데이터)으로 마무리되며 "잘 된 것 같다"는 충분하지 않음
점진적 공개: SKILL.md가 진입점이며, 지원 레퍼런스는 필요 시에만 로드해 토큰 사용량을 최소화
설치 방법 (지원 도구)
Claude Code (권장): /plugin marketplace add addyosmani/agent-skills 후 /plugin install agent-skills@addy-agent-skills
로컬 개발: git clone 후 claude --plugin-dir /path/to/agent-skills
Cursor: 임의의 SKILL.md를 .cursor/rules/에 복사하거나 전체 skills/ 디렉터리 참조
Windsurf: 스킬 내용을 Windsurf rules 설정에 추가
GitHub Copilot: agents/의 에이전트 정의를 Copilot 페르소나로, 스킬 내용을 .github/copilot-instructions.md에 사용
Codex 및 그 외 에이전트: 스킬은 일반 Markdown이므로 시스템 프롬프트나 인스트럭션 파일을 지원하는 모든 에이전트와 호환
