agent-skills: AI 코딩 에이전트의 개발 생명주기를 구조화하는 오픈소스 스킬 모음

AI 코딩 에이전트는 코드를 빠르게 작성할 수 있지만, 실제 개발에서는 코드 작성만으로 충분하지 않습니다. 요구사항을 명확하게 정의하고 구현 방법을 계획한 뒤 테스트와 보안 검토를 거쳐 배포하는 과정까지 함께 관리해야 합니다.

agent-skills는 이러한 개발 과정을 AI 코딩 에이전트가 따르도록 구조화한 오픈소스입니다. 구글 클라우드 AI 디렉터 Addy Osmani가 만든 이 프로젝트는 스펙 정의부터 계획, 구현, 테스트, 코드 리뷰, 보안 검토, 배포까지 개발 생명주기 전반을 7개 단계와 19개 스킬로 구성합니다.

단순히 AI에게 코드를 작성하도록 지시하는 것이 아니라, 시니어 엔지니어 수준의 개발 워크플로우를 AI 에이전트가 따를 수 있도록 프로세스 형태로 정리한 것이 핵심입니다.

반응형

AI 코딩 에이전트에 개발 프로세스가 필요한 이유

AI 코딩 에이전트를 사용하면 개발 속도를 높일 수 있지만, 빠르게 코드를 생성하는 것만으로 안정적인 소프트웨어가 만들어지는 것은 아닙니다.

요구사항을 충분히 정의하지 않은 상태에서 바로 코드를 작성하거나, 테스트를 나중으로 미루거나, 코드 리뷰와 보안 검토를 생략할 수 있기 때문입니다.

agent-skills는 이런 문제를 줄이기 위해 개발 과정을 단계별 워크플로우로 구조화합니다.

전체 과정은 다음 7개 단계로 나뉩니다.

• /spec : 무엇을 만들지 정의
• /plan : 구현 방법 계획
• /build : 점진적 구현
• /test : 동작 증명
• /review : 병합 전 품질 검토
• /code-simplify : 코드 단순화
• /ship : 프로덕션 배포

핵심은 코드를 먼저 작성하는 것이 아니라 정의와 계획, 구현, 검증, 리뷰를 거친 뒤 배포하는 흐름입니다.

7개 슬래시 커맨드로 구성된 개발 워크플로우

/spec: 코드 작성 전에 무엇을 만들지 정의

/spec은 개발을 시작하기 전에 무엇을 만들어야 하는지 명확하게 정의하는 단계입니다.

스펙에는 목표와 명령, 구조, 코드 스타일, 테스트, 경계 등이 포함됩니다.

agent-skills에서는 이를 “코드 전에 스펙”이라는 원칙으로 다룹니다.

/plan: 구현 작업을 작은 단위로 분해

스펙이 정해지면 /plan을 통해 구현 방법을 계획합니다.

큰 작업을 한 번에 처리하는 대신 수용 기준과 의존성 순서를 가진 작고 검증 가능한 태스크로 나눕니다.

이를 통해 AI 에이전트가 복잡한 기능을 한 번에 구현하는 대신 단계적으로 작업할 수 있도록 합니다.

/build: 한 번에 하나의 슬라이스만 구현

/build는 실제 코드 작성 단계입니다.

여기에서는 점진적 구현 방식을 사용합니다. 얇은 수직 슬라이스 단위로 구현하고 테스트와 검증을 진행하며 커밋합니다.

필요한 경우 피처 플래그와 롤백을 고려한 변경도 지원합니다.

핵심은 한 번에 모든 것을 구현하기보다 작게 구현하고 확인하는 것입니다.

/test: 테스트를 통해 동작을 증명

/test는 구현된 코드가 실제로 동작하는지 확인하는 단계입니다.

agent-skills는 테스트를 단순한 추가 작업이 아니라 동작을 증명하는 증거로 바라봅니다.

테스트 주도 개발에서는 Red-Green-Refactor 방식과 테스트 피라미드, DAMP over DRY, Beyonce Rule 등의 원칙을 활용합니다.

/review: 병합 전 품질 검토

/review는 코드를 병합하기 전에 품질을 확인하는 단계입니다.

코드 리뷰는 5개 축을 기준으로 진행하며, 변경 규모와 리뷰 속도, 심각도 레이블 등을 고려합니다.

이를 통해 단순히 코드가 실행되는지만 확인하는 것이 아니라 유지보수성과 품질까지 검토합니다.

/code-simplify: 복잡성을 줄이고 명료하게 만들기

/code-simplify는 기존 코드의 정확한 동작을 유지하면서 불필요한 복잡성을 줄이는 단계입니다.

여기에는 Chesterton's Fence와 Rule of 500 등의 원칙이 적용됩니다.

핵심 방향은 영리하게 작성된 코드보다 이해하기 쉬운 코드를 만드는 것입니다.

/ship: 안전하게 프로덕션에 배포

마지막 /ship은 실제 배포를 위한 단계입니다.

출시 전 체크리스트와 피처 플래그 생명주기, 단계적 롤아웃, 롤백 절차, 모니터링 설정 등을 다룹니다.

즉, 개발이 끝났다는 판단에서 멈추지 않고 실제 프로덕션 배포까지 이어지는 과정입니다.

19개 스킬로 세분화된 기능

7개 단계 아래에는 총 19개의 스킬이 구성되어 있습니다.

Define: 무엇을 만들지 명확하게 정의

idea-refine는 막연한 아이디어를 구체적인 제안으로 전환합니다.

spec-driven-development는 코드 작성 전에 목표와 명령, 구조, 코드 스타일, 테스트, 경계 등을 포함하는 PRD를 작성합니다.

Plan: 개발 작업을 작은 단위로 분해

planning-and-task-breakdown은 스펙을 수용 기준과 의존성 순서를 가진 소규모 검증 가능 태스크로 분해합니다.

Build: 실제 코드 구현

incremental-implementation은 얇은 수직 슬라이스 방식으로 구현과 테스트, 검증, 커밋을 반복합니다.

test-driven-development는 Red-Green-Refactor와 테스트 피라미드 등의 원칙을 적용합니다.

context-engineering은 AI 에이전트가 올바른 정보를 올바른 시점에 사용할 수 있도록 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단계 트리아지 방식으로 문제를 해결합니다.

Review: 코드 품질과 보안 검토

code-review-and-quality는 코드 품질을 5개 축으로 검토하고 변경 규모와 심각도 레이블 등을 활용합니다.

code-simplification은 기존 동작을 유지하면서 코드 복잡성을 줄입니다.

security-and-hardening은 OWASP Top 10 예방, 인증 패턴, 시크릿 관리, 의존성 감사, 3계층 경계 시스템을 다룹니다.

performance-optimization은 측정 우선 접근법과 Core Web Vitals 목표, 프로파일링 워크플로우, 번들 분석을 포함합니다.

Ship: 배포와 운영

git-workflow-and-versioning은 트렁크 기반 개발과 원자적 커밋, 커밋-as-세이브포인트 패턴 등을 다룹니다.

ci-cd-and-automation은 Shift Left, Faster is Safer, 피처 플래그, 품질 게이트 파이프라인을 활용합니다.

deprecation-and-migration은 코드를 부채로 바라보는 관점에서 강제적·권고적 폐기 방식과 좀비 코드 제거를 다룹니다.

documentation-and-adrs는 Architecture Decision Records와 API 문서, 인라인 문서화를 통해 코드에서 ‘무엇을 했는가’보다 ‘왜 했는가’를 기록하도록 합니다.

shipping-and-launch는 출시 전 체크리스트와 피처 플래그 생명주기, 단계적 롤아웃, 롤백 절차, 모니터링 설정을 다룹니다.

상황에 따라 필요한 스킬을 활용하는 방식

agent-skills의 특징 중 하나는 모든 스킬을 매번 동일하게 사용하는 방식이 아니라는 점입니다.

개발 상황에 따라 적절한 스킬이 자동으로 활성화됩니다.

예를 들어 API를 설계하는 상황에서는 api-and-interface-design이 사용되고, UI를 구현하는 상황에서는 frontend-ui-engineering이 활용됩니다.

이를 통해 개발자가 모든 스킬을 직접 선택하고 관리하는 부담을 줄이고, 현재 작업에 필요한 엔지니어링 원칙을 적용할 수 있도록 구성되어 있습니다.

개발 과정에 엔지니어링 원칙을 직접 적용

agent-skills에는 여러 엔지니어링 원칙이 워크플로우에 포함되어 있습니다.

대표적으로 다음과 같은 원칙을 활용합니다.

• Hyrum's Law: 시스템의 사용 가능한 모든 관찰 가능한 동작이 결국 의존 대상이 될 수 있다는 원칙
• Beyonce Rule: 테스트에서 동작을 명확하게 증명하는 접근
• Chesterton's Fence: 기존 구조를 제거하기 전에 왜 존재하는지 먼저 이해하는 원칙
• Shift Left: 테스트와 품질 검증을 개발 과정의 앞단으로 이동하는 접근

이러한 원칙을 별도의 참고 자료로만 제공하는 것이 아니라 각 개발 단계에 연결해 사용하도록 구성한 것이 특징입니다.

코드 리뷰와 테스트, 보안을 위한 전문가 페르소나

agent-skills에는 특정 검토 목적에 맞춰 사용할 수 있는 3개의 전문가 페르소나도 사전 구성되어 있습니다.

code-reviewer

시니어 스태프 엔지니어 관점에서 코드를 검토합니다.

핵심 기준은 **스태프 엔지니어가 승인할 수준인가?**입니다.

test-engineer

QA 전문가 관점에서 테스트 전략과 커버리지를 분석합니다.

테스트 전략과 함께 Prove-It 패턴을 활용합니다.

security-auditor

보안 엔지니어 관점에서 취약점 탐지와 위협 모델링, OWASP 평가를 수행합니다.

이를 통해 AI가 작성한 코드에 대해 하나의 관점이 아니라 코드 품질, 테스트, 보안이라는 서로 다른 관점에서 검토할 수 있도록 구성합니다.

검증을 선택 사항으로 두지 않는 구조

agent-skills의 설계 원칙에서 중요한 부분은 검증은 협상할 수 없는 단계라는 점입니다.

각 스킬은 단순히 작업을 완료했다고 판단하는 대신 테스트 통과, 빌드 출력, 런타임 데이터 등 확인 가능한 증거를 요구합니다.

따라서 “잘 된 것 같다”는 판단만으로 작업을 종료하지 않는 구조입니다.

또한 스킬은 일반적인 설명 문서가 아니라 에이전트가 실제로 따라야 하는 워크플로우로 설계되어 있습니다.

각 단계와 체크포인트, 종료 기준이 포함되어 있으며, 에이전트가 테스트를 나중으로 미루는 등의 방식으로 단계를 건너뛰지 않도록 흔한 합리화와 그에 대한 반박 논리도 포함합니다.

필요한 정보만 점진적으로 로드하는 방식

19개 스킬과 여러 참고 자료를 한 번에 모두 AI 에이전트에 제공하면 불필요한 정보가 많아질 수 있습니다.

agent-skills는 이를 줄이기 위해 점진적 공개 방식을 사용합니다.

진입점은 SKILL.md이며, 지원 레퍼런스는 필요한 경우에만 로드합니다.

대표적인 빠른 참조 자료로는 다음이 있습니다.

• testing-patterns.md : 테스트 구조, 명명, 모킹, React/API/E2E 예시와 안티패턴
• security-checklist.md : 커밋 전 체크, 인증, 입력 유효성 검사, 헤더, CORS, OWASP Top 10
• performance-checklist.md : Core Web Vitals 목표와 프론트엔드·백엔드 체크리스트, 측정 명령어
• accessibility-checklist.md : 키보드 내비게이션, 스크린 리더, 시각 디자인, ARIA, 테스트 도구

필요한 정보만 선택적으로 로드하기 때문에 AI 에이전트의 토큰 사용량을 줄이는 구조입니다.

다양한 AI 코딩 도구에서 활용

agent-skills는 특정 AI 코딩 에이전트 하나에만 한정되지 않습니다.

Claude Code

권장 도구로 소개되며 다음 방식으로 설치할 수 있습니다.

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

로컬 개발 환경에서는 저장소를 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으로 작성되어 있기 때문에 시스템 프롬프트나 인스트럭션 파일을 지원하는 다른 에이전트에서도 활용할 수 있습니다.

728x90

agent-skills는 AI 코딩 에이전트가 코드를 빠르게 작성하는 것에서 그치지 않고, 실제 소프트웨어 개발에 필요한 프로세스를 따르도록 구성한 오픈소스 스킬 모음입니다.

/spec에서 무엇을 만들지 정의하고, /plan에서 작업을 나누고, /build에서 점진적으로 구현한 뒤 /test와 /review를 통해 검증합니다. 이후 코드 단순화와 보안·성능 검토를 거쳐 /ship을 통해 배포하는 구조입니다.

총 19개의 스킬은 아이디어 구체화부터 API 설계, 프론트엔드 구현, 테스트, 디버깅, 코드 리뷰, 보안, 성능, CI/CD, 문서화, 마이그레이션, 배포까지 개발 생명주기 전반을 다룹니다.

특히 테스트 통과나 빌드 출력, 런타임 데이터처럼 확인 가능한 증거를 요구하고, 필요한 레퍼런스만 점진적으로 로드하도록 설계한 점은 AI 코딩 에이전트를 개발 프로세스 안에서 활용하려는 접근을 보여줍니다.

결국 agent-skills가 제시하는 핵심은 단순합니다. AI에게 코드를 작성하게 하는 것과 AI가 엔지니어링 프로세스를 따라 코드를 개발하게 하는 것은 다르다는 것입니다. 스펙 정의부터 검증과 배포까지 개발 과정 자체를 구조화함으로써 AI 코딩 에이전트를 보다 체계적인 개발 워크플로우 안에서 활용할 수 있도록 한 것이 agent-skills의 핵심입니다.

300x250

https://github.com/addyosmani/agent-skills

GitHub - addyosmani/agent-skills: Production-grade engineering skills for AI coding agents.