addyosmani/agent-skills — 프로덕션 수준의 엔지니어링 스킬을 AI 코딩 에이전트에게

본문

AI 코딩 에이전트는 기본적으로 가장 짧은 경로를 택하기 때문에 스펙 작성, 테스트, 보안 리뷰 같은 필수 절차를 건너뛰기 쉽습니다. Addy Osmani가 만든 agent-skills는 이러한 문제를 해결하기 위해 시니어 엔지니어가 실무에서 쓰는 워크플로우, 품질 게이트, 모범 사례를 구조화된 '스킬(Skill)'로 패키징한 저장소입니다. GitHub에 오르며 656점의 커뮤니티 점수를 기록했습니다.

개발 생애주기를 따라가는 9개의 슬래시 커맨드

이 패키지는 DEFINE→PLAN→BUILD→VERIFY→REVIEW→SHIP으로 이어지는 개발 생애주기에 매핑되는 9개의 슬래시 커맨드를 제공합니다. '/spec'은 코드 이전에 스펙을 작성하고, '/plan'은 작고 원자적인 작업으로 분해하며, '/build'는 한 번에 하나의 수직 슬라이스씩 구현하고, '/test'는 테스트를 증거로 삼습니다. 여기에 품질 기준을 한 번 정해 전체에 적용하는 '/constraints', 머지 전 리뷰를 위한 '/review', 측정 우선의 웹 성능 감사 '/webperf', 명확함을 우선하는 '/code-simplify', 더 빠른 배포가 더 안전하다는 철학의 '/ship'이 포함됩니다. 특히 '/build'는 스펙이 존재하면 계획을 자동 생성하고 승인 한 번으로 모든 작업을 자율적으로 수행하되, 각 작업은 여전히 테스트 주도로 개별 커밋되며 실패나 위험한 단계에서는 일시 정지합니다.

25개 스킬의 구성과 자동 활성화

스킬은 작업 맥락에 따라 자동으로 활성화되기도 합니다. API를 설계하면 api-and-interface-design이, UI를 만들면 frontend-ui-engineering이 트리거되는 식입니다. 전체 25개 스킬은 24개의 생애주기 스킬과 작업을 적절한 스킬에 연결하는 메타 스킬 using-agent-skills로 구성됩니다. 주요 스킬로는 사용자가 실제로 원하는 것을 한 번에 한 질문씩 추출하는 interview-me, PRD 작성을 강제하는 spec-driven-development, Red-Green-Refactor와 테스트 피라미드(80/15/5)를 적용하는 test-driven-development, 모든 비자명한 결정을 적대적으로 재검토하는 doubt-driven-development, OWASP Top 10과 시크릿 관리를 다루는 security-and-hardening, 코드를 부채로 취급하는 deprecation-and-migration 등이 있습니다. 여기에 코드 리뷰어, 테스트 엔지니어, 보안 감사자, 웹 성능 감사자라는 4개의 전문가 페르소나와 정의된 완료 기준, 테스트 패턴, 보안·성능·접근성·관측가능성 체크리스트 등 7개의 참조 자료가 함께 제공됩니다.

스킬의 구조와 설계 철학

모든 스킬은 일관된 구조를 따릅니다. SKILL.md는 프론트매터와 함께 개요, 사용 시점, 단계별 프로세스, 합리화(Rationalizations), 위험 신호(Red Flags), 검증(Verification) 섹션을 포함합니다. 설계상 핵심은 네 가지입니다. 첫째, 산문이 아닌 프로세스로서 단계·체크포인트·종료 기준을 갖춥니다. 둘째, '나중에 테스트를 추가하겠다' 같은 에이전트의 흔한 핑계와 그 반박을 표로 정리한 반-합리화 장치를 둡니다. 셋째, '맞아 보인다'는 것으로는 부족하며 테스트 통과, 빌드 출력, 런타임 데이터 같은 증거 요구사항으로 모든 스킬을 마무리합니다. 넷째, SKILL.md가 진입점이고 보조 참조는 필요할 때만 로드하는 점진적 공개로 토큰 사용을 최소화합니다.

Google 엔지니어링 문화와 생태계 통합

스킬에는 'Software Engineering at Google'과 Google 엔지니어링 프랙티스 가이드의 개념이 녹아 있습니다. API 설계의 Hyrum's Law, 테스트의 Beyonce Rule과 테스트 피라미드, 코드 리뷰의 변경 크기(~100라인)와 리뷰 속도 규범, 단순화의 Chesterton's Fence, Git 워크플로우의 trunk-based development, CI/CD의 Shift Left와 피처 플래그 등이 추상적 원칙이 아니라 에이전트가 따라야 할 단계별 워크플로우로 직접 내장됩니다. 설치는 'npx skills add addyosmani/agent-skills' 한 줄로 70개 이상의 에이전트에 적용 가능하며, Claude Code는 플러그인 마켓플레이스, Codex는 네이티브 플러그인, Gemini CLI는 네이티브 스킬, Cursor는 .cursor/skills/ 디렉터리 등 각 도구의 네이티브 발견 규칙에 맞춘 어댑터를 제공합니다. 스킬 자체는 평범한 Markdown이라 시스템 프롬프트나 지시 파일을 받는 어떤 에이전트와도 호환되며, 라이선스는 MIT입니다.

원문: GitHub / 번역·요약: Trawling