프로젝트 개요

Agent Skills는 20개의 재사용 가능한 Markdown 기반 워크플로 지침 라이브러리로, 시니어 엔지니어의 모범 사례를 AI 코딩 에이전트에 인코딩하여 전체 소프트웨어 개발 수명 주기에 걸쳐 코너를 자르는 것을 방지합니다.

프로젝트 배경 및 포지셔닝

존재 이유

AI 코딩 에이전트는 유능하지만 규율이 부족합니다. 제약 없이 방치하면 사양을 건너뛰고, 테스트를 생략하고, 보안 검토를 무시하며, 그럴듯한 변명으로 지름길을 정당화합니다. Agent Skills는 Google 엔지니어링 문화에 깊은 뿌리를 둔 개발자 옹호자인 Addy Osmani가 편견이 있고 검증 가능한 워크플로를 에이전트의 지침 계층에 직접 내장하여 이 문제를 해결하기 위해 만들었습니다. 이 프로젝트는 코드를 자산이 아닌 부채로 취급하며 "옳아 보인다"는 것이 측정 가능한 증거를 대체할 수 없다고 주장합니다.

유사 프로젝트와의 차이점

대부분의 프롬프트 라이브러리는 임시 팁 모음입니다. Agent Skills는 세 가지 면에서 다릅니다.

수명 주기 적용 범위 — 스킬은 정의 → 계획 → 빌드 → 검증 → 검토 → 배포의 모든 단계에 매핑되며, 단일 단계만 대상으로 하지 않습니다.
합리화 방지 가드레일 — 각 스킬은 에이전트가 취하는 일반적인 지름길을 명시적으로 명명하고 문서화된 반박을 제공하여 거부보다 준수를 더 어렵게 만듭니다.
도구 불가지론적 이식성 — 모든 스킬이 일반 Markdown이므로 Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot, Kiro IDE 또는 시스템 프롬프트를 수락하는 모든 에이전트에서 수정 없이 실행됩니다.

기능 범주

📋 정의 — 사양 스킬 · 3개 스킬
대표적인 예: 시스템 요구 사항, API 계약, 데이터 모델 설계.
목적: 한 줄의 코드도 작성하기 전에 에이전트가 요구 사항을 명확히 하도록 강제합니다.

🗺 계획 — 아키텍처 및 분해 스킬 · 4개 스킬
대표적인 예: 작업 분해, 아키텍처 계획, 종속성 매핑, 타임라인 추정.
목적: 에이전트가 구현으로 바로 뛰어드는 대신 감사 가능한 계획을 생성하도록 합니다.

🔨 빌드 — 구현 스킬 · 4개 스킬
대표적인 예: 점진적 제공, 모듈성 강제, 코드 구성, 트렁크 기반 브랜칭.
목적: 에이전트가 항상 병합 가능한 작고 검증 가능한 단계로 빌드하도록 합니다.

✅ 검증 — 테스트 스킬 · 4개 스킬
대표적인 예: 단위 테스트, 통합 테스트, 테스트 커버리지 게이트, 테스트 패턴 참조 체크리스트.
목적: 에이전트가 올바름을 가정하는 대신 테스트로 기능을 증명하도록 합니다.

🔍 검토 — 품질 게이트 스킬 · 3개 스킬
대표적인 예: 코드 검토, 보안 감사, 성능 검토, 접근성 체크리스트.
목적: 병합을 승인하기 전에 시니어 엔지니어가 사용하는 것과 동일한 기준을 적용합니다.

🚀 배포 — 배포 스킬 · 2개 스킬
대표적인 예: 프로덕션 준비 체크리스트, 배포 전략, 롤백 계획.
목적: 에이전트가 프로덕션으로 푸시하기 전에 관찰 가능성, 롤백 및 온콜 영향을 고려하도록 합니다.

핵심 하이라이트

20개의 수명 주기 전반에 걸친 스킬을 한 곳에 — 첫 번째 사양부터 프로덕션 배포까지, 모든 단계에는 단계별 절차와 검증 게이트가 있는 전용 스킬이 최소 하나 이상 있습니다.

워크플로 단계에 매핑된 7개의 슬래시 명령 — /spec, /plan, /build, /test, /review, /code-simplify, /ship은 IDE에 관계없이 팀이 에이전트에게 지시하기 위한 공유 어휘를 제공합니다.

3개의 전문 에이전트 페르소나 — 코드 검토자, 테스트 엔지니어, 보안 감사자 페르소나가 스킬과 함께 제공되어 팀이 전용 품질 작업을 위해 집중된 에이전트를 실행할 수 있습니다.

4개의 참조 체크리스트 — 테스트 패턴, 보안 관행, 성능 최적화 및 접근성 표준에 대한 독립적이고 링크 가능한 체크리스트는 경량 규정 준수 게이트 역할을 합니다.

엔지니어링 원칙 고정 — 스킬은 명명된 원칙(Hyrum의 법칙, 비욘세 규칙, Chesterton의 울타리)을 내장하여 에이전트가 단순히 기계적으로 따르는 것이 아니라 관행이 존재하는 이유를 추론할 수 있도록 합니다.

최고 수준의 멀티툴 통합 — 전용 구성 디렉토리(.claude/, .cursor/, .windsurf/, .gemini/, .opencode/) 및 각 플랫폼에 대한 설정 가이드는 모든 IDE에서 마찰 없이 채택할 수 있습니다.

역할별 사용 사례

일반 개발자
매일 워크플로 드라이버로 7개의 슬래시 명령을 사용합니다. 모든 기능을 시작하기 전에 /spec을 실행하고, 구현 중에 /build를 실행하고, PR을 열기 전에 /review를 실행합니다. 스킬은 일정 부담 없이 당신을 지켜보는 시니어 엔지니어 역할을 합니다.

DevOps / 플랫폼 엔지니어
배포 스킬과 프로덕션 준비 체크리스트에 집중하여 AI 생성 배포 코드가 프로덕션에 도달하기 전에 롤백 전략, 기능 플래그 및 관찰 가능성 후크를 고려하도록 합니다.

데이터 및 연구 엔지니어
정의 및 계획 스킬을 사용하여 에이전트가 파이프라인 또는 변환 코드를 생성하기 전에 명확한 데이터 계약 및 스키마 문서를 강제합니다. 테스트 스킬은 데이터 품질 어설션에 대한 커버리지를 강제하는 데 도움이 됩니다.

제품 팀
사양 스킬을 요구 사항 번역 계층으로 사용합니다. 제품 브리프를 사양 스킬을 실행하는 에이전트에 공급하여 엔지니어링과의 반복을 줄이는 구조화되고 개발자 준비된 요구 사항 문서를 얻습니다.

빠른 시작

🔍 리소스 찾기 방법

리포지토리의 skills/ 디렉토리에서 20개의 .md 스킬 파일, 3개의 전문 페르소나에 대한 agents/, 4개의 독립형 체크리스트에 대한 references/를 찾아보세요. docs/ 디렉토리에는 도구별 설정 가이드가 포함되어 있습니다.

skills/          # 20개 수명 주기 스킬
agents/          # code-reviewer, test-engineer, security-auditor
references/      # testing, security, performance, accessibility
docs/            # 도구별 설정 가이드

🛠 설치 / 통합 방법

옵션 1 — Claude Code 플러그인 마켓플레이스 (권장)

/plugin marketplace add addyosmani/agent-skills

옵션 2 — 모든 도구에 대한 로컬 복제

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

# Claude Code — 로컬 플러그인 디렉토리 지정
claude --plugin-dir ./

# Gemini CLI
gemini skills install https://github.com/addyosmani/agent-skills.git

옵션 3 — 개별 스킬을 시스템 프롬프트로 복사

# 모든 에이전트에서 시스템 프롬프트로 모든 스킬 사용
cat skills/review.md   # 도구의 시스템 프롬프트에 붙여넣기

Cursor / Windsurf / Kiro IDE — .cursor/, .windsurf/, .opencode/ 디렉토리에는 즉시 사용 가능한 구성 파일이 포함되어 있습니다. docs/의 도구별 가이드를 따르세요.

🤝 기여 방법

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

# 기존 규칙에 따라 새 스킬 만들기
cp skills/review.md skills/my-skill.md
# my-skill.md 편집 — 포함할 내용: 목표, 단계, 검증 게이트, 합리화 방지

# 풀 리퀘스트 제출
git checkout -b feat/my-skill
git add skills/my-skill.md
git commit -m "feat: <목적>을 위한 my-skill 추가"
git push origin feat/my-skill
# https://github.com/addyosmani/agent-skills/pulls에서 PR 열기

프로젝트 구조

agent-skills/
├── skills/                  # 20개 수명 주기 스킬 Markdown 파일
│   ├── spec.md              # 요구 사항 정의
│   ├── plan.md              # 작업을 작업으로 분해
│   ├── build.md             # 점진적 구현
│   ├── test.md              # 검증 워크플로
│   ├── review.md            # 병합 전 품질 게이트
│   ├── code-simplify.md     # 복잡성 감소
│   └── ship.md              # 프로덕션 배포 준비
├── agents/                  # 전문 에이전트 페르소나
│   ├── code-reviewer.md
│   ├── test-engineer.md
│   └── security-auditor.md
├── references/              # 독립형 품질 체크리스트
│   ├── testing-patterns.md
│   ├── security.md
│   ├── performance.md
│   └── accessibility.md
├── .claude/commands/        # Claude Code 슬래시 명령 통합
├── .gemini/commands/        # Gemini CLI 통합
├── .cursor/                 # Cursor IDE 구성
├── .windsurf/               # Windsurf IDE 구성
├── .opencode/               # Kiro / OpenCode IDE 구성
├── docs/                    # 도구별 설정 가이드
└── README.md                # 프로젝트 개요 및 빠른 시작

라이선스

MIT 라이선스


✅ 허용	개인, 오픈 소스 및 상업용 프로젝트에서 사용
✅ 허용	포크, 수정 및 출처 표기하여 재배포
✅ 허용	독점 AI 제품 또는 SaaS 도구에 스킬 번들링
❌ 금지	재배포된 복사본에서 저작권 고지 제거
ℹ️ 참고	보증 없음; 기여자는 프로덕션 사용 결과에 대해 책임을 지지 않음

FAQ

Q: Claude Code가 반드시 필요한가요, 아니면 모든 AI 코딩 도구에서 작동하나요?
A: Markdown을 시스템 프롬프트로 수락하는 모든 도구에서 작동합니다. 20개의 스킬 모두 일반 .md 파일입니다. Claude Code는 가장 풍부한 UX(슬래시 명령, 플러그인 마켓플레이스)를 갖춘 기본 통합이지만 Cursor, Windsurf, Gemini CLI, GitHub Copilot 및 모든 일반 에이전트도 동일하게 잘 작동합니다.

Q: "스킬"은 단순히 프롬프트를 붙여넣는 것과 어떻게 다른가요?
A: 각 스킬은 일회성 지침이 아니라 구조화된 워크플로입니다. 명시적인 목표, 각 단계의 검증 게이트가 있는 번호가 매겨진 단계, 에이전트가 일반적으로 취하는 지름길을 예상하고 반박하는 "합리화 방지" 섹션이 포함되어 있습니다. 이로 인해 스킬이 간단한 프롬프트보다 훨씬 강력합니다.

Q: 팀의 내부 관례를 스킬에 추가할 수 있나요?
A: 예 — 그리고 그것이 권장되는 워크플로입니다. 리포지토리를 포크하고 관련 .md 파일을 편집하여 팀의 특정 표준(예: 내부 테스트 프레임워크, 배포 체크리스트)을 포함하고 에이전트를 포크로 가리킵니다. Markdown 형식은 쉬운 사용자 정의를 위해 특별히 선택되었습니다.

Q: AI 코딩 에이전트의 속도가 크게 느려지나요?
A: 스킬은 단계를 추가하지만 규율이 부족한 생성으로 인해 발생하는 훨씬 더 비용이 많이 드는 재작업을 방지합니다. 이 프로젝트는 이를 의도적인 절충으로 취급합니다. 초기 출력은 느리지만 검토 또는 프로덕션에 도달하는 결함은 훨씬 적습니다.

Q: 세 가지 전문 페르소나는 20가지 스킬과 어떻게 다릅니까?
A: 스킬은 워크플로 지침입니다. 에이전트에게 작업을 수행하는 방법을 알려줍니다. 페르소나(agents/)는 집중된 작업을 위해 에이전트의 정체성과 우선순위를 구성합니다(예: 항상 보안 감사자처럼 생각). 이들은 상호 보완적입니다. 가장 철저한 결과를 얻기 위해 보안 감사자 페르소나를 사용하여 보안 감사 스킬을 적용할 수 있습니다.

빠른 링크

리소스	URL
GitHub 리포지토리	https://github.com/addyosmani/agent-skills
플러그인 마켓플레이스 (Claude Code)	`/plugin marketplace add addyosmani/agent-skills`
이슈 및 토론	https://github.com/addyosmani/agent-skills/issues
릴리스	https://github.com/addyosmani/agent-skills/releases
작성자	https://github.com/addyosmani

요약

Agent Skills는 기능 격차가 아닌 구조적 문제를 해결하는 드문 오픈 소스 프로젝트입니다. AI 코딩 에이전트가 자신감 넘치는 주니어처럼 행동하는 대신 규율 잡힌 시니어 엔지니어처럼 행동하도록 만듭니다. 25,000개 이상의 GitHub 스타, 모든 주요 AI 코딩 플랫폼에 대한 최고 수준의 지원 및 MIT 라이선스를 통해 이미 개발 워크플로에서 AI를 사용하는 모든 팀에서 즉시 사용할 수 있습니다. AI 코딩 도구에서 일관되고 감사 가능하며 프로덕션 준비가 된 출력을 원하는 개발자는 Agent Skills를 에이전트 구성의 첫 번째 계층으로 만드는 것을 고려해야 합니다.

agent-skills