📋 목차

01 · Agent Skill이 필요한 이유(Prompt 붙여넣기에서 벗어나기)

Cursor·Claude Code 같은 AI 코딩 도우미에서 Agent Skill은 에이전트가 필요할 때 발견·활성화·실행하는 지시 묶음입니다. 매 세션마다 긴 Prompt를 붙이는 방식과 달리, Skill은 SKILL.md로 저장소나 사용자 홈에 남고, 작업 유형이 맞을 때 자동으로 마운트됩니다. 매번 구두로 사내 규정을 설명하는 대신 «업무 매뉴얼»을 배포하는 셈입니다.

반복 Prompt의 한계는 버전 관리 불가, 팀 공유 어려움, 다른 Agent 런타임으로 이식 불가입니다. «PR 설명은 한국어», «배포 전 이 세 명령» 같은 노하우를 Skill에 넣으면 clone한 누구나 같은 동작을 얻습니다. Cursor 2.4+는 Skill을 Rules·MCP와 나란히 두어, 절차·도메인·재현 가능한 워크플로를 Skill에 맡기도록 설계했습니다.

스타트업·SI·게임사 iOS 팀 모두 비슷한 패턴을 겪습니다. 시니어가 Slack에 남긴 «배포 전 체크» 메시지는 검색이 어렵고, Notion 문서는 Agent가 자동으로 열지 않습니다. Skill은 Git diff로 리뷰되므로 «언제·누가·왜 바꿨는지»가 PR과 함께 남습니다. 모델을 Claude에서 GPT로 바꿔도 Skill 폴더만 있으면 행동이 이어집니다.

Mac에서 OpenClaw·OpenHuman 이중 Agent를 쓰는 경우에도 Skill은 «특정 일의 하는 법»만 가르치는 모듈입니다. 항상 켜진 Rule과 외부 API용 MCP와 역할이 겹치지 않게 나누는 것이 중요합니다.

02 · 반복 Prompt의 세 가지 비용

컨텍스트 표류: 같은 경고문이 세션마다 잘리거나 잊혀 정책 위반이 발생합니다. 긴 Prompt는 토큰을 잡아먹어 코드 읽기 공간을 줄입니다.
지식 사일로: 시니어의 배포 체크리스트가 주니어 Agent에 전달되지 않습니다. 개인 «마법 Prompt» 문서만 늘어납니다.
셸 자동화 공포: bash, npm publish, fastlane이 들어간 Skill을 메인 Mac에 맡기기 꺼려집니다. 버릴 수 있는 검증 환경이 없으면 수동 복사로 회귀합니다.

Skill은 Markdown 버전 관리로 앞의 두 문제를 줄입니다. 세 번째는 아래 10절 Mac 임대 5단계로 해결하는 것이 현실적입니다.

03 · Skill vs Rule 비교표

«이 문단은 Rule인가 Skill인가»는 항상 주입 vs 작업 연동으로 판단합니다.

항목	Agent Skill	Cursor Rule
로딩	작업 일치 시 온디맨드	세션 내내 상시
예시	PR 절차, 릴리스 체크, SDK 연동	코딩 스타일, amend 금지
위치	`.cursor/skills/`	`.cursor/rules/`
토큰	관련 작업 때만	상시 후보
담당	DevOps·SDK	아키텍트·규약

매 대화마다 지킬 것 → Rule, 특정 요청 때만 필요한 절차 → Skill입니다. 500줄 배포 매뉴얼을 always-on Rule에 넣지 마세요.

04 · 디렉터리 구조와 SKILL.md 규약

프로젝트 Skill은 .cursor/skills/<name>/SKILL.md, 개인 Skill은 ~/.cursor/skills-cursor/입니다.

                        # 권장 레이아웃

.cursor/skills/deploy-staging/

├── SKILL.md

├── scripts/smoke-test.sh

└── references/rollback.md

frontmatter의 description은 라우팅 키입니다. 발견 단계에서는 name·description만 보이므로 «무엇을·언제·제외»를 구체적으로 씁니다.

                        ---

name: deploy-staging

description: Staging 배포 체크리스트. 사용자가 staging 배포·스모크 테스트를 요청할 때 사용. SSH·npm 포함, production 제외.

---

## 사전 조건

...

한국어 팀이라도 description에 영어 트리거를 섞는 경우가 많습니다. Cursor Agent가 영어·한국어 요청을 모두 라우팅하기 때문입니다. 다만 본문 단계는 팀 모국어로 두면 온보딩이 빨라집니다.

05 · 3단계 점진 로딩

발견: 모든 Skill의 name + description만.
활성화: 매칭된 SKILL.md 전문.
온디맨드: scripts/·references/는 지시 전까지 미로드.

긴 API 문서는 references/로 분리하고 본문은 약 500줄 이내가 권장입니다. 원격 SSH로 검증할 때도 불필요한 토큰은 대역과 시간 낭비입니다.

실무 예: «App Store 심사 제출» Skill은 본문에 12단계만 두고, 스크린샷 규격·export compliance 표는 references/asc-checklist.md로 보냅니다. Agent가 «표를 읽어»라고 할 때만 3단계 로딩이 작동해, 평소 대화 비용이 줄어듭니다.

06 · Skill 만들기(6단계)

방법 A: `/create-skill`

Cursor Agent 채팅에서 /create-skill을 실행하면 용도·트리거·단계를 대화로 정리해 frontmatter 포함 뼈대를 만듭니다.

방법 B: 수동 6단계

단일 책임: Skill 하나는 작업 한 종류.
라우팅 가능한 description: 3인칭·트리거·제외 조건.
SKILL.md 작성: .cursor/skills/your-skill/.
리소스 분리: 긴 문서·셸은 references/·scripts/.
채팅 검증: description에 맞는 요청으로 활성화 확인.
PR·인덱스: README에 Skill 목록.

신규 입사자 온보딩 문서에 «사용 가능 Skill 표»를 링크해 두면, 채팅창에 긴 Prompt를 다시 붙이는 일이 줄어듭니다. 분기마다 사용 빈도가 낮은 Skill은 archive 브랜치로 옮기는 것도 좋습니다.

07 · 모범 사례와 수치

📌 2026년 세 가지 숫자:

agentskills.io에 31,000개 이상 커뮤니티 Skill;
Cursor 2.4+ 네이티브 Skill 발견;
SKILL.md 약 500줄 권장, 초과분은 references로.

파괴적 명령은 본문에 굵게 경고하고, 전역 금지는 Rule, 절차는 Skill에 둡니다. 오래된 Skill은 잘못된 라우팅을 유발하므로 정기 정리가 필요합니다.

CI에 Skill 린트를 넣는 팀도 늘고 있습니다. frontmatter 필수 키 검사, .env·API 키 패턴 차단, scripts/*.sh에 shellcheck — 일반 코드와 동일한 품질 게이트입니다. 오픈소스 Skill을 가져올 때는 description만 한국어로 바꾸고 스크립트는 반드시 diff 리뷰하세요.

08 · 2026 스킬 생태계

Skill은 단일 IDE 팁에서 도구 간 교환 형식으로 진화했습니다. agentskills.io에서 검색·fork한 뒤 사내 브랜치 전략에 맞게 description을 고치는 운영이 일반적입니다. 로컬 OpenClaw 계열 Agent는 Skill로 저장소 절차를 고정하고 MCP로 티켓·DB에 접속하는 패턴이 많습니다.

Xcode 빌드·서명 Skill이라면 Mac mini M4 요금 안내에서 일일 임대와 구매 TCO를 비교하세요.

09 · FAQ: Skill, MCP, 스코프

Skill과 MCP 차이는?

Skill은 절차서(Markdown+선택 스크립트), MCP는 런타임 외부 연동 프로토콜입니다. 프로덕션 DB 실시간 조회는 MCP, 릴리스 전 체크리스트 통일은 Skill입니다.

전역 vs 프로젝트 Skill 위치는?

프로젝트 .cursor/skills/, 개인 ~/.cursor/skills-cursor/. 동명은 보통 프로젝트 우선(Cursor 최신 문서 기준).

Skill이 셸을 자동 실행하나요?

Skill은 «어떻게»를 알려줄 뿐, 터미널 실행은 권한·사용자 확인 대상입니다. 파괴 작업은 description에 명시하고 격리 Mac에서 먼저 시험하세요.

agentskills.io에서 바로 가져올 수 있나요?

대부분 폴더 다운로드나 Git submodule입니다. 가져온 뒤 패키지 매니저(pnpm vs npm), 브랜치 전략(trunk vs gitflow)에 맞게 description과 경로를 고치고, scripts/ 안의 curl·bash를 신뢰하지 마세요.

SSH·VNC·요금은 일일 Mac 임대 가이드(FAQ)를 참고하세요.

10 · Mac 임대로 스크립트 Skill 격리 검증(5단계)

npm test, docker compose, fastlane 서명 등이 Skill에 있으면 메인 Mac 전자동 실행은 피하는 것이 좋습니다.

노드 임대: Apple Silicon·Xcode 포함 macOS(Mac mini M4 등)를 SSH/VNC로 접속.
격리 clone: 읽기 전용 토큰으로 복제, 프로덕션 비밀 분리.
대상 Skill만 활성화: 실험 Skill 비활성화로 변수 축소.
로그 보존: 종료 코드·stdout을 증적으로 남기고 Skill 쪽 수정.
머지 후 반납: PR 병합 뒤 인스턴스 해제로 과금 중단.

Linux VPS만으로는 Xcode·iOS 서명·공증·Keychain 재현이 어렵습니다. Windows 클라우드 + WSL로 Node Skill 일부는 돌아가지만, TestFlight·notarization·CocoaPods 경로 이슈로 야근이 늘어나는 사례가 많습니다. 프로덕션과 같은 macOS에서 시험하는 일일 임대가 비용 대비 유리한 경우가 많습니다.

MacDate 노드는 독립 IP·데이터센터 대역을 제공해 대용량 로그 업로드·VNC 화면 공유 시 끊김이 적습니다. 1~3일 파일럿으로 Skill 스모크 테스트 → 통과 시 팀 저장소에 merge → 인스턴스 반납, 이 리듬이 가장 흔한 성공 패턴입니다. 단가·M4 Pro 차액은 M 시리즈 요금 페이지를 보세요.