AI 에이전트에게 시니어 엔지니어의 습관을 이식하다: agent-skills

오늘 하루 3,275개의 별이 쏟아졌다. Google Chrome 팀 출신으로 Lighthouse·web.dev를 만든 Addy Osmani가 공개한 agent-skills는 AI 코딩 에이전트에게 "시니어 엔지니어의 워크플로"를 주입하는 오픈소스 프레임워크다. 단순 프롬프트 모음이 아니다. 프로덕션급 개발 프로세스를 AI에게 이식하는 표준을 제안한다.

---

이게 뭔가

비유하자면 이렇다. 신입 개발자가 입사하면 팀은 코딩 스타일 가이드, 코드 리뷰 체크리스트, 배포 절차를 가르친다. AI 에이전트도 마찬가지다. 아무리 뛰어난 모델이라도 "우리 팀 방식대로" 일하려면 맥락이 필요하다.

agent-skills는 이 맥락을 스킬(Skill) 파일로 패키징한다. 각 스킬은 "API를 설계할 때는 이렇게", "UI를 짤 때는 저렇게"라는 원칙을 담고 있으며 에이전트가 관련 작업을 시작하면 자동으로 활성화된다. 개발자가 매번 지시할 필요가 없다.

---

왜 지금 뜨는가

세 가지 흐름이 겹쳤다.

첫째, AI 코딩 도구의 대중화와 그 부작용. Claude Code·Cursor·GitHub Copilot이 확산되면서 "AI가 코드는 짜는데 팀 컨벤션을 무시한다"는 불만이 커지고 있다. 스킬 기반 제어는 정확히 이 공백을 채운다.

둘째, Addy Osmani의 브랜드 신뢰. 그의 이름은 프론트엔드 커뮤니티에서 즉각적인 신뢰 지표다. 이 레포가 단순한 해커의 실험이 아니라는 증거다.

셋째, "vibe coding"의 한계 인식. 즉흥적 AI 프롬프트로 코드를 뽑아내는 방식은 프로젝트 규모가 커질수록 기술 부채를 키운다. 구조화된 대안을 찾는 수요가 무르익었다.

---

핵심 기능

개발 라이프사이클을 7개 슬래시 커맨드로 구조화한다.

커맨드	역할	원칙
/spec	아이디어 → PRD·명세	코딩 전에 스펙 먼저
/plan	원자 단위 작업 분해	작고 독립적인 태스크
/build	점진적 구현	한 슬라이스씩
/test	동작 증명	테스트가 곧 증거
/review	머지 전 코드 검사	코드 건강 개선
/code-simplify	복잡도 제거	명료함 > 영리함
/ship	프로덕션 배포	빠를수록 안전

/build auto 모드는 스펙 승인 후 계획→구현을 자율 실행한다. 각 태스크는 TDD로 진행되고 개별 커밋으로 분리되며 실패나 위험 단계에서는 멈춘다. 자율적이지만 무감독은 아니다.

---

누구에게 쓸모 있나

• Claude Code·Cursor 사용자: 즉시 설치해 워크플로를 표준화한다.
• 팀 리드: 온보딩 문서 대신 스킬 파일로 팀 컨벤션을 AI에 주입할 수 있다.
• 솔로 개발자: 시니어처럼 일하는 AI 페어 프로그래머를 얻는다.

AI 코딩 도구를 전혀 쓰지 않거나, Claude Code·Cursor 환경이 아닌 경우라면 지금 당장의 실용성은 낮다.

---

시작하기

README 기준으로 두 가지 설치 경로가 있다.

Claude Code (권장)

# 마켓플레이스 설치
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

SSH 키 미설정 시 오류가 날 수 있다. GitHub SSH 설정 가이드를 먼저 확인하거나 HTTPS 방식으로 설치한다.

직접 클론 (범용)

git clone https://github.com/addyosmani/agent-skills.git ~/.claude/skills

---

사용 예시

1. 스펙 작성부터 자율 구현까지 한 번에

# 아이디어를 명세서로 전환
/spec "사용자 알림 설정 페이지"

# 명세 기반 실행 계획 수립
/plan

# 계획 승인 후 자율 구현 (TDD + 개별 커밋)
/build auto

아이디어 → PRD → 구현의 전체 파이프라인을 에이전트가 일관된 방식으로 실행한다.

2. 머지 전 코드 리뷰 게이트

/review

PR 머지 전 실행하면 에이전트가 코드 품질·보안·테스트 커버리지를 시니어 기준으로 점검한다.

3. 복잡해진 컴포넌트 단순화

/code-simplify

기능은 유지하면서 불필요한 복잡도를 걷어낸다. "명료함이 영리함보다 낫다"는 원칙을 AI가 적용한다.

---

한계·주의

• Claude Code·Cursor 의존적: README가 두 도구 중심으로 작성돼 있다. 다른 에디터 환경의 지원 범위는 아직 불분명하다.
• 스킬 품질 = 결과 품질: 스킬 파일을 잘못 커스터마이징하면 AI가 잘못된 패턴을 일관되게 적용한다. 처음에는 기본 스킬을 그대로 쓰는 편이 낫다.
• 자율 모드의 범위: /build auto는 계획 승인 후에만 자율 실행된다. 아키텍처 결정이나 스펙 정의를 AI가 단독으로 수행하지는 않는다.
• 초기 프로젝트 리스크: 54,000개 별을 받았지만 오픈소스 초기 단계다. API와 명세가 변경될 수 있으니 프로덕션 의존 전에 버전 고정을 확인하라.