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/ 디렉터리 참조
• Gemini CLI: gemini skills install https://github.com/addyosmani/agent-skills.git
• Windsurf: 스킬 내용을 Windsurf rules 설정에 추가
• GitHub Copilot: agents/의 에이전트 정의를 Copilot 페르소나로, 스킬 내용을 .github/copilot-instructions.md에 사용
• Codex 및 그 외 에이전트: 스킬은 일반 Markdown이므로 시스템 프롬프트나 인스트럭션 파일을 지원하는 모든 에이전트와 호환