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

프로토타입을 넘어 프로덕션 품질로

AI 코딩 에이전트가 프로토타입 수준을 넘어 프로덕션 품질의 코드를 작성하려면 시니어 엔지니어의 워크플로우를 체계적으로 학습해야 한다. Google Chrome 팀의 Addy Osmani가 공개한 agent-skills는 스펙 작성부터 배포까지 전체 소프트웨어 개발 라이프사이클을 20개의 마크다운 기반 스킬로 정의한 오픈소스 프로젝트이다.

agent-skills는 AI 코딩 에이전트에 프로덕션급 엔지니어링 판단력을 부여하는 스킬 모음으로, Google 엔지니어링 문화에서 축적된 모범 사례를 마크다운으로 인코딩한다. 스펙 작성 → 코드 작성 → 테스트 → 머지 → 최적화의 순서를 강제하며, "나중에 테스트 추가할게"와 같은 에이전트의 흔한 회피 패턴을 문서화하고 반박 근거를 제공한다. 검증은 비타협 사항으로, 테스트 통과·빌드 출력·런타임 데이터 등 증거 기반 확인을 요구한다.

정의부터 운영까지 이어지는 스킬 체계

agent-skills는 소프트웨어 개발의 전체 단계를 카테고리로 분류한다.

⤢✕

Define(정의) 카테고리에는 아이디어 구체화 및 요구사항 도출을 다루는 idea-refine, SPECIFY→PLAN→TASKS→IMPLEMENT 4단계 스펙 주도 개발을 다루는 spec-driven-development가 있다.

Plan(계획) 카테고리에는 작업 분해 및 검증 가능한 단위 태스크 생성을 다루는 planning-and-task-breakdown이 있다.

Build(구현) 카테고리에는 점진적 구현과 중간 검증을 다루는 incremental-implementation, 컨텍스트 엔지니어링 및 프롬프트 최적화를 다루는 context-engineering, 소스 기반 개발을 다루는 source-driven-development, 프론트엔드 UI 엔지니어링을 다루는 frontend-ui-engineering, 테스트 주도 개발을 다루는 test-driven-development, API 및 인터페이스 설계를 다루는 api-and-interface-design이 있다.

Verify(검증) 카테고리에는 브라우저 DevTools 기반 테스트를 다루는 browser-testing-with-devtools, 디버깅 및 오류 복구를 다루는 debugging-and-error-recovery가 있다.

Review(리뷰) 카테고리에는 코드 리뷰 및 품질 관리를 다루는 code-review-and-quality, 코드 단순화를 다루는 code-simplification, 보안 강화를 다루는 security-and-hardening, 성능 최적화를 다루는 performance-optimization이 있다.

Ship(배포) 카테고리에는 Git 워크플로우 및 버전 관리를 다루는 git-workflow-and-versioning, CI/CD 및 자동화를 다루는 ci-cd-and-automation, 디프리케이션 및 마이그레이션을 다루는 deprecation-and-migration, 문서화 및 ADR(Architecture Decision Records)을 다루는 documentation-and-adrs, 출시 및 런치를 다루는 shipping-and-launch가 있다.

코드 전에 스펙이라는 철학

agent-skills의 핵심 철학은 "코드 전에 스펙"이다.

⤢✕

스펙은 코드 작성 전에 명확성을 강제하는 도구이며, SPEC.md·tasks/plan.md·tasks/todo.md 등 작업 산출물을 생성한다. 각 단계에서 인간 리뷰 게이트를 삽입해 자율 실행의 위험을 통제하며, 에이전트가 "이해했습니다"라고 말하는 것과 실제로 이해한 것의 차이를 좁힌다.

슬래시 명령어로 즉시 실행하기

agent-skills는 슬래시 명령어를 제공하여 워크플로우를 즉시 실행할 수 있다.

명령어	기능	산출물
/spec	요구사항 명세 작성	SPEC.md
/plan	작업 계획 수립	tasks/plan.md
/build	점진적 구현 실행	코드 파일
/test	테스트 작성 및 실행	테스트 파일
/review	코드 리뷰 수행	리뷰 코멘트
/code-simplify	코드 단순화	리팩터링 코드
/ship	출시 준비 및 실행	릴리스 산출물

Google 엔지니어링 문화가 스며든 원칙들

agent-skills에는 Google 내부에서 검증된 엔지니어링 원칙이 반영되어 있다. Hyrum's Law는 API의 모든 관찰 가능한 동작이 누군가에게 의존 대상이 된다는 원칙이고, Beyonce Rule은 "네가 좋아했으면 테스트를 걸었어야지 — 테스트 없으면 보호 없음"이라는 원칙이다. 단위 테스트가 통합 테스트·E2E 테스트보다 많아야 한다는 테스트 피라미드 비율, 작은 변경이 빠른 리뷰와 안전한 배포를 보장한다는 변경 크기 규범, 장기 브랜치를 지양하고 메인 브랜치 중심으로 개발하는 트렁크 기반 개발도 포함된다.

설치와 호환 도구

Claude Code, Cursor, Antigravity 등 마크다운 시스템 프롬프트를 지원하는 모든 에이전트와 호환되며, 설치 명령어는 npx skills add addyosmani/agent-skills다. 스킬 파일은 순수 마크다운이므로 커스터마이징이 가능하고, CLAUDE.md·AGENTS.md 등 에이전트 설정 파일과 연동된다.

빠르게 만드는 것에서 올바르게 만드는 것으로

agent-skills는 AI 코딩 에이전트의 출력 품질을 프로토타입 수준에서 프로덕션 수준으로 끌어올리기 위한 체계적인 엔지니어링 스킬 모음이다. Google 엔지니어링 문화의 핵심 원칙을 마크다운으로 인코딩하여 모든 AI 에이전트가 동일한 품질 기준을 적용할 수 있게 한다. 스펙 주도 개발과 증거 기반 검증이라는 두 축은 에이전트가 "빠르게 코드를 생성하는 것"을 넘어 "올바르게 소프트웨어를 만드는 것"으로 전환하는 데 필수적인 가이드라인을 제공한다.