SKILL.md 오픈 표준 · 3단계 점진적 공개 · Cursor / Claude Code 공통 · 원격 Mac 검수
이런 분께 드리는 글입니다. Cursor, Claude Code, Gemini CLI에서 Agent로 코드를 쓰는데 배포 방법, PR 여는 법, 감사 절차를 매번 붙여넣고 계신가요? 컨텍스트는 가득 차고 Token 청구만 늘어납니다.결론: 절차를 Agent Skill(YAML 헤더가 있는 SKILL.md 폴더)로 캡슐화하면 Agent가 필요할 때만 읽고 대화를 넘어 재사용할 수 있습니다. macOS 스크립트나 Xcode 단계가 포함된 Skill은 VNC 원격 Mac 임대로 scripts/ 출력을 검수하는 것이 현실적입니다.구성: Skill vs Rule → 파일 규격 → 3단계 로드 → 생성·마이그레이션 → 모범 사례 → 2026 생태계 → 실전 예 → FAQ.
AI Agent의 진화 경로는 분명합니다. 챗봇 → 작업 보조 → 전문 영역 능력을 갖춘 에이전트. 기존 Prompt에는 세 가지 고통이 있습니다. 복잡한 절차를 매번 다시 설명하는 일, 무관한 Rule이 컨텍스트를 점유하는 일, 팀 노하우가 프로젝트 간 공유되지 않는 일입니다.
Agent Skill은 「어떻게 일을 수행하는지」를 재사용 가능한 모듈로 묶습니다. 필요 시 로드, Token 절약, 대화·팀을 넘는 공유가 가능합니다. Anthropic이 2025년 말 agentskills.io 오픈 표준을 추진한 뒤 Cursor, Claude Code, OpenAI Codex, Gemini CLI가 동일한 SKILL.md 디렉터리 구조를 지원합니다.
한 줄로 말하면, Skill은 AI Agent를 위한 작업 매뉴얼입니다. 매번 처음부터 추론하게 하지 않고, 적절한 시점에 올바른 절차를 실행하게 합니다.
반복 노동: 배포·테스트·PR 설명을 매번 Prompt로 쓰면 한 번에 평균 2k~8k Token을 추가 소비합니다.
컨텍스트 오염: 500줄 규약을 Rules에 넣으면 무관한 파일 편집에도 통째로 실립니다.
버전 관리 불가: 구두 약속은 PR Review가 어렵고, 신입 onboarding은 채팅 복사에 의존합니다.
플랫폼 분절: 같은 배포 절차를 Cursor와 Claude Code에 각각 작성——Skill 표준화 후 Git으로 공유 가능합니다.
| 비교 축 | Rule(규칙) | Skill(스킬) |
|---|---|---|
| 로드 시점 | 항상 로드 | 필요·관련 시에만 |
| 적용 장면 | 영구적 약속(명명, 스타일) | 복잡 워크플로(배포, 감사) |
| 컨텍스트 점유 | 고정 점유 | 동적·효율적 |
| 트리거 | 시스템 프롬프트 자동 주입 | Agent 라우팅 + /skill-name |
| 비유 | 신입 온보딩 규정 | 전문 작업 매뉴얼 |
Skill으로 더 할 수 있는 것: 커스텀 / 명령(예 /deploy), 다단계 워크플로 패키징, 도메인 지식 주입, Bash/Python/Node 스크립트 포함, Hooks·MCP 연동. 사이트의OpenClaw 스킬 시장 실전은 제품 내 플러그인 이야기입니다. 본 글은 에디터 간 공통 Skill 파일 형식을 다루며, 개념은 비슷하지만 생태계는 다릅니다.
표준 디렉터리는 다음과 같습니다(폴더명 = skill 이름):
.cursor/skills/
└── deploy-app/
├── SKILL.md # 필수
├── scripts/ # 선택: 실행 가능 스크립트
│ ├── deploy.sh
│ └── validate.py
├── references/ # 선택: 필요 시 로드 참고 문서
└── assets/ # 선택: 템플릿·정적 리소스호환 경로: .agents/skills/(Claude Code, Codex, Gemini CLI), ~/.cursor/skills/(사용자 전역), ~/.agents/skills/(도구 간 전역).
--- name: deploy-app description: >- 사용자가 staging 또는 production에 앱을 배포하려 할 때 사용. 키워드: 배포, 릴리스, 상용, 환경 전환. paths: - "apps/web/**" disable-model-invocation: false --- # 앱 배포 ## 실행 단계 1. `scripts/validate.py`로 환경 변수 완전성 확인 2. `scripts/deploy.sh <environment>` 실행 3. 헬스체크 엔드포인트가 200을 반환하는지 확인
| 필드 | 필수 | 설명 |
|---|---|---|
| name | 예 | 소문자+하이픈, 폴더명과 일치 |
| description | 예 | 라우팅 키: 트리거 조건 기술(요약 아님) |
| paths | 아니오 | Glob으로 적용 파일 범위 제한 |
| disable-model-invocation | 아니오 | true면 수동 /skill-name만 |
Agent Skills는 점진적 공개(Progressive Disclosure)를 채택합니다. 공식 문서와 agentskills.io는 세 단계로 설명합니다.
발견 단계(시작 시): 각 Skill의 name + description만 읽고 현재 작업과 관련 있는지 판단합니다.
활성화 단계(매칭 시): 전체 SKILL.md 본문을 읽고 단계대로 실행합니다.
온디맨드(실행 중): references/ 상세 문서를 읽고, scripts/ 실행 시 출력만 컨텍스트로 되돌립니다. 스크립트 본문은 Token을 쓰지 않습니다.
트리거 방식: 자동(Agent가 관련 판단, 기본), 수동 /skill-name, 컨텍스트 첨부 @skill-name. 위험 작업 Skill은 disable-model-invocation: true로 사람 확인 후에만 로드합니다.
참고 수치: 2026년 초 커뮤니티 통계상 이용 가능 Skill은 31,000개를 넘습니다. 이를 모두 Rules에 넣으면 한 대화 컨텍스트가 10배 이상 부풀 수 있습니다. 점진적 공개로 Agent는 「많은 매뉴얼이 있다는 것만 알고, 지금 필요한 한 권만 연다」.
가장 빠른 경로: Cursor Agent 대화창에 /create-skill 입력 후 원하는 Skill을 설명하면 Agent가 디렉터리와 SKILL.md를 생성합니다.
수동 생성: .cursor/skills/your-skill-name/에 SKILL.md를 만들고 frontmatter와 단계를 작성합니다.
선택 스크립트: 반복 명령을 scripts/에 두고 본문에서 상대 경로로 참조합니다.
인식 확인: Cursor Settings → Rules 또는 Agent 세션 재시작 후 Skill이 목록에 보이는지 확인합니다.
구 Rule 마이그레이션: Cursor 2.4+에서 /migrate-to-skills로 dynamic rules와 slash commands를 Skill 폴더로 변환합니다.
Windows 주력 개발자가 Cursor에서 Skill을 작성한 뒤 scripts/에 bash, xcodebuild, notarytool이 있으면 로컬에서 진짜 실행이 불가합니다. 권장 흐름: Git으로 원격 Mac 동기화 → VNC로 Cursor 또는 터미널 열기 → Skill 트리거 → exit code와 로그 대조. 키체인, 공증, TCC 권한 단계는 VNC 필수이며, 사이트원격 Mac 권한 체크리스트와 같은 원칙입니다.
① description은 라우팅 키이지 요약이 아닙니다. 잘못: 「이 skill은 배포 관련 지시를 포함」. 올바름: 「사용자가 배포, 상용, staging/production 전환을 언급할 때 사용」.
② 점진적 공개: SKILL.md는 500줄 이내, 상세는 references/, 실행 로직은 scripts/.
③ 단일 책임: Skill 하나는 한 영역. 「배포 + 보안 감사 + 테스트 작성」은 3개 Skill로 나눠 조합합니다.
④ 이유 설명: 「환경 변수 누락으로 서비스 기동 실패를 막기 위해 배포 전 validate.py 실행」처럼 씁니다.
⑤ Gather → Act → Verify: 정보 수집 → 실행 → 검증 순서를 명시하면 Agent가 예외에도 대응을 확장합니다.
⑥ 용어 통일, 경로는 슬래시, 오류 처리 명시: 스크립트 실패 시 재시도·롤백·중단 중 무엇을 택할지 본문에 적습니다.
| 카테고리 | 대표 Skill | 용도 |
|---|---|---|
| 개발 효율 | Prompt Lookup, Skill Installer, Ralph 코딩 루프 | 지시 품질, 다른 Skill 설치, TDD 자율 반복 |
| 프론트/Web | React Best Practices, Web Design Audit, Next.js Cache Optimizer | Vercel 계열 성능·접근성 감사 |
| 워크플로 | PR Skill, TDD Skill, Skill Writer | 커밋→푸시→PR, 테스트 주도, 메타 Skill |
| 크리에이티브 | Remotion Video Editor | React로 영상 기술 후 클립 생성 |
생태계 요점(2026): agentskills.io가 크로스 플랫폼 공통 기반입니다. Cursor Marketplace는 Rules + Skills + MCP 조합을 원클릭 설치합니다. Monorepo에서는 .cursor/skills/shipping/deploy-staging/SKILL.md처럼 중첩해 스코프를 분리할 수 있습니다.
MCP와의 관계: MCP는 외부 API(DB, 브라우저, GitHub)에 연결합니다. Skill은 「언제, 어떤 순서로」 도구를 호출할지 편성합니다. PR Skill에 「먼저 git status, 다음 GitHub MCP로 PR 생성」처럼 쓰면 둘은 보완 관계입니다.
시나리오: 매번 커밋 → 푸시 → PR 생성 → 설명 작성. Skill 지시: 모든 변경 커밋 → 새 브랜치 푸시 → gh pr create → 템플릿으로 설명 작성. /pr 한 번으로 끝.
시나리오: 테스트가 통과할 때까지 코드 반복 수정. Skill 로직: 테스트 실행 → 실패 시 Agent 수정 → 재실행 → 통과까지 루프. Hooks와 결합하면 CI 실패 시 Agent 자동 기동.
시나리오: Windows 개발자가 xcodebuild archive, notarytool submit Skill 유지. 로컬 Cursor는 Markdown 편집만 가능. 진짜 검수는 VNCMac 원격 Mac: VNC 연결 → Skill 트리거 → Agent 스크립트 실행 → 키체인 「항상 허용」 GUI 클릭. 공증 staple 검수 체크리스트와 같은 「SSH만으로는 부족, VNC 필요」 유형입니다.
| 검수 항목 | 로컬 Windows | 원격 Mac + VNC |
|---|---|---|
| SKILL.md 편집 | 가능 | 가능 |
| bash 배포 스크립트 | WSL 일부 가능 | 완전한 macOS 환경 |
| xcodebuild/공증 | 불가 | 필수 |
| 키체인/TCC 대화상자 | 불가 | VNC GUI 클릭 |
Skill은 구조화된 가이드이지 강제 실행이 아닙니다. Model은 여전히 자율 판단합니다. description과 단계가 명확할수록 일관성이 높아집니다. 커뮤니티 Skill 설치 전 scripts/ 내용을 읽으세요.
description의 트리거어로 실제 작업을 테스트하세요. 자동 로드되지 않으면 수동 /skill-name을 시도하고, 실패 시 description 앞부분에 동의어를 추가합니다.
범용 워크플로(커밋, 테스트)는 ~/.cursor/skills/. 저장소 고유(내부 API, 배포 경로)는 .cursor/skills/에 두고 Git 커밋.
형식 철학은 비슷(재사용 가능한 능력 모듈)하지만 OpenClaw는 ClawHub·Gateway 플러그인, Cursor Agent Skill은 SKILL.md + agentskills.io 표준입니다. OpenClaw 7×24 Gateway + Cursor Skill 일상 코딩 병행이 흔합니다.
Agent Skill은 팀 안 「베테랑만 아는」 절차를 버전 관리·Review·크로스 플랫폼 공유 가능한 SKILL.md로 바꿉니다. description에 트리거 조건, 본문에 Gather-Act-Verify, 스크립트는 scripts/로 Token 절약——이 세 가지가 되면 Agent는 「매번 가르치는 대상」에서 「매뉴얼을 펴면 일하는 대상」으로 바뀝니다.
한계도 현실적입니다. macOS 빌드·공증·키체인 Skill은 Windows 로컬에서 쓰기만 가능하고 검증은 어렵습니다. SSH만 원격 Mac은 시스템 대화상자 클릭 불가. Agent를 연중 가동하는 팀에는 Mac mini 구매도 합리적이지만, Skill 라이브러리 구축 중이거나 월간 iOS/macOS 스크립트 검수만 필요하면 VNC 원격 Mac 임대로 「Skill 쓰는 기기」와 「Skill 돌리는 기기」를 나누는 편이 occasional 수요에 하드웨어를 사는 것보다 경제적입니다.
Skill의 가치는 재사용, 재사용 전제는 환경이 돌아가는 것입니다. 아래원격 Mac 요금제에서 macOS 전용 Skill을 VNC로 검수할 노드를 준비하세요.