에이전트가 '잘' 하는 법, 25개 스킬로 만든 생산성

에이전트가 알아서 '잘' 하는 법, Agent Skills가 만든 생산성 흐름

출처: addyosmani.com

AI 코딩 에이전트가 코드를 대신 써주긴 하는데, 계속 "이 정도면 됐지" 수준에 머무는 경험 있으시죠? 구글에서 웹 성능 전문가로 유명한 Addy Osmani가 그 문제를 정면으로 다룬 오픈소스를 내놨어요. 바로 agent-skills라는 레포인데, 2026년 9월 18일 기준 0.6.10 버전까지 릴리스되며 별 9.6만 개를 넘겼어요.

이 프로젝트가 어떤 설계 아이디어로 에이전트의 작업 품질을 끌어올리는지, 어떻게 직접 적용할 수 있는지 하나씩 짚어 볼게요.

25개 스킬이 나누어 가진 건 '일의 순서'예요

agent-skills는 소프트웨어를 만드는 전 과정을 여섯 단계로 나눠요. 바로 DEFINE→PLAN→BUILD→VERIFY→REVIEW→SHIP 순서예요. 각 단계마다 스킬이라는 잘 짜인 워크플로우가 배정되어 있고, 총 25개 스킬이 들어 있어요.

24개의 라이프사이클 스킬에 더해, 어떤 스킬을 쓸지 판단을 도와주는 using-agent-skills 메타 스킬이 하나 붙어 있는 구조죠.

  DEFINE          PLAN           BUILD          VERIFY         REVIEW          SHIP
┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐
│ Idea │ ---- │ Spec │ ---- │ Code │ ---- │ Test │ ---- │  QA  │ ---- │  Go  │
│Refine│      │  PRD │      │ Impl │      │Debug │      │ Gate │      │ Live │
└──────┘      └──────┘      └──────┘      └──────┘      └──────┘      └──────┘
 /spec          /plan          /build        /test         /review       /ship

각 단계를 담당하는 대표 스킬만 보면 이런 구성이에요. 요구사항을 뽑아내는 interview-me, 코드 짜기 전 PRD를 쓰게 하는 spec-driven-development, 테스트를 먼저 작성하도록 강제하는 test-driven-development, 머지 전 5축 리뷰를 도는 code-review-and-quality, 배포 준비를 점검하는 shipping-and-launch 같은 것들이죠. 에이전트는 시작할 때 using-agent-skills로 지금 일에 어떤 스킬이 맞는지 판단하고, 해당 스킬의 절차를 따르게 돼요.

슬래시 명령으로 라이프사이클을 바로 연결해요

이 스킬들은 슬래시 명령과 묶여 있어요. 레포에 등록된 명령은 9개예요.

여기서 눈여겨볼 명령이 /build auto예요. spec이 준비되면 계획을 자동 생성하고 모든 태스크를 한 번의 승인으로 구현하는 모드인데, 인간이 태스크 사이에 개입하는 것을 없애는 대신 검증은 그대로 유지해요. 모든 태스크가 여전히 테스트 주도로 개별 커밋되고, 실패하거나 위험한 단계에서는 멈추는 방식이에요.

스킬 하나하나가 '에이전트용 매뉴얼'로 설계돼 있어요

이 프로젝트의 핵심은 스킬의 구성 방식이에요. 예를 들어 test-driven-development 스킬의 SKILL.md는 레드-그린-리팩터 절차, 테스트 피라미드의 80/15/5 비율, 테스트 크기, DAMP over DRY 원칙 같은 내용을 담고 있어요. 그런데 단순한 참고 문서가 아니라 워크플로우 자체로 설계되어 있다는 점이 달라요.

README에 나온 스킬의 해부도는 이런 구조예요.

┌─────────────────────────────────────────────────┐
│  SKILL.md                                       │
│  ┌─ Frontmatter ─────────────────────────────┐  │
│  │ name: lowercase-hyphen-name               │  │
│  │ description: Guides agents through [task].│  │
│  │              Use when…                    │  │
│  └───────────────────────────────────────────┘  │
│  Overview         → What this skill does        │
│  When to Use      → Triggering conditions       │
│  Process          → Step-by-step workflow       │
│  Rationalizations → Excuses + rebuttals         │
│  Red Flags        → Signs something's wrong     │
│  Verification     → Evidence requirements       │
└─────────────────────────────────────────────────┘

흥미로운 부분은 Process 다음에 Rationalizations 섹션이 있는 거예요. 에이전트가 단계를 건너뛰는 흔한 변명들("테스트는 나중에 추가할게" 같은)을 모아서 반박 논거를 정리해 둔 표예요.

또 Red Flags로 뭔가 잘못됐을 때의 신호를, Verification으로 통과 기준을 명시해서 "그럴듯해 보인다"는 에이전트의 판단을 증거로 바꾸게 해요. 이렇게 설계 덕분에 에이전트가 절차를 대충 흉내 내는 대신 검증 가능한 단계를 실제로 밟게 돼요.

설치부터 적용까지, 70여 개 에이전트를 지원해요

가장 간단한 설치 방법은 오픈 소스 skills CLI를 쓰는 거예요. Claude Code, Cursor, Codex, Copilot, Cline 등 70개 이상의 에이전트에 한 번에 설치할 수 있어요.

npx skills add addyosmani/agent-skills            # 25개 스킬 전부 설치
npx skills add addyosmani/agent-skills --list     # 설치 전에 목록만 확인
npx skills add addyosmani/agent-skills --skill code-review-and-quality   # 개별 스킬만

Claude Code를 쓰시면 마켓플레이스 형태로 /plugin 명령으로 설치할 수도 있어요. Cursor는 .cursor/skills/에 동기화하고, Gemini CLI는 gemini skills install로, Codex는 네이티브 플러그인으로 각각 받을 수 있어요. 스킬이 결국 마크다운이라 시스템 프롬프트나 지침 파일을 받는 어떤 에이전트에서도 동작한다는 점도 덧붙여요.

에이전트 페르소나로 리뷰 관점까지 정렬해요

code-reviewer, test-engineer, security-auditor처럼 특정 역할에 특화된 에이전트 페르소나도 제공돼요. code-reviewer는 시니어 스태프 엔지니어의 관점으로 "스태프 엔지니어가 승인할까?"라는 기준으로 리뷰하고, security-auditor는 취약점 탐지와 위협 모델링, OWASP 점검에 집중해요. 이런 페르소나는 스킬이 강제하는 품질 기준과 같은 어휘를 쓰도록 정렬되어 있어서, 같은 결함이 어느 진입점에서 리뷰하든 같은 심각도로 분류되게 해요.

오픈소스나 내부 팀 저장소에서 이 레포를 가져와 쓰고 싶으시다면, MIT 라이선스라서 자유롭게 활용할 수 있고 이슈와 PR을 통한 기여도 활발해요. 기본 9개 슬래시 명령과 25개 스킬보다 더 가볍게 시작하고 싶을 땐 핵심 스킬 몇 개만 고르는 것도 좋은 방법이에요.

참고 링크

• addyosmani/agent-skills 저장소
• skills CLI (vercel-labs)
• Online skills catalog