AI 코딩 에이전트를 명세부터 배포까지 단계대로 이끄는 방법

addyosmani/agent-skills의 Agent Skills를 적용하면 AI 코딩 에이전트가 코드를 쓰기 전에 명세부터 작성하고, 작업을 작은 단위로 나눈 뒤 한 조각씩 구현하면서 테스트로 동작을 입증하고 리뷰를 거쳐 배포까지 마친다. 개발자는 뒤섞인 파일 수정본 대신 요구사항 문서, 검증을 통과한 개별 커밋, 병합 전 코드 리뷰를 돌려받는다.

요청이 모호하거나 변경 규모가 큰데도 에이전트가 명세와 테스트, 리뷰를 건너뛰고 파일부터 고치기 시작할 때 개발자가 이 스킬을 꺼내 든다. 요청 문장만으로는 에이전트가 목표와 작업 경계를 먼저 적고 검증 뒤에 완료를 보고하도록 묶어 두기 어렵기 때문이다.

에이전트는 코드를 짜기 전에 명세부터 작성하고, 테스트와 리뷰를 끝내기 전에는 작업을 마쳤다고 보고하지 않는다.

없을 때와 있을 때

이 스킬이 없으면 기능 추가를 요청받은 에이전트는 곧장 코드 수정부터 시작해 여러 파일을 한 번에 건드리기 쉽다. 문서화된 명세도, 테스트도, 리뷰도 없이 작업이 끝났다고 보고해 버리며, 요청만으로는 목표, 명령어, 구조, 코드 스타일, 테스트, 작업 경계를 먼저 적게 만들지 못한다.

이 스킬을 쓰면 코드를 작성하기 전에 /spec으로 요구사항 문서부터 만든다. 이어서 /plan이 명세를 확인 가능한 작은 작업들로 나누고 완료 기준과 의존성 기반 순서를 붙이며, /build가 한 번에 한 조각씩 구현하고 /test가 그 조각이 동작한다는 증거로 테스트를 돌린다. 병합 전에는 /review로 변경 사항을 점검하고 /ship으로 프로덕션까지 내보내며, 슬래시 명령어가 필요하지 않은 상황에서도 API를 설계하면 api-and-interface-design을, 사용자 인터페이스를 만들면 frontend-ui-engineering을 불러와 적용한다.

에이전트가 경로를 결정하는 방식

요청이 들어올 때마다 25개 스킬이 전부 실행되지는 않는다. 24개는 개발 수명 주기를 맡고, 나머지 하나인 using-agent-skills가 세션을 시작할 때나 에이전트가 어떤 스킬을 적용할지 정해야 할 때 들어온 작업을 하나의 워크플로우에 연결하고 공통 운영 규칙을 정한다. 각 스킬은 단계별 절차와 반드시 통과해야 하는 검증을 밟게 하고, 단계를 건너뛰려는 흔한 변명을 표로 막는다.

작업을 연결한 뒤에는 요청 상태에 따라 경로가 갈린다. 요청이 구체적이지 않으면 interview-me가 한 번에 질문 하나씩 던져 사용자가 실제로 원하는 바를 끌어내고, 끝없이 묻는 대신 확신도가 95%쯤에 닿으면 멈춘다. 아이디어가 거친 구상 수준이라면 idea-refine이 선택지를 살펴본 뒤 구체적인 제안으로 좁혀 준다. 명문화된 품질 기준이 없거나 에이전트가 아무도 읽지 못할 만큼 결과물을 쏟아낸다면 constraint-driven-development가 작동해 사용자와 인터뷰로 기준을 정하고 합리적인 기본 임계값으로 CONSTRAINTS.md를 작성한다. 이어서 비용에 맞춰 각 검증을 배치하고, 통과한 것처럼 보이려고 검증을 끄거나 테스트를 건너뛰는 에이전트를 잡아낸다.

/build를 실행해도 모든 파일을 한꺼번에 덮어쓰지는 않는다. incremental-implementation이 끝단까지 이어지는 작은 조각 하나를 구현한 뒤 테스트하고 검증해 커밋하며, 이때 피처 플래그, 안전한 기본값, 되돌릴 수 있는 변경을 쓴다.

/build auto는 승인 방식이 다른 갈래다. 계획을 한 번만 승인하면 작업 사이에 사람이 개입하는 단계를 없애고 끝까지 진행하지만, 검증까지 생략하지는 않는다. 모든 작업은 여전히 테스트 주도로 진행해 각각 따로 커밋하고, 작업이 실패하거나 단계가 위험하면 실행을 잠시 멈춘다.

적용 시작점도 상황에 따라 나뉜다. 새 프로젝트는 첫날부터 전체 수명 주기를 밟고, 기존 코드베이스는 먼저 검증하는 점진적 경로를 택한다. 슬래시 명령어는 아홉 개가 있지만 변경할 때마다 아홉 개를 다 실행하지는 않는다.

사용법

쓸 때

새 프로젝트나 기능, 혹은 규모가 큰 변경을 시작하는데 아직 문서화된 명세가 없다.

/spec

코드를 작성하기 전에 목표, 명령어, 구조, 코드 스타일, 테스트, 작업 경계를 담은 요구사항 문서를 얻는다.

쓸 때

명세는 이미 있고, 작업 중간마다 승인을 기다리지 않고 에이전트가 모든 작업을 완료하길 원한다.

/build auto

계획을 한 번 승인하면 각 작업이 테스트 주도로 진행돼 개별 커밋으로 남고, 작업이 실패하거나 위험한 단계가 나오면 실행이 잠시 멈춘다.

쓸 때

Claude Code에 이미 내장 /review 명령어가 있어서, 그 대신 이 저장소의 리뷰를 쓰고 싶다.

/agent-skills:review

같은 짧은 이름을 쓰는 호스트 명령어 대신, 코드 품질에 초점을 맞춘 이 저장소의 병합 전 리뷰를 받는다.

설치 방법

지원하는 모든 에이전트에서 가장 빠르게 설치하는 방법은 명령어 한 줄이다:

npx skills add addyosmani/agent-skills

설치 전에 목록 살펴보기:

npx skills add addyosmani/agent-skills --list

스킬 하나만 설치하기:

npx skills add addyosmani/agent-skills --skill test-driven-development

Claude Code에서 권장하는 설치 방법:

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

SSH로 마켓플레이스 클론에 실패하면 HTTPS URL을 사용한다:

/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills

설치 후 코드를 요청하기 전에 /spec을 입력하면 된다. 짧은 수명 주기 명령어가 나타나지 않는 GitHub Copilot에서는 /spec-driven-development를 입력한다.

이 도구가 맞지 않을 때

스킬이 공용 체크리스트를 필요로 할 때는 스킬 하나만 설치하는 구성이 맞지 않는다. 개별 설치는 저장소 수준의 references/ 디렉터리를 빼고 skills/<name>/만 복사하기 때문에 스킬 자체는 돌아가더라도 체크리스트 경로가 빠진다. 이 문제는 이슈 361에서 추적 중이므로, 저장소 전체를 설치하거나 클론하고 아니면 필요한 체크리스트를 설치한 스킬 내부의 references/ 디렉터리로 복사해 넣어야 한다.

하는 일이 빌드 수명 주기가 아닐 때도 이 저장소는 맞지 않는다. 어떤 저장소를 고를지는 스타 수가 아니라 작업 목적에 달려 있으며, 스타 수가 더 많다고 갈아탈 필요는 없다.

저장소	선택 기준	스타 수
morluto/rea	애플리케이션 동작부터 네이티브 바이너리까지 시스템을 역공학할 에이전트가 필요할 때	459,838
mattpocock/skills	이 명세-배포 수명 주기 대신 실제 동작하는 .agents 디렉터리에서 가져온 스킬을 원할 때	324,479
obra/superpowers	명령어에 매핑된 이 수명 주기 대신 에이전트 스킬 프레임워크와 소프트웨어 개발 방법론을 원할 때	317,645

먼저 명세를 쓰고, 각 조각을 테스트 가능하게 유지하며 개별 커밋으로 남기고, 자동 빌드라도 실패 시 멈추는 단계를 건너뛰지 말자. MIT 라이선스를 따르는 addyosmani/agent-skills 저장소는 스타 117,564개, 포크 12,297개, 열린 이슈 122개를 기록하고 있으며, 2026-02-15에 만들어져 2026-11-14에 마지막 푸시가 올라왔다.

많이 묻는 질문

어떤 에이전트에 이 스킬을 설치할 수 있나?

skills CLI는 Claude Code, Cursor, Codex, Copilot, Cline을 포함해 70개 이상의 에이전트에 설치할 수 있다. 스킬이 일반 마크다운이라 시스템 프롬프트나 지침 파일을 받는 에이전트라면 네이티브 플러그인 설치 없이도 쓸 수 있다.

세션을 열 때마다 모든 스킬이 실행되나?

아니다. 세션을 시작하거나 선택이 필요할 때 using-agent-skills가 작업을 하나의 워크플로우에 연결하고, API 설계나 사용자 인터페이스 작업 같은 나머지 스킬은 해당 작업에 따라 켜진다.

스킬 하나만 설치하면 무엇이 빠지나?

저장소 루트에 있는 공용 references/ 디렉터리가 빠진다. 스킬에 그 파일이 필요하다면 저장소 전체를 설치하거나 클론하고, 아니면 체크리스트를 직접 복사해 넣어야 한다.

출처: GitHub 저장소 addyosmani/agent-skills, https://github.com/addyosmani/agent-skills