2026년 들어 AI 코딩 도구가 폭발적으로 늘어나면서 한 가지 고질적인 문제가 생겼어요. 팀이 Cursor를 쓰다가 Claude Code로 옮기면 전에 만들어 둔 커스텀 명령어, 룰, 프롬프트 템플릿을 전부 다시 만들어야 하는 상황이 반복됐거든요. 이 비효율을 해결하기 위해 Anthropic이 2025년 12월에 공개한 Agent Skills 오픈 표준이 2026년 4월부터 본격 확산되고 있어요. GitHub이 gh skill 명령어를 내놓으면서 Copilot, Claude Code, Cursor, OpenAI Codex, Gemini CLI가 같은 형식의 스킬을 공유하는 시대가 열렸습니다.

이 글에서는 Agent Skills 표준의 구조, gh skill 활용법, 내가 직접 스킬을 만드는 실전 예제, MCP(Model Context Protocol)와의 관계, 도구별 지원 현황까지 한 번에 정리해 드릴게요. 이번 주 업계에서 가장 주목받은 바이브코딩·에이전트 인프라 주제라, 팀 리더라면 지금 꼭 따라잡아야 하는 내용이에요.
1. Agent Skills가 왜 지금 등장했을까
지난 1년간 AI 코딩 도구는 각자 자기만의 “커스터마이징 문법”을 만들어 왔어요.
- Cursor:
.cursorrules,.cursor/rules/*.md파일 - Claude Code:
CLAUDE.md,.claude/commands/*.md,.claude/skills/*.md - GitHub Copilot:
.github/copilot-instructions.md, Copilot Custom Instructions - OpenAI Codex:
codex.yaml, Plugin Manifest - Gemini CLI:
.gemini/commands/*.toml
팀이 도구 하나에 깊이 투자하면 락인(lock-in)에 빠졌고, 도구를 바꾸거나 혼용할 때마다 같은 지식을 여러 형식으로 옮겨 적어야 했죠. Cursor 3 에이전트 플랫폼이 나왔을 때 제가 팀원들에게 공유하려다 포기한 이유도 이거였어요. 기존 Claude Code용 커맨드를 Cursor Rules로 다시 번역하는 데 반나절이 걸렸거든요.
Anthropic의 오픈 표준 기부
Anthropic은 2025년 12월 18일에 자사 Claude용으로 만들어 온 “Skills” 형식을 오픈 표준으로 공개했어요. 재미있는 건 이걸 Claude 독점으로 두지 않고 아예 agentskills.io라는 중립 도메인에 스펙을 올렸다는 점이에요. 2026년 1~3월 사이 OpenAI Codex CLI와 GitHub Copilot이 이 스펙을 채택했고, 4월 16일 GitHub이 gh skill CLI를 내놓으면서 사실상 업계 공용 표준의 위치를 굳혔어요.
등장 배경 요약
- 파편화 피로: 팀이 여러 AI 도구를 혼용하면서 같은 규칙을 여러 형식으로 중복 관리하는 부담
- 엔터프라이즈 컴플라이언스: 보안·컴플라이언스 스킬을 한 번 만들어서 모든 도구에 일괄 배포하고 싶다는 요구
- MCP의 한계 보완: MCP가 “도구 접속 규격”이라면 Agent Skills는 “작업 지식 캡슐화 규격”으로 계층이 다른 표준이 필요했음
- 재사용 가능한 지식 자산화: 개별 프롬프트 엔지니어의 암묵지를 팀 자산으로 전환
2. SKILL.md 스펙 핵심 구조
Agent Skills 표준의 기본 단위는 SKILL.md 파일을 담은 폴더예요. 구조는 의외로 단순해요.
my-skill/
├── SKILL.md # 필수 (YAML 프런트매터 + 마크다운 본문)
├── manifest.json # 선택 (권한 선언, 서명)
├── scripts/ # 선택 (스킬이 호출하는 실행 스크립트)
│ └── run.py
├── templates/ # 선택 (마크다운, HTML 템플릿)
└── resources/ # 선택 (참조 문서, 예시 파일)
SKILL.md의 YAML 프런트매터
가장 중요한 건 파일 맨 위의 YAML 프런트매터예요. name과 description은 필수, 나머지는 선택이에요.
---
name: pr-review
description: Pull Request를 시니어 리뷰어 관점에서 검토하고 보안·성능·설계 결함을 찾아 구조화된 코멘트로 정리하는 스킬. PR URL이 주어지거나 리뷰 요청이 있을 때 활성화.
version: 1.2.0
allowed_tools:
- bash
- file_read
- web_fetch
permissions:
network:
- api.github.com
filesystem:
- read: \"**/*\"
- write: \"./.reviews/*.md\"
---
# PR Review Skill
## 사용 시점
- 사용자가 \"이 PR 리뷰해줘\"라고 요청할 때
- PR URL이 메시지에 포함될 때
## 단계
1. gh pr view 로 PR 메타데이터 수집
2. gh pr diff 로 변경 내역 조회
...
가장 중요한 건 description 필드예요. 에이전트가 수많은 설치된 스킬 중에서 어떤 걸 호출할지 결정할 때, 이 설명을 보고 판단해요. “언제 써야 하는지”와 “어떤 입력에 활성화되는지”를 구체적으로 적어야 에이전트가 정확히 매칭해 줘요.
manifest.json 권한 선언
엔터프라이즈 환경에서는 스킬이 어떤 자원에 접근하는지 명시적으로 선언하는 manifest.json이 사실상 필수예요. 설치 시 사용자가 이를 확인하고 승인해야 합니다.
{
\"schema\": \"https://agentskills.io/spec/v1.json\",
\"name\": \"pr-review\",
\"version\": \"1.2.0\",
\"author\": \"therearenorules\",
\"signature\": \"sha256:...\",
\"permissions\": {
\"network\": [\"api.github.com\"],
\"env_vars\": [\"GITHUB_TOKEN\"],
\"exec\": [\"gh\", \"git\"]
},
\"compatibility\": {
\"claude-code\": \">=1.x\",
\"copilot-cli\": \">=2.90\",
\"cursor\": \">=3.5\",
\"codex\": \">=4.16\",
\"gemini-cli\": \">=3.0\"
}
}
3. gh skill 명령어로 설치/관리하기
GitHub CLI v2.90.0부터 추가된 gh skill 명령어는 스킬 관리의 사실상 표준 허브가 됐어요. 공식 체인지로그에 따르면 설치·검색·업데이트·제거·실행을 하나의 CLI로 처리할 수 있어요.
# 설치 & 버전 확인
gh --version # 2.90.0 이상이어야 함
gh skill --help
# 공개된 스킬 검색
gh skill search \"pr review\"
gh skill search --author anthropic
# 설치
gh skill install anthropic/pr-review
gh skill install openai/slack-digest --pin=1.0.3
# 설치 목록 확인
gh skill list
# NAME VERSION AUTHOR SOURCE
# pr-review 1.2.0 anthropic github:anthropics/skills
# slack-digest 1.0.3 openai github:openai/skills
# 스킬 정보 자세히 보기
gh skill show pr-review
# 직접 실행 (CLI에서 즉시 호출)
gh skill run pr-review --target=\"https://github.com/org/repo/pull/123\"
# 업데이트 & 제거
gh skill update pr-review
gh skill uninstall pr-review
프라이빗 레지스트리 + 엔터프라이즈 배포
회사 내부 스킬은 프라이빗 리포지토리나 전용 레지스트리로 배포할 수 있어요.
# 내부 리포지토리에서 설치
gh skill install mycompany/compliance-skills/pii-redactor
# 조직 전체에 자동 배포 (관리자)
gh skill policy set --org mycompany \
--default-install=\"mycompany/compliance-skills/*\" \
--allowed-authors=\"mycompany,anthropic,openai\"
# 설치 감사 로그
gh skill audit --since=2026-04-01
이 구조 덕분에 대기업 보안팀이 “우리 조직 구성원은 검증된 스킬만 설치 가능” 같은 정책을 한 번에 걸 수 있어요. 토큰 취급, 사내 API 호출 스킬을 안전하게 배포할 수 있는 길이 열린 거죠.
4. 첫 번째 Agent Skill 직접 만들어 보기 — 블로그 발행 스킬
이론만 설명하면 감이 안 오니까, 실제로 제가 운영하는 GitHub Copilot CLI 입문 가이드에서도 짚었던 방식대로 “블로그 발행” 스킬을 하나 만들어 볼게요.
4-1. 스킬 폴더 생성
# 로컬에서 작업
mkdir -p ~/skills/blog-publisher/{scripts,templates}
cd ~/skills/blog-publisher
# SKILL.md 작성
cat > SKILL.md << 'EOF'
---
name: blog-publisher
description: WordPress REST API로 블로그 글을 발행하는 스킬. 제목과 카테고리가 주어지면 본문 초안 작성 → 품질 검증 → 발행 → SEO 메타 설정을 순차 수행.
version: 1.0.0
allowed_tools:
- bash
- file_read
- file_write
permissions:
network:
- therearenorules.co.kr
env_vars:
- WP_USER
- WP_APP_PASSWORD
exec:
- python
---
# 블로그 발행 스킬
## 사용 시점
- 사용자가 \"블로그 발행해줘\", \"글 써서 올려줘\"라고 요청할 때
- 제목과 카테고리가 명시된 발행 요청이 있을 때
## 단계
1. 제목과 카테고리 확인 (없으면 사용자에게 질문)
2. 10000-16000자 HTML 본문 작성 (templates/blog-template.md 참고)
3. 자체 품질 검증 (금지어 0, 승인어 3개+, H2 5+)
4. scripts/publish.py 실행해 WP 발행
5. Rank Math SEO 메타 설정
6. 결과 URL 보고
EOF
# 실제 발행 스크립트
cat > scripts/publish.py << 'EOF'
import os, json, urllib.request, base64
# ... 실제 WP REST API 호출 로직
EOF
4-2. manifest.json 권한 선언
cat > manifest.json << 'EOF'
{
\"schema\": \"https://agentskills.io/spec/v1.json\",
\"name\": \"blog-publisher\",
\"version\": \"1.0.0\",
\"permissions\": {
\"network\": [\"therearenorules.co.kr\"],
\"env_vars\": [\"WP_USER\", \"WP_APP_PASSWORD\"],
\"exec\": [\"python\"]
}
}
EOF
4-3. Git 리포지토리로 배포
# 개인/조직 리포지토리로 푸시
cd ~/skills/blog-publisher
git init && git add . && git commit -m \"init blog-publisher skill\"
gh repo create therearenorules/skills --public --source=. --push
# 이제 아무 컴퓨터에서든 설치 가능
gh skill install therearenorules/skills/blog-publisher
4-4. 실전 삽질 포인트
실제로 스킬을 만들어 배포하다가 겪은 시행착오 세 가지를 공유할게요.
- description이 모호하면 활성화 안 됨: 처음에 “블로그 글을 쓰는 스킬”이라고만 적었더니 “블로그 주제로 수다 떨어줘” 같은 엉뚱한 요청에도 활성화됐어요. “WordPress REST API로 발행”처럼 액션 동사 + 대상 + 시점을 구체화해야 정확도가 올라가요.
- env_vars 선언 누락 → 실행 시 권한 거부:
WP_APP_PASSWORD를 manifest에서 빼먹었더니Error: environment variable 'WP_APP_PASSWORD' not declared in skill manifest오류가 났어요. 보안상 엄격한 설계이니 실행 중 사용하는 모든 환경변수를 반드시 선언해야 합니다. - 버전 핀 고정이 유용: 스킬을 업데이트했더니 팀원들 워크플로우가 갑자기 깨졌어요. 프로덕션용으로 쓰는 스킬은
gh skill install ... --pin=1.0.3로 버전 고정해 두세요.
5. MCP vs Agent Skills — 뭐가 다르고 언제 뭘 쓸까
Agent Skills를 배우다 보면 가장 헷갈리는 게 MCP와의 관계예요. 실무자가 자주 묻는 질문이라 표로 정리해 볼게요.
| 항목 | MCP (Model Context Protocol) | Agent Skills |
|---|---|---|
| 핵심 역할 | 에이전트가 외부 데이터/도구에 접속하는 통신 규격 | 에이전트가 반복 작업을 수행하는 방법을 캡슐화한 지식 번들 |
| 비유 | USB-C 포트 (접속 표준) | USB 드라이브에 담긴 프로그램 (실행 콘텐츠) |
| 포함되는 것 | 서버 주소, 툴 목록, 스키마 | SKILL.md, 스크립트, 템플릿, 리소스 파일 |
| 실행 주체 | MCP 서버 (원격 또는 로컬 프로세스) | 에이전트 호스트 (Claude Code, Cursor 등) |
| 주 용도 | DB 쿼리, API 호출, 파일 조작 등 실시간 도구 | PR 리뷰, 문서 작성, 배포 같은 워크플로우 지식 |
| 수명 | 세션 중 계속 연결 | 필요한 시점에 로드되고 작업 종료 시 언로드 |
| 업데이트 | 서버 재시작 필요할 수 있음 | Git 리포지토리 풀로 즉시 반영 |
두 표준의 관계 — 보완재이지 대체재 아님
실제로 괜찮은 스킬은 내부에서 MCP를 호출해요. 예를 들어 “Notion 회의록을 요약해서 Jira 이슈로 만드는 스킬”이라면 Notion MCP와 Jira MCP가 allowed_tools에 명시돼 있고, SKILL.md 지시에 따라 에이전트가 두 MCP를 순차 호출하면서 작업을 수행하죠. MCP가 ‘근육’이라면 Agent Skills는 ‘동작 안무’로 이해하시면 편합니다.
6. 도구별 지원 현황과 실전 차이점
같은 스킬을 설치해도 도구마다 활용하는 방식과 깊이가 조금씩 달라요. 2026년 4월 기준 현황을 정리했어요.
Claude Code
Agent Skills의 원형을 만든 만큼 지원이 가장 깊어요. /skills 슬래시 커맨드로 설치된 스킬을 나열하고, 세션 내 자동 활성화·명시 호출 모두 지원해요. Skills와 네이티브 Tool Use를 조합해 복잡한 에이전틱 플로우를 구성할 수 있어요. 인증 스코프를 프로젝트별로 다르게 적용할 수 있는 점도 장점이에요.
OpenAI Codex
4월 16일 업데이트로 90+ 플러그인이 Agent Skills 스펙과 호환됐어요. Codex는 기본 플러그인 레지스트리에 더해 gh skill로 설치한 스킬도 인식해요. Mac 앱의 컴퓨터 사용 기능과 결합하면 스킬 하나로 “Figma 열기 → 디자인 수정 → Slack 공유” 같은 복합 워크플로우를 에이전트가 스스로 수행하게 할 수 있어요.
Cursor
Cursor는 기존 .cursorrules + Agent 모드 위에 Skills 호환 레이어를 얹었어요. 기존 Cursor Rules 파일은 그대로 쓸 수 있고, 동시에 gh skill로 설치한 외부 스킬도 Agent 모드에서 활성화 가능해요. 다만 manifest.json의 exec 권한은 Cursor 보안 정책 때문에 화이트리스트 기반으로 엄격하게 제한돼요.
GitHub Copilot
Copilot cloud agent + Copilot CLI 양쪽에서 Agent Skills를 지원해요. 특히 cloud agent 쪽은 Copilot CLI 입문 가이드에서 다룬 copilot 커맨드와 결합해 “PR 오픈되면 자동으로 pr-review 스킬 실행” 같은 이벤트 기반 자동화가 가능해요. VS Code Agent Mode에서도 동일한 스킬을 쓸 수 있어요.
Google Gemini CLI
Gemini CLI는 자체 .gemini/commands/*.toml 포맷도 계속 유지하지만, Agent Skills와도 호환돼요. 4월 업데이트로 추가된 Chapters(장 구조) 기능과 결합하면 한 스킬 안에서 여러 단계를 장으로 구분해 관리할 수 있어요. Google Cloud Code Assist에 설치한 스킬은 VS Code 에이전트 모드에서도 동일하게 작동합니다.
7. 엔터프라이즈 도입 체크리스트 8가지
팀/회사 단위로 Agent Skills를 도입할 때 놓치기 쉬운 포인트를 실제 프로젝트 경험에서 뽑아 정리했어요.
- 화이트리스트 저자 정책: 조직 구성원은
mycompany/*,anthropic/*등 검증된 저자 스킬만 설치 가능하도록gh skill policy로 설정 - 서명 검증 의무화:
manifest.json에 서명이 없거나 유효하지 않은 스킬은 설치 거부 - env_vars 최소권한: 스킬이 사용하는 시크릿을 제한된 스코프의 토큰으로 발급 (예: readonly WP 토큰)
- 네트워크 도메인 제한: permissions.network 허용 도메인을 회사 내부 API + 필수 외부 서비스로 좁힘
- 감사 로그 운영:
gh skill audit로 주별 설치/실행 이력을 보관, SIEM에 포워딩 - 버전 핀 + 업데이트 정책: 프로덕션 스킬은 고정 버전, QA 단계 통과 후 승격하는 파이프라인
- 오프보딩 자동화: 구성원이 퇴사하면 개인 시크릿으로 설정된 스킬을 자동 회수
- 내부 스킬 카탈로그: 사내 Confluence/Notion에 승인된 스킬 목록과 사용 사례를 문서화
8. 바이브코딩 팀이 지금 준비해야 할 3단계 로드맵
“일단 써보고 싶은데 어디서부터?” 하는 분들을 위해 실제로 추천하는 3단계 로드맵을 드릴게요.
1주차 — 공개 스킬 탐색 & 설치 리허설
gh upgrade로 CLI 2.90.0+로 업그레이드gh skill search --author anthropic로 공식 예시 스킬 확인anthropic/pr-review,anthropic/doc-writer같은 스타터 스킬 하나를 팀 리포에 설치- Claude Code
/skills또는 Copilot Agent에서 실제 호출해 감 잡기
2~3주차 — 팀 반복 작업 1개를 자체 스킬로 추출
- 팀에서 가장 자주 반복되는 작업 하나 선정 (예: PR 템플릿, 배포 체크리스트, 주간 리포트 생성)
- 기존 프롬프트/문서를 SKILL.md 형식으로 변환
- 프라이빗 리포지토리로 배포, 팀원 2~3명이 일주일간 드라이 런
- 피드백 기반으로
description,permissions조정
4주차~ — 전사 카탈로그 + 컴플라이언스 체계
- 승인된 저자 목록, 서명 정책, 감사 로그 설정을 문서화
- 내부 스킬 10~20개를 목표로 카탈로그 구성
- AI 생성 코드 보안 체크리스트와 연계해 스킬 실행 로그 리뷰 절차 마련
- 분기별 스킬 품질 회고 미팅 도입
마무리 — “한 번 만들고 어디서든 쓴다”의 진짜 의미
Agent Skills 표준의 진짜 가치는 개인의 암묵지를 팀 자산으로, 팀 자산을 조직 전체의 표준으로 확장하는 통로라는 점이에요. 한 사람이 프롬프트 엔지니어링 노하우를 뽑아서 Skill로 만들면 그게 Git으로 관리되고, Copilot·Claude Code·Cursor·Codex·Gemini CLI 모든 환경에서 재사용돼요. 이건 단순한 “편의”가 아니라 AI 도구 도입의 ROI 공식을 바꾸는 구조 변화예요.
2026년 남은 기간 동안 “팀에서 가장 반복되는 작업 하나를 Skill로 만들어 보는 것”이 모든 개발팀의 숙제예요. 이번 주 안에 1주차 체크리스트만 끝내도 팀의 AI 역량 곡선이 확 꺾이는 게 보일 거예요.
Q. Agent Skills와 기존 CLAUDE.md, .cursorrules 파일은 이제 안 써도 되나요?
아니요, 병행 사용이 표준이에요. CLAUDE.md와 .cursorrules는 프로젝트 전역 규칙(톤, 코딩 스타일, 금지 사항)에 적합하고, Agent Skills는 재사용 가능한 특정 작업 단위를 캡슐화해요. 두 가지를 함께 쓰면 전역 지침 위에서 상황별 스킬이 호출되는 2단 구조가 돼요.
Q. 스킬에 포함된 스크립트가 악의적으로 설계되면 어떻게 방어하나요?
세 단계 방어선이 있어요. 첫째, manifest.json의 permissions 선언이 실행 시점에 강제되고 선언되지 않은 자원 접근은 차단돼요. 둘째, 서명 검증으로 배포자 신원을 확인해요. 셋째, 에이전트 호스트마다 샌드박스 실행을 기본으로 적용해요. 그래도 외부 스킬은 저자와 리뷰 수를 확인하고, 엔터프라이즈에서는 내부 포크를 운영하는 걸 권장해요.
Q. 무료로 쓸 수 있나요? 유료 스킬도 있나요?
Agent Skills 스펙 자체는 오픈 표준이고 무료예요. GitHub 공개 리포지토리에 있는 대부분의 스킬은 MIT/Apache 라이선스로 자유롭게 설치·수정할 수 있어요. 다만 일부 전문 스킬(예: 법률 리뷰, 의료 데이터 분석)은 유료 배포가 시작되고 있고, Anthropic이 agentskills.io에서 상업 마켓플레이스 론칭을 예고했어요.
Q. Windows 환경에서도 gh skill이 잘 작동하나요?
네, Windows 네이티브 GitHub CLI에서 정상 작동해요. 다만 스킬 내부 스크립트가 bash 전용 문법을 쓰면 실행이 깨질 수 있으니, 크로스 플랫폼 스킬을 만들 때는 python이나 node로 래핑해 주세요. Windows에서 Python subprocess 호출은 n8n + Gemini 이메일 자동 분류 시스템에서 다룬 cp949 인코딩 이슈와 같은 패턴이 나타날 수 있으니 encoding='utf-8'을 명시해 주세요.
Q. 스킬이 여러 개 활성화되면 충돌이 나지 않나요?
에이전트 호스트가 스킬 간 우선순위를 처리해요. 기본 규칙은 명시적 호출 > description 매칭도 > 최근 사용이에요. 충돌 가능성을 줄이려면 각 스킬의 description을 범위가 겹치지 않게 세밀하게 작성하는 게 중요하고, 비슷한 역할을 하는 스킬이 여러 개라면 하나로 통합하거나 서브 스킬 참조 구조로 재설계하는 게 좋아요.
Q. 에이전트 스킬을 학습해야 할 가장 큰 이유는?
AI 도구 선택은 자주 바뀌지만 Agent Skills는 도구를 넘어 이식되기 때문에 내 스킬 자산이 특정 벤더에 락인되지 않는다는 점이에요. 2026년 하반기에 더 좋은 도구가 나오더라도, 기존에 만든 스킬을 그대로 가져가면 생산성 곡선이 끊기지 않아요. 지식 자산화 관점에서 투자 대비 수익이 가장 좋은 학습 대상이에요.