AI 에이전트를 시니어 개발자로 만드는 법: agent-skills + Cursor 윈도우 완전 세팅 가이드
이 글은 Google 엔지니어링 디렉터 Addy Osmani의 오픈소스 프로젝트 agent-skills (⭐ 43.1k, 2026.06 기준)의 공식 문서와 실제 소스코드를 직접 확인하여 작성했습니다.
🤔 왜 agent-skills인가?
Cursor로 개발하다 보면 이런 상황이 자주 발생합니다.
- 설계 논의도 없이 바로 코드를 뚝딱 만들어 버림
- 테스트 코드는 "나중에 쓸게요" 하고 영원히 안 씀
- 100줄 수정 요청에 1000줄짜리 괴물 PR을 만들어 옴
agent-skills는 이 문제를 해결하기 위해 탄생했습니다. AI 에이전트가 Google 엔지니어링 문화에서 검증된 시니어 개발자의 업무 프로토콜을 따르도록 강제하는 구조화된 워크플로우 모음입니다.
*"Skills encode the workflows, quality gates, and best practices that senior engineers use when building software."*
— agent-skills README
현재 총 23개의 스킬이 개발 생명주기(Define → Plan → Build → Verify → Review → Ship) 전 단계를 커버합니다.
📁 저장소 구조 먼저 파악하기
실제 저장소는 아래와 같이 구성되어 있습니다. 이 구조를 알아야 어디서 뭘 가져다 쓸지 알 수 있습니다.
agent-skills/
├── skills/ ← 핵심! 23개의 SKILL.md 파일들
│ ├── incremental-implementation/SKILL.md
│ ├── test-driven-development/SKILL.md
│ ├── code-review-and-quality/SKILL.md
│ ├── spec-driven-development/SKILL.md
│ ├── planning-and-task-breakdown/SKILL.md
│ ├── security-and-hardening/SKILL.md
│ ├── performance-optimization/SKILL.md
│ └── ... (총 23개)
├── agents/ ← 전문 페르소나 (code-reviewer, test-engineer, security-auditor)
├── references/ ← 체크리스트 (testing, security, performance, accessibility)
├── .claude/commands/← Claude Code 전용 슬래시 커맨드 7개
├── hooks/ ← 세션 라이프사이클 훅
└── docs/ ← 도구별 세팅 가이드
├── cursor-setup.md ← 우리가 볼 파일
├── gemini-cli-setup.md
├── windsurf-setup.md
└── ...
각 SKILL.md 파일은 단순한 팁 모음이 아닙니다. 실행 가능한 단계별 워크플로우 + 안티 패턴 반박 테이블 + 검증 체크리스트로 구성된 정교한 프롬프트 문서입니다.
🛠️ Step-by-Step: 윈도우 세팅 가이드
Step 1. 저장소 클론
PowerShell을 열고 원하는 경로에 저장소를 클론합니다.
# 예: C:\dev\agent-skills 에 클론
git clone https://github.com/addyosmani/agent-skills.git C:\dev\agent-skills
git이 없다면 GitHub에서 Code → Download ZIP으로 다운로드 후 압축 해제해도 됩니다.
Step 2. Cursor 규칙 폴더 생성
작업 중인 프로젝트 루트로 이동해서 Cursor 전용 규칙 폴더를 만듭니다.
# 내 프로젝트 폴더로 이동
cd C:\Projects\MyProject
# .cursor/rules/ 폴더 생성 (-p 없이도 PowerShell mkdir은 중첩 폴더 자동 생성)
mkdir .cursor\rules
Step 3. Essential Skills — 핵심 3개 복사
공식 문서(docs/cursor-setup.md)가 상시 로드(Always Load) 를 권장하는 핵심 스킬은 정확히 3개입니다.
# 1. 점진적 구현 — 한 번에 코드 뭉텅이 뱉는 것 방지
copy C:\dev\agent-skills\skills\incremental-implementation\SKILL.md `
.cursor\rules\incremental-implementation.md
# 2. TDD — 테스트 없이 PR 날리는 것 방지
copy C:\dev\agent-skills\skills\test-driven-development\SKILL.md `
.cursor\rules\test-driven-development.md
# 3. 코드 리뷰 — 머지 전 5축 품질 게이트 적용
copy C:\dev\agent-skills\skills\code-review-and-quality\SKILL.md `
.cursor\rules\code-review-and-quality.md
완료되면 프로젝트 구조가 이렇게 됩니다.
MyProject/
├── .cursor/
│ └── rules/
│ ├── incremental-implementation.md ← 상시 로드
│ ├── test-driven-development.md ← 상시 로드
│ └── code-review-and-quality.md ← 상시 로드
└── ... (기존 프로젝트 파일들)
⚠️ 중요: .cursor/rules/ 폴더의 파일들은 Cursor가 자동으로 컨텍스트에 로드합니다. 파일명은 자유롭게 지어도 되지만, 내용은 반드시 원본 SKILL.md를 그대로 사용하세요. 내용을 직접 창작하면 agent-skills의 구체적인 워크플로우와 반박 테이블을 잃게 됩니다.
Step 4. Commands 세팅 — 상황별 스킬 온디맨드 호출
⚠️ 중요: Cursor의 Notepads 기능은 2025년 10월 말 Cursor 2.0 출시와 함께 완전히 폐기되었습니다. 현재 Cursor 최신 버전(3.x)에는 존재하지 않습니다.
모든 스킬을 .cursor/rules/에 넣으면 Cursor의 컨텍스트 한도 초과로 성능이 저하됩니다. 상황별로 필요한 스킬만 불러올 수 있는 현재 공식 대안은 커스텀 슬래시 커맨드(.cursor/commands/)입니다.
.cursor/commands/ 디렉토리에 Markdown 파일을 생성하면 파일명이 슬래시 커맨드 이름이 되고, 파일 내용이 프롬프트 템플릿으로 사용됩니다. 글로벌(전 프로젝트 공통)로 쓰려면 ~/.cursor/commands/에 저장합니다.
Commands 폴더 생성:
# 프로젝트 루트에 commands 폴더 생성 (-p 옵션 없이도 중첩 폴더 자동 생성됨)
mkdir .cursor\commands
스킬을 커맨드 파일로 복사:
# 보안 검토 커맨드
copy C:\dev\agent-skills\skills\security-and-hardening\SKILL.md `
.cursor\commands\security.md
# 성능 최적화 커맨드
copy C:\dev\agent-skills\skills\performance-optimization\SKILL.md `
.cursor\commands\performance.md
# 스펙 작성 커맨드
copy C:\dev\agent-skills\skills\spec-driven-development\SKILL.md `
.cursor\commands\spec.md
# 프론트엔드 UI 커맨드
copy C:\dev\agent-skills\skills\frontend-ui-engineering\SKILL.md `
.cursor\commands\frontend.md
사용 방법: Cursor 채팅창에서 /를 입력하면 등록된 커맨드 목록이 드롭다운으로 표시됩니다.
/security 이 로그인 API의 보안 취약점을 검토해줘.
/performance 이 목록 조회 쿼리의 성능 문제를 분석해줘.
/spec 결제 만료 알림 기능의 PRD를 작성해줘.
| 커맨드 파일명 |
원본 SKILL.md 경로 |
호출 방법 |
사용 시점 |
security.md |
skills/security-and-hardening/SKILL.md |
/security |
인증/입력처리/배포 전 |
performance.md |
skills/performance-optimization/SKILL.md |
/performance |
성능 개선/리팩토링 시 |
spec.md |
skills/spec-driven-development/SKILL.md |
/spec |
새 기능/프로젝트 설계 시 |
frontend.md |
skills/frontend-ui-engineering/SKILL.md |
/frontend |
UI 컴포넌트 작업 시 |
Step 5. .cursorrules 방식 (선택 대안)
프로젝트 루트에 .cursorrules 단일 파일로 여러 스킬을 합치는 방법도 있습니다.
팀 협업 시 .cursor/rules/ 폴더 구조 관리가 번거롭다면 이 방식을 고려하세요.
# PowerShell에서 3개 스킬을 하나의 .cursorrules 파일로 합치기
Get-Content C:\dev\agent-skills\skills\test-driven-development\SKILL.md |
Out-File .cursorrules -Encoding utf8
"`n---`n" | Out-File .cursorrules -Append -Encoding utf8
Get-Content C:\dev\agent-skills\skills\code-review-and-quality\SKILL.md |
Out-File .cursorrules -Append -Encoding utf8
"`n---`n" | Out-File .cursorrules -Append -Encoding utf8
Get-Content C:\dev\agent-skills\skills\incremental-implementation\SKILL.md |
Out-File .cursorrules -Append -Encoding utf8
.cursorrules와 .cursor/rules/를 동시에 사용하면 충돌이 생길 수 있으니 둘 중 하나만 선택하세요.
🎯 실전 활용: 스킬을 명시적으로 호출하기
규칙 파일이 자동 로드된다고 해서 AI가 항상 알아서 따르지는 않습니다. 공식 Usage Tips에 이렇게 명시되어 있습니다.
*"Reference skills explicitly — Tell Cursor 'Follow the test-driven-development rules for this change' to ensure it reads the loaded rules."*
— docs/cursor-setup.md
스킬별 실전 프롬프트 패턴:
새 기능 구현 시 (incremental-implementation)
incremental-implementation 스킬을 따라서 결제 만료 알림 기능을 구현해줘.
한 번에 다 짜지 말고, 수직 슬라이스 단위로 쪼개서 각 단계마다
빌드와 테스트를 검증한 후 다음으로 넘어가.
버그 수정 시 (test-driven-development)
test-driven-development 스킬의 Prove-It Pattern을 따라서
이 버그를 수정해줘. 먼저 버그를 재현하는 실패 테스트를 작성하고,
그 테스트가 통과하도록 수정해.
머지 전 리뷰 (code-review-and-quality)
code-review-and-quality 스킬의 Five-Axis Review를 적용해서
이 변경사항을 검토해줘. 각 피드백에 Critical / Nit / Optional 레이블을 붙여줘.
보안 검토가 필요할 때 (Commands)
/security 이 로그인 API의 보안 취약점을 OWASP Top 10 기준으로 검토해줘.
📊 전체 23개 스킬 한눈에 보기
agent-skills가 제공하는 전체 스킬 목록입니다. .cursor/rules/에 상시 로드할지, .cursor/commands/ 로 필요할 때만 호출할지 구분해서 정리했습니다.
| 단계 |
스킬 |
역할 |
관리 방식 |
| Meta |
using-agent-skills |
어떤 스킬을 쓸지 매핑 |
.cursor/commands/ |
| Define |
interview-me |
요구사항 인터뷰 |
.cursor/commands/ |
| Define |
idea-refine |
아이디어 구체화 |
.cursor/commands/ |
| Define |
spec-driven-development |
PRD 작성 |
.cursor/commands/ |
| Plan |
planning-and-task-breakdown |
태스크 분해 |
.cursor/commands/ |
| Build |
incremental-implementation |
점진적 구현 |
✅ .cursor/rules/ 상시 로드 |
| Build |
test-driven-development |
TDD 사이클 |
✅ .cursor/rules/ 상시 로드 |
| Build |
context-engineering |
컨텍스트 최적화 |
.cursor/commands/ |
| Build |
source-driven-development |
공식 문서 기반 코딩 |
.cursor/commands/ |
| Build |
doubt-driven-development |
고위험 결정 재검토 |
.cursor/commands/ |
| Build |
frontend-ui-engineering |
UI 컴포넌트 |
.cursor/commands/ |
| Build |
api-and-interface-design |
API 설계 |
.cursor/commands/ |
| Verify |
browser-testing-with-devtools |
DevTools 디버깅 |
.cursor/commands/ |
| Verify |
debugging-and-error-recovery |
버그 트리아지 |
.cursor/commands/ |
| Review |
code-review-and-quality |
5축 코드 리뷰 |
✅ .cursor/rules/ 상시 로드 |
| Review |
code-simplification |
코드 단순화 |
.cursor/commands/ |
| Review |
security-and-hardening |
OWASP 보안 |
.cursor/commands/ |
| Review |
performance-optimization |
성능 최적화 |
.cursor/commands/ |
| Ship |
git-workflow-and-versioning |
트렁크 기반 Git |
.cursor/commands/ |
| Ship |
ci-cd-and-automation |
CI/CD 파이프라인 |
.cursor/commands/ |
| Ship |
deprecation-and-migration |
레거시 제거 |
.cursor/commands/ |
| Ship |
documentation-and-adrs |
ADR 문서화 |
.cursor/commands/ |
| Ship |
shipping-and-launch |
배포 체크리스트 |
.cursor/commands/ |
💡 핵심 개념 3가지 — 스킬이 왜 효과적인가
agent-skills의 SKILL.md들이 단순한 "지시문"과 다른 이유가 있습니다. 실제 파일을 열어보면 공통된 설계 철학이 보입니다.
1. 안티 합리화 테이블 (Anti-rationalization)
AI가 단계를 건너뛰려 할 때 내놓는 변명들을 미리 반박합니다.
| AI의 변명 |
실제 현실 |
| "마지막에 한꺼번에 테스트할게요" |
Slice 1의 버그가 Slice 2~5를 전부 오염시킵니다 |
| "한 번에 다 짜는 게 더 빠릅니다" |
500줄 중 어디서 터진지 모를 때 체감됩니다 |
| "이 리팩토링은 같이 넣어도 작아요" |
피처와 리팩토링이 섞이면 리뷰도, 롤백도 불가능합니다 |
2. 검증 게이트 (Verification Gates)
각 스킬의 마지막엔 반드시 "증거 요구사항"이 있습니다. "잘 된 것 같아요"는 완료가 아닙니다.
3. 레드 플래그 (Red Flags)
문제의 징조를 명시합니다. 예를 들어 incremental-implementation의 Red Flags:
- 테스트 실행 없이 100줄 이상 작성
- 한 인크리먼트에 여러 관심사 혼재
- "이것도 빠르게 추가할게요" 스코프 크리프
⚙️ 최종 세팅 요약
MyProject/
├── .cursor/
│ ├── rules/ ← Cursor 자동 로드 (상시)
│ │ ├── incremental-implementation.md
│ │ ├── test-driven-development.md
│ │ └── code-review-and-quality.md
│ └── commands/ ← 슬래시 커맨드 온디맨드 호출
│ ├── security.md → /security
│ ├── performance.md → /performance
│ ├── spec.md → /spec
│ └── frontend.md → /frontend
└── ... (기존 프로젝트 파일들)
| 관리 방식 |
대상 스킬 |
활성화 방법 |
사용 시점 |
.cursor/rules/ |
핵심 3개 |
자동 로드 |
항상 |
.cursor/commands/ |
나머지 20개 |
/커맨드명 입력 |
해당 작업 시 |
🔗 참고 링크