Addy Osmani의 agent-skills: AI 코딩 에이전트를 시니어 엔지니어로 만드는 19개 스킬

AI 코딩 에이전트는 기본적으로 최단 경로를 택합니다. 스펙, 테스트, 보안 리뷰를 건너뛰죠. agent-skills는 시니어 엔지니어가 프로덕션 코드에 적용하는 것과 동일한 규율을 구조화된 워크플로우로 강제하는 오픈소스 프로젝트입니다.

AI 코딩 에이전트를 사용해본 개발자라면 한 번쯤 경험했을 겁니다. "테스트 코드 작성해줘"라고 하면 작성하지만, 명시하지 않으면 건너뜁니다. 보안 리뷰도, 코드 리뷰도 마찬가지입니다. AI 에이전트는 코드를 잘 짜지만 엔지니어링 프로세스를 스스로 따르지 않습니다.

Google Chrome DevRel 출신이자 현재 Anthropic에서 일하는 Addy Osmani가 이 문제를 정면으로 풀었습니다. addyosmani/agent-skills는 AI 코딩 에이전트가 시니어 엔지니어의 워크플로우를 일관되게 따르도록 만든 프로덕션급 엔지니어링 스킬 19종입니다. 2026년 4월 기준 GitHub 스타 8,600개, 포크 853개를 기록하며 빠르게 성장하고 있습니다.

agent-skills란 무엇인가

agent-skills는 AI 코딩 에이전트(Claude Code, Cursor, Gemini CLI, Copilot 등)가 사용하는 구조화된 워크플로우 패키지입니다. 참조 문서가 아니라 에이전트가 실제로 따르는 프로세스라는 점이 핵심입니다.

일반적인 코딩 가이드라인이 "이렇게 하면 좋습니다"라고 알려주는 것이라면, agent-skills는 "이 단계를 건너뛰면 다음으로 넘어갈 수 없습니다"라고 강제합니다. 에이전트가 스펙 없이 코딩을 시작하거나, 테스트 없이 PR을 올리는 것을 구조적으로 차단합니다.

19개 스킬과 6단계 개발 라이프사이클

agent-skills는 소프트웨어 개발의 전체 라이프사이클을 6단계로 나누고, 각 단계에 해당하는 스킬을 배치합니다.

DEFINE (정의)

• idea-refine: 아이디어를 구체적인 요구사항으로 정제
• spec-driven-development: 스펙 문서를 먼저 작성하고, 이를 기반으로 개발 진행

PLAN (계획)

• planning-and-task-breakdown: 작업을 관리 가능한 단위로 분해

BUILD (구현)

• incremental-implementation: 작은 단위로 점진적 구현
• test-driven-development: 테스트 먼저 작성, 그 다음 구현
• context-engineering: CLAUDE.md, 규칙 파일, MCP를 활용한 맥락 관리
• frontend-ui-engineering: 프론트엔드 UI 구현 워크플로우
• api-and-interface-design: API 설계 원칙과 패턴

VERIFY (검증)

• browser-testing-with-devtools: 브라우저 기반 테스트와 DevTools 활용
• debugging-and-error-recovery: 디버깅 전략과 에러 복구

REVIEW (리뷰)

• code-review-and-quality: 코드 리뷰 프로세스와 품질 기준
• code-simplification: 코드 단순화와 리팩토링
• security-and-hardening: 보안 취약점 점검과 하드닝
• performance-optimization: 성능 최적화 체크리스트

SHIP (배포)

• git-workflow-and-versioning: Git 워크플로우와 버전 관리
• ci-cd-and-automation: CI/CD 파이프라인 자동화
• deprecation-and-migration: 디프리케이션과 마이그레이션 전략
• documentation-and-adrs: 문서화와 아키텍처 결정 기록
• shipping-and-launch: 배포와 런칭 체크리스트

핵심 설계 원칙 4가지

agent-skills가 단순한 체크리스트 모음이 아닌 이유는 설계 철학에 있습니다.

1. 프로세스, 프로즈 아님 (Process, Not Prose)

각 스킬은 읽기 자료가 아니라 에이전트가 따라야 하는 워크플로우입니다. 단계별로 입력과 출력이 정의되어 있고, 다음 단계로 넘어가려면 이전 단계의 산출물이 필요합니다.

2. 반합리화 (Anti-rationalization)

"나중에 테스트 추가할게요", "이 부분은 보안 리뷰 안 해도 될 것 같아요" 같은 변명을 사전에 차단합니다. 각 스킬에 반론 테이블이 내장되어 있어서, AI 에이전트가 프로세스를 건너뛰려 할 때 왜 건너뛰면 안 되는지 근거를 제시합니다.

3. 검증 비타협 (Non-negotiable Verification)

모든 스킬이 증거 요구사항으로 끝납니다. "잘 되는 것 같다"는 통과 기준이 아닙니다. 테스트 결과, 벤치마크 수치, 보안 스캔 리포트 같은 구체적인 증거를 요구합니다.

4. 점진적 공개 (Progressive Disclosure)

SKILL.md 파일이 진입점이고, 세부 참조 문서는 필요할 때만 로드합니다. AI 에이전트의 컨텍스트 윈도우(토큰)를 효율적으로 사용하기 위한 설계입니다.

Google 엔지니어링 문화의 코드화

Addy Osmani가 Google에서 경험한 엔지니어링 문화가 agent-skills 곳곳에 녹아 있습니다.

수만 명의 Google 엔지니어에게 적용되던 원칙이 이제 AI 코딩 에이전트의 워크플로우로 구조화된 것입니다.

슬래시 커맨드와 에이전트 페르소나

agent-skills는 7개의 슬래시 커맨드를 제공합니다.

3개의 에이전트 페르소나도 포함됩니다.

• code-reviewer: 시니어 스태프 엔지니어 관점의 코드 리뷰
• test-engineer: QA 전문가 관점의 테스트 설계
• security-auditor: 보안 엔지니어 관점의 취약점 점검

그리고 4개의 참조 체크리스트(testing-patterns.md, security-checklist.md, performance-checklist.md, accessibility-checklist.md)로 각 영역의 상세 기준을 제공합니다.

설치 방법

Claude Code

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

Cursor

SKILL.md 파일을 .cursor/rules/ 디렉토리에 복사합니다.

Gemini CLI

gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

특정 도구에 종속되지 않고 Claude Code, Cursor, Gemini CLI, Copilot 등 주요 AI 코딩 에이전트 모두에서 사용할 수 있습니다.

Addy Osmani의 AI 코딩 워크플로우 7가지 원칙

agent-skills를 만든 Addy Osmani가 자신의 블로그에서 공유한 AI 코딩 워크플로우 핵심 원칙입니다.

1. 스펙 먼저, 코드 나중: 15분 동안 요구사항을 정리하는 것이 몇 시간의 삽질을 줄여줍니다.
2. 작은 반복 단위: LLM에 한 번에 큰 작업을 주지 마세요. 작게 쪼개서 하나씩 확인하세요.
3. 컨텍스트가 전부: CLAUDE.md, 규칙 파일, MCP로 에이전트에게 충분한 맥락을 제공하세요.
4. 여러 모델 사용: 하나의 모델이 막히면 다른 모델로 교차 확인하세요.
5. 테스트가 AI의 안전망: 테스트 없이 에이전트가 올바르게 작동한다고 믿지 마세요.
6. 커밋은 세이브 포인트: 자주 커밋하고 워크트리로 병렬 작업하세요.
7. 인간이 디렉터: AI는 어시스턴트지, 자율 코더가 아닙니다.

왜 agent-skills가 중요한가

AI 코딩 에이전트의 채택이 빠르게 늘고 있지만, 대부분 "코드 생성" 능력에만 집중합니다. 하지만 프로덕션 코드는 생성만으로 완성되지 않습니다. 스펙 정의, 테스트, 보안 리뷰, 코드 리뷰, 문서화, 배포까지 전체 엔지니어링 프로세스가 필요합니다.

agent-skills는 이 gap을 메워줍니다. AI 에이전트가 코드만 짜는 주니어가 아니라, 프로세스를 따르는 시니어처럼 일하게 만드는 구조적 장치입니다.

MIT 라이선스 오픈소스로, 누구나 자유롭게 사용하고 기여할 수 있습니다. 2026년 4월 기준 8,600+ 스타와 853 포크가 이 프로젝트의 가치를 보여줍니다.

자주 묻는 질문

Q: agent-skills는 특정 프로그래밍 언어에 종속되나요?

아닙니다. 언어에 독립적인 엔지니어링 프로세스를 정의하므로, Python, TypeScript, Go 등 어떤 언어로 개발하든 적용할 수 있습니다.

Q: Claude Code 외 다른 AI 코딩 도구에서도 사용할 수 있나요?

네. Claude Code, Cursor, Gemini CLI, GitHub Copilot 등 주요 AI 코딩 에이전트를 모두 지원합니다. 각 도구별 설치 방법이 README에 안내되어 있습니다.

Q: 기존 프로젝트에 바로 적용할 수 있나요?

네. 기존 프로젝트에 스킬을 추가 설치하면 됩니다. 기존 코드를 변경할 필요 없이, AI 에이전트의 워크플로우만 개선됩니다.

Q: 19개 스킬을 모두 사용해야 하나요?

아닙니다. 점진적 공개 설계 덕분에 필요한 스킬만 선택적으로 활용할 수 있습니다. spec-driven-development와 test-driven-development부터 시작하는 것을 추천합니다.

참고 자료

• addyosmani/agent-skills GitHub 저장소
• Addy Osmani - My LLM Coding Workflow
• Addy Osmani LinkedIn 포스트