agent-skills - AI 코딩 에이전트를 위한 프로덕션급 엔지니어링 스킬 모음

xguru · 2026-04-08T09:31:02+09:00

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이므로 시스템 프롬프트나 인스트럭션 파일을 지원하는 모든 에이전트와 호환

(github.com/addyosmani)

41P by xguru 10시간전 | ★ favorite | 댓글 5개

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이므로 시스템 프롬프트나 인스트럭션 파일을 지원하는 모든 에이전트와 호환