Agent Skills

AI 코딩 에이전트를 위한 프로덕션 수준의 엔지니어링 스킬.

스킬은 시니어 엔지니어가 소프트웨어를 만들 때 쓰는 워크플로우, 품질 게이트, 모범 사례를 담습니다. 이 스킬들은 AI 에이전트가 개발의 모든 단계에서 일관되게 따르도록 패키징되어 있습니다.

imageAddy의 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

커맨드

개발 생명주기에 대응하는 슬래시 커맨드 9개입니다. 각각이 알맞은 스킬을 자동으로 활성화합니다.

Claude Code에서는 플러그인 커맨드로 설치됩니다. /review처럼 내장 커맨드와 이름이 같으면 네임스페이스 형식을 쓰세요. /agent-skills:review.

스펙이 생긴 뒤 수동 단계를 줄이고 싶으신가요? **/build auto**는 계획을 만들고, 한 번의 승인으로 모든 작업을 구현합니다. 계획을 한 번 승인하면 그다음부터는 자율적으로 실행됩니다. 작업 사이에 사람이 개입하는 단계를 없앱니다. 검증은 그대로입니다. 모든 작업은 여전히 테스트 주도이고 개별적으로 커밋되며, 실패하거나 위험한 단계에서는 멈춥니다.

스킬은 하고 있는 일에 따라 자동으로 활성화되기도 합니다. API를 설계하면 api-and-interface-design이, UI를 만들면 frontend-ui-engineering이 켜지고, 그런 식으로 이어집니다.

빠른 시작

가장 빠른 경로. 어떤 에이전트든 명령 하나. 공개된 skills CLI는 70개 이상의 에이전트(Claude Code, Cursor, Codex, Copilot, Cline 등)에 설치됩니다.

npx skills add addyosmani/agent-skills            # install all 25 skills
npx skills add addyosmani/agent-skills --list     # browse before installing

개별 스킬만 받으려면:

npx skills add addyosmani/agent-skills --skill code-review-and-quality   # five-axis review before merge
npx skills add addyosmani/agent-skills --skill interview-me              # requirements interrogation, one question at a time
npx skills add addyosmani/agent-skills --skill test-driven-development   # red-green-refactor, enforced

스킬을 하나만 설치하나요? 스킬 단위 npx 설치는 skills/<name>/만 복사하고, 저장소 수준의 references/ 디렉터리는 복사하지 않습니다. 스킬 자체는 동작하지만, 공유 보충 체크리스트로 가는 경로는 쓸 수 없습니다. 저장소 전체 통합을 쓰거나, 저장소를 클론하거나, 필요한 체크리스트를 설치된 스킬 안의 references/ 디렉터리로 복사하세요. 이 이식성 공백은 #361에서 추적합니다.

네이티브 통합을 원하시면 아래에서 도구를 고르세요.

Claude Code (권장)

마켓플레이스 설치:

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

SSH 오류가 나나요? 마켓플레이스는 SSH로 저장소를 클론합니다. GitHub에 SSH 키가 없다면, SSH 키를 추가하거나, 마켓플레이스 추가 단계에서 HTTPS 클론을 강제하도록 전체 HTTPS URL을 쓰세요:

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

Windows나 macOS에서 /plugin install이 여전히 git@github.com: Permission denied (publickey)로 실패하면, 서브프로세스 클론에서 GitHub SSH URL을 HTTPS로 바꾸도록 Git을 한 번 설정하는 방법이 권장됩니다:

git config --global url."https://github.com/".insteadOf git@github.com:

로컬 / 개발:

git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills

Cursor

워크플로우 스킬은 .cursor/skills/에 두고 (agent-skills/skills/에서 동기화), 짧은 정책은 .cursor/rules/*.mdc에 두세요. 스킬 전문을 규칙에 붙여 넣지 마세요. 두 디렉터리 모두 프로젝트 안에 있습니다. 이 저장소는 .cursor/ 폴더를 포함하지 않습니다. docs/cursor-setup.md를 보세요.

Antigravity CLI

스킬과 서브에이전트를 위한 네이티브 플러그인으로 설치합니다. 영향을 받는 Antigravity CLI 릴리스에서는 레거시 커맨드 TOML이 변환된 것으로 보고되지만, 그 래퍼 커맨드는 발견되지 않습니다. 기반이 되는 네임스페이스 스킬을 직접 호출하세요. docs/antigravity-setup.md를 보세요.

저장소에서 설치:

agy plugin install https://github.com/addyosmani/agent-skills.git

로컬 클론에서 설치:

git clone https://github.com/addyosmani/agent-skills.git
agy plugin install ./agent-skills

Gemini CLI

자동 발견을 위해 네이티브 스킬로 설치하거나, 지속되는 컨텍스트를 위해 GEMINI.md에 추가하세요. docs/gemini-cli-setup.md를 보세요.

저장소에서 설치:

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

로컬 클론에서 설치:

gemini skills install ./agent-skills/skills/

Windsurf

스킬 내용을 Windsurf 규칙 설정에 추가하세요. docs/windsurf-setup.md를 보세요.

OpenCode

스킬을 .opencode/skills/(또는 ~/.config/opencode/skills/)로 복사하고, 프로젝트 로컬 AGENTS.md를 추가한 뒤, 에이전트 주도 실행에는 내장 skill 도구를 사용하세요. 선택적 슬래시 커맨드는 .opencode/commands/ 아래에 추가할 수 있습니다.

docs/opencode-setup.md를 보세요.

GitHub Copilot

agents/의 에이전트 정의를 Copilot 페르소나로 쓰고, 스킬 내용은 .github/copilot-instructions.md에 둡니다. 생명주기 슬래시 커맨드(/spec, /plan, /build, /test, /review, /ship)는 Claude Code 커맨드라 Copilot에는 나타나지 않습니다. 대신 스킬 이름으로 호출하세요 (/spec-driven-development 등). docs/copilot-setup.md를 보세요.

독립 실행형 copilot CLI를 쓰시나요? 플러그인으로 설치하세요. docs/copilot-cli-setup.md를 보세요.

Kiro IDE & CLI

Codex

네이티브 Codex 플러그인으로 설치합니다 (Codex CLI v0.122 이상):

codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills

첫 명령은 마켓플레이스를 등록하고, 두 번째 명령은 플러그인을 설치합니다. Codex는 .codex-plugin/plugin.json을 통해 루트 skills/ 디렉터리를 직접 읽습니다. 설치한 뒤에는 채팅에서 @로 스킬을 호출하세요 (예: @spec-driven-development). 로컬 설치와 문제 해결은 docs/codex-setup.md를 보세요.

Command Code

내장 cmd skills 명령으로 네이티브 설치합니다. Command Code는 저장소를 클론하고, 모든 SKILL.md를 찾은 뒤 .commandcode/skills/에 설치합니다:

cmd skills add addyosmani/agent-skills            # pick skills to install (project)
cmd skills add addyosmani/agent-skills --global   # install for all projects (~/.commandcode/skills/)
cmd skills add addyosmani/agent-skills -s spec-driven-development  # install a specific skill

설치된 스킬은 TUI 슬래시 메뉴에 나타납니다. 예: /spec-driven-development. docs/commandcode-setup.md를 보세요.

다른 에이전트

스킬은 일반 마크다운입니다. 시스템 프롬프트나 지시 파일을 받는 에이전트라면 어디서든 동작합니다. docs/getting-started.md를 보세요. 팩을 설치하지만 위에 없는 호스트는 docs/other-hosts.md에 있습니다.

도입

이미 설치하셨나요? 팩을 롤아웃하는 방법은 코드베이스에 따라 다릅니다. **도입 가이드**는 두 경로를 다룹니다. 그린필드 프로젝트라면 첫날부터 전체 생명주기를 쓰고, 이미 자리 잡은 코드베이스라면 점진적이고 검증을 우선하는 롤아웃을 합니다.

스킬 25개 전체

위의 커맨드는 진입점입니다. 팩에는 스킬이 모두 25개 있습니다. 생명주기 스킬 24개와 메타 스킬 using-agent-skills입니다. 각 스킬은 단계, 검증 게이트, 합리화 방지 표가 있는 구조화된 워크플로우입니다. 어떤 스킬이든 직접 참조할 수도 있습니다.

메타 (Meta) - 어떤 스킬이 적용되는지 찾기

정의 (Define) - 무엇을 만들지 명확히 하기

계획 (Plan) - 쪼개기

구현 (Build) - 코드 작성

검증 (Verify) - 동작함을 증명하기

리뷰 (Review) - 머지 전 품질 게이트

출시 (Ship) - 자신 있게 배포하기

에이전트 페르소나

목적에 맞춘 리뷰를 위한, 미리 구성된 전문가 페르소나입니다.

의사결정 매트릭스, 오케스트레이션 규칙, 페르소나가 스킬 및 슬래시 커맨드와 어떻게 조합되는지는 docs/agents.md를 보세요.

참조 체크리스트

스킬이 필요할 때 가져오는 빠른 참조 자료입니다.

스킬이 동작하는 방식

모든 스킬은 일관된 구조를 따릅니다.

┌─────────────────────────────────────────────────┐
│  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       │
└─────────────────────────────────────────────────┘

핵심 설계 선택:

• 산문이 아니라 절차입니다. 스킬은 에이전트가 읽는 참조 문서가 아니라, 에이전트가 따르는 워크플로우입니다. 각각 단계, 체크포인트, 종료 기준이 있습니다.
• 합리화 방지. 모든 스킬에는 에이전트가 단계를 건너뛸 때 쓰는 흔한 변명 표가 있습니다 (예: "테스트는 나중에 추가하면 된다"). 문서화된 반박도 함께 있습니다.
• 검증은 타협할 수 없습니다. 모든 스킬은 증거 요구로 끝납니다. 테스트 통과, 빌드 출력, 런타임 데이터입니다. "맞아 보인다"는 결코 충분하지 않습니다.
• 점진적 공개. SKILL.md가 진입점입니다. 보조 참조는 필요할 때만 불러와 토큰 사용을 최소로 유지합니다.

프로젝트 구조

이식 가능한 핵심은 공유 디렉터리에 있습니다. 호스트별 경로는 브랜딩용 별칭이 아니라, 도구가 원래 탐색하는 규칙입니다. 이름을 바꾸거나 합치면 그 정확한 위치를 훑는 도구가 깨집니다.

체크인된 어댑터 디렉터리가 없는 도구는 공유 skills/ 핵심을 각자의 네이티브 위치에 설치하거나 복사합니다. 빠른 시작이 지원하는 호스트마다 설정 가이드로 연결합니다.

Agent Skills를 쓰는 이유

AI 코딩 에이전트는 기본적으로 가장 짧은 경로를 택합니다. 그래서 스펙, 테스트, 보안 리뷰, 소프트웨어를 믿을 수 있게 하는 관행을 건너뛰기 쉽습니다. Agent Skills는 시니어 엔지니어가 프로덕션 코드에 가져오는 것과 같은 규율을 강제하는 구조화된 워크플로우를 에이전트에 줍니다.

각 스킬은 어렵게 얻은 엔지니어링 판단을 담습니다. 언제 스펙을 쓸지, 무엇을 테스트할지, 어떻게 리뷰할지, 언제 출시할지입니다. 이것은 일반적인 프롬프트가 아닙니다. 프로덕션 품질의 작업과 프로토타입 품질의 작업을 가르는, 의견이 분명하고 절차로 이끄는 워크플로우입니다.

스킬에는 Google 엔지니어링 문화의 모범 사례가 녹아 있습니다. Software Engineering at Google과 Google의 엔지니어링 관행 가이드에 나온 개념이 포함됩니다. API 설계의 Hyrum's Law, 테스트의 Beyonce Rule과 테스트 피라미드, 코드 리뷰의 변경 크기와 리뷰 속도 기준, 단순화의 Chesterton's Fence, Git 워크플로우의 트렁크 기반 개발, CI/CD의 Shift Left와 피처 플래그, 그리고 코드를 부채로 다루는 지원 종료 스킬을 만날 수 있습니다. 이것은 추상적인 원칙으로 끝나지 않습니다. 에이전트가 따르는 단계별 워크플로우 안에 직접 들어가 있습니다.

비교

Superpowers나 Matt Pocock의 스킬과 어떻게 다른지 궁금하신가요? 셋이 어떻게 다르게 생겼는지, 각각을 언제 쓰면 되는지를 솔직하게 나란히 본 **docs/comparison.md**를 보세요. 통제된 맞대결 실험 링크도 있습니다.

기여

스킬은 구체적이어야 합니다 (모호한 조언이 아니라 실행 가능한 단계). 검증 가능해야 합니다 (증거 요구가 있는 명확한 종료 기준). 실전에서 검증되어야 합니다 (실제 워크플로우에 기반). 최소여야 합니다 (에이전트를 이끄는 데 필요한 것만).

형식 스펙은 docs/skill-anatomy.md, 가이드라인은 CONTRIBUTING.md, 이식 가능한 SKILL.md frontmatter를 깨지 않고 모델 라우팅, 도구 제한, 그 밖의 에이전트별 런타임 제어를 적용하는 방법은 docs/advanced-per-agent-configuration.md를 보세요.

팀

agent-skills를 만들고 유지하는 사람들:

라이선스

MIT. 이 스킬을 프로젝트, 팀, 도구에서 사용할 수 있습니다.