오픈 표준 v1.x
TECH
Agent Skills, Claude 전용 아닌 게 핵심입니다
Claude Code에서 시작한 SKILL.md 포맷이 이제 Codex CLI·Cursor·Gemini CLI·GitHub Copilot까지 10개 이상 플랫폼에서 그대로 작동합니다. 한 번 만들면 어디서든 씁니다.
Agent Skills가 뭔지 정확히 짚고 넘어가겠습니다
2025년 10월, Anthropic은 Claude Code에 Agent Skills라는 기능을 정식 출시했습니다. 그리고 같은 해 12월 이 포맷을 오픈 표준으로 공개했는데, 그로부터 두 달도 안 돼서 OpenAI·Cursor·GitHub Copilot이 조용히 지원을 추가했습니다. (출처: inference.sh 공식 블로그, 2026.02.27)
구조는 놀라울 만큼 단순합니다. SKILL.md 파일 하나가 담긴 폴더가 전부입니다. 이 파일에 이름·설명(YAML 프런트매터)과 에이전트가 따를 절차(마크다운 본문)를 넣으면 끝입니다. 모델 파인튜닝도, 별도 서버도, 플러그인 SDK도 필요하지 않습니다.
쉽게 말하면 신입 직원 온보딩 문서를 AI 에이전트용으로 쓴 것과 같습니다. “이 업무는 이런 흐름으로 처리해라”를 파일로 정리해두면 에이전트가 알아서 읽고 따릅니다. 그리고 그 파일이 Claude에서도 Cursor에서도 Codex에서도 동일하게 작동합니다.
💡 공식 발표문과 실제 채택 현황을 같이 놓고 보니 이런 차이가 보였습니다. Anthropic이 “오픈 표준”을 선언한 것과 OpenAI가 실제로 채택한 시점이 두 달 차이밖에 나지 않습니다. MCP(Model Context Protocol)가 채택 속도에 수개월 걸렸던 것과 비교하면 훨씬 빠릅니다. 포맷 자체가 단순해서 진입 장벽이 낮기 때문입니다.
SKILL.md 구조 — 생각보다 단순합니다
스킬 하나는 아래 디렉토리 구조를 따릅니다. 필수는 SKILL.md 하나, 나머지는 전부 선택입니다. (출처: OpenAI Codex 공식 문서, developers.openai.com/codex/skills)
my-skill/
├── SKILL.md ← 필수: 지침 + 메타데이터
├── scripts/ ← 선택: 실행 가능한 코드
├── references/ ← 선택: 참조 문서
├── assets/ ← 선택: 템플릿·리소스
└── agents/
└── openai.yaml ← 선택: UI 메타데이터(Codex 앱 전용)SKILL.md 파일의 최소 구성은 다음과 같습니다.
---
name: my-code-review
description: >
PR 제출 전 코드 리뷰 체크리스트를 실행한다.
보안·성능·가독성 3개 항목을 순서대로 점검한다.
## 코드 리뷰 절차
1. 보안: SQL 인젝션·하드코딩된 비밀값 여부 확인
2. 성능: 불필요한 루프 중첩·N+1 쿼리 패턴 탐지
3. 가독성: 함수 길이 50줄 초과 여부, 의미 없는 변수명 지적description 필드가 실제로 가장 중요합니다. 에이전트가 어떤 작업에 이 스킬을 써야 할지 판단하는 기준이 이 설명이기 때문입니다. 범위가 모호하면 엉뚱한 상황에서 스킬이 자동 실행되거나 반대로 써야 할 때 안 써집니다.
스킬 저장 위치는 에이전트마다 다릅니다
| 에이전트 | 사용자 레벨 경로 | 프로젝트 레벨 경로 |
|---|---|---|
| Claude Code | ~/.claude/skills/ |
.claude/skills/ |
| Codex CLI | ~/.agents/skills/ |
.agents/skills/ |
| Cursor | – | .cursor/skills/ |
| GitHub Copilot | ~/.copilot/skills/ |
.github/skills/ |
경로가 달라도 npx skills add 명령어를 쓰면 선택한 모든 에이전트에 자동으로 심볼릭 링크가 생성됩니다. 수동으로 각각 복사할 필요가 없습니다.
스킬이 많아질수록 무거워질 것 같지만, 실제론 다릅니다
스킬을 수십 개 설치하면 시작할 때마다 컨텍스트 창이 꽉 찰 것 같습니다. 막상 써보니 그렇지 않았습니다. 구조가 이 문제를 처음부터 고려해서 설계되었기 때문입니다.
💡 실제 토큰 사용 흐름을 같이 보면 이렇습니다
에이전트는 시작 시 각 스킬의 name과 description만 읽습니다. 스킬당 약 100토큰입니다. 스킬 30개를 설치해도 시작 시 소비되는 토큰은 3,000토큰 수준이고, 실제 작업과 관련된 스킬 전문 내용은 그 작업을 시작할 때만 불러옵니다. (출처: inference.sh 공식 블로그, 2026.02.27)
이 구조를 점진적 공개(Progressive Disclosure)라고 부릅니다. 3단계로 작동합니다.
발견 단계
이름·설명만 읽음. 스킬당 약 100토큰 소비.
활성화 단계
작업이 스킬 설명과 매칭되면 SKILL.md 전체 로드.
실행 단계
추가 파일(스크립트·참조 문서)은 필요할 때만 로드.
이 구조 덕분에 스킬이 없으면 오히려 없는 셈이라는 말이 정확합니다. 매번 프롬프트에 코드 리뷰 기준을 붙여 넣거나 배포 절차를 설명하는 대신, 해당 작업이 시작될 때만 정확히 필요한 내용이 들어옵니다.
skills.sh에서 바로 설치할 수 있는 스킬들
스킬을 하나씩 직접 만들 필요는 없습니다. skills.sh에 이미 수천 개의 공개 스킬이 있고, 설치 명령어 한 줄이면 됩니다. 실제로 써본 것들 기준으로 분류했습니다.
능력 확장형 — 원래 못 하던 걸 가능하게 만드는 스킬
| 스킬명 | 실제로 하는 일 | 설치 명령 |
|---|---|---|
| pdf / docx / xlsx / pptx | 실제 파일 생성·파싱 (텍스트 설명 아님) | npx skills add anthropics/skills --skill pdf |
| webapp-testing | Playwright로 로컬 앱 실제 브라우저 테스트 | npx skills add anthropics/skills --skill webapp-testing |
| trailofbits 보안 스킬 | CodeQL·Semgrep 기반 실제 취약점 분석 | npx skills add trailofbits/skills |
방식 인코딩형 — 이미 하는 일을 팀 방식대로 하게 만드는 스킬
| 스킬명 | 실제로 하는 일 | 주간 설치 수 |
|---|---|---|
| frontend-design | Inter·Roboto 금지, 의도적 디자인 방향 강제 | 110,000+ |
| web-design-guidelines | 100개 이상 접근성·UX 규칙 자동 점검 | 133,000+ |
| vercel-react-best-practices | 57개 성능 규칙, 충격도 순으로 적용 | 공개 수치 없음 |
| remotion-best-practices | React 기반 영상 제작 패턴 전문화 | 117,000+ |
(출처: Firecrawl 공식 블로그, 2026.03.13 기준 설치 수)
MCP와 뭐가 다른가요 — 헷갈리는 사람 많습니다
MCP(Model Context Protocol)와 Agent Skills를 혼동하는 경우가 많습니다. 둘 다 에이전트에 능력을 추가하는 방식이지만 작동 원리가 다릅니다.
| 구분 | Agent Skills | MCP 서버 |
|---|---|---|
| 형태 | 폴더 + 마크다운 파일 | 실행 중인 서버 프로세스 |
| 설치 난이도 | 명령어 한 줄 | 서버 구축·호스팅 필요 |
| 특기 | 절차적 지식, 워크플로 인코딩 | 실시간 API·DB 연동 |
| 컨텍스트 부담 | 시작 시 스킬당 약 100토큰 | 도구 정의 전체를 선불 로드 |
| 이식성 | Claude Code·Codex·Cursor·Copilot 등 공통 | MCP 지원 클라이언트만 |
가장 실용적인 조합은 둘을 함께 쓰는 것입니다. “어떻게 해야 하는가”는 Agent Skills로, “실시간 데이터에 접근하는 것”은 MCP 서버로 분리하면 됩니다. Anthropic 공식 문서도 이 조합을 권장합니다. (출처: inference.sh/blog/skills, 2026.02.27)
💡 개발자들이 “MCP가 죽었다”는 말을 꺼낼 때 배경이 이겁니다. Agent Skills가 MCP가 담당하던 절차적 지식 부분을 더 간단하게 대체할 수 있기 때문입니다. 실시간 연동이 필요 없는 사용 사례는 Skills로 이미 충분합니다.
직접 만들면 어디에서 써야 제일 남는지
공개 스킬이 아닌 팀 전용 스킬을 만들 때 진짜 가치가 납니다. 구체적으로 세 가지 상황에서 투자 대비 효과가 높습니다.
매번 반복 설명하는 것
PR 제출 전 체크리스트, 커밋 메시지 형식, 코드 리뷰 기준처럼 매 세션마다 AI에게 다시 설명하던 내용을 스킬로 한 번만 정리하면 됩니다.
조직 고유의 지식
사내 API 연동 방식, 배포 파이프라인 순서, 특정 보안 정책처럼 외부에 공개할 수 없지만 팀 내에선 반드시 필요한 절차들입니다.
AI 출력이 아쉬울 때
Inter 폰트, 보라색 그라디언트, 카드 레이아웃을 뽑아내는 AI 특유의 “범용 출력”을 막을 때 Encoded Preference 스킬을 씁니다.
Anthropic 공식 skill-creator 스킬로 만드는 법
스킬을 처음 만들 때 빈 파일 앞에서 막히는 경우가 많습니다. Anthropic이 만든 skill-creator 스킬을 쓰면 대화형 Q&A로 구조가 완성됩니다.
# skill-creator 설치
npx skills add anthropics/skills --skill skill-creator
# 설치 후 Claude Code에서
$skill-creator
# → 어떤 작업을 자동화할지, 언제 트리거할지,
# 스크립트가 필요한지 등을 묻고 SKILL.md를 생성해줌만들고 나면 npx skills add ./my-skill-folder 로 설치하거나 GitHub 저장소에 올려서 팀과 공유할 수 있습니다.
한 가지 주의할 점 — 포터빌리티가 완전하진 않습니다
“한 번 만들면 어디서든 작동한다”는 게 Agent Skills의 핵심 약속입니다. 그런데 실제로 170개 스킬을 9개 도메인에 걸쳐 만들고 테스트한 사람의 경험은 조금 달랐습니다.
⚠️ 플랫폼 간 실제 차이
Claude Code에서 완벽하게 작동하던 마케팅 콘텐츠 감사 스킬을 Codex CLI로 옮겼더니, 파일 유형 기반 자동 트리거가 작동하지 않았습니다. 점진적 공개가 제대로 구현되지 않아 참조 파일 전체가 컨텍스트에 한꺼번에 올라왔고 토큰 소비가 3배로 늘었습니다. (출처: Medium — Alireza Rezvani, 2026.03.13)
이유는 각 플랫폼이 표준 스펙을 완전히 동일하게 구현하지 않았기 때문입니다. 2026년 3월 기준 SKILL.md 호환 도구로 주장하는 곳은 Claude Code·Codex CLI·Gemini CLI·Cursor·Windsurf·Kilo Code 등 10개 이상이지만, 구현 수준에는 차이가 있습니다.
실용적인 대응 방법은 두 가지입니다. 첫째로 가장 많이 쓰는 에이전트 하나를 기준으로 테스트하고 다른 플랫폼은 보너스로 여기는 것, 둘째로 스킬 내에서 플랫폼별 암묵적 트리거에 의존하지 않고 명시적 호출($스킬명)을 쓰도록 워크플로를 설계하는 것입니다.
💡 보안도 짚고 넘어가겠습니다. 스킬은 그냥 텍스트 파일이기 때문에 악의적인 스킬이 에이전트를 의도치 않은 방향으로 유도할 수 있습니다. skills.sh의 공식 검증 스킬이나 GitHub 스타 수가 높은 저장소 것을 우선 쓰고, 출처가 불분명한 스킬은 SKILL.md 전체를 읽은 후 사용하는 것이 기본 원칙입니다.
Q&A
Q1. Agent Skills를 쓰려면 유료 플랜이어야 하나요?
Claude Code 자체는 Claude Pro 이상 플랜에서 사용할 수 있습니다. 그러나 Agent Skills 오픈 표준과 skills.sh는 Cursor·Codex CLI·GitHub Copilot 등 다른 도구에서도 사용 가능하므로, 어떤 에이전트를 쓰냐에 따라 다릅니다. GitHub Copilot의 Agent Skills 지원은 VS Code 확장 프로그램에서 별도 설정으로 활성화할 수 있습니다(2025년 12월부터 실험적 지원).
Q2. 설치한 스킬이 언제 작동하는지 어떻게 알 수 있나요?
Claude Code에서는 ~/.claude/skills/ 경로에 있는 스킬이 시작 시 자동 감지됩니다. 에이전트에게 “설치된 스킬 목록을 보여줘”라고 물어보거나 npx skills list 명령어로 확인할 수 있습니다. 스킬이 자동 실행됐는지 알고 싶다면 대화 흐름에서 에이전트가 스킬 지침을 따르는 패턴을 보면 됩니다.
Q3. Claude.md(CLAUDE.md)와 SKILL.md는 뭐가 다른가요?
CLAUDE.md는 항상 컨텍스트에 포함되는 프로젝트 전체 지침입니다. 반면 SKILL.md는 작업이 매칭될 때만 로드됩니다. 자주 쓰이는 전역 지침은 CLAUDE.md로, 특정 작업 유형에만 필요한 전문 지식은 Skills로 분리하는 게 효율적입니다.
Q4. 스킬을 팀에서 공유하려면 어떻게 하나요?
가장 간단한 방법은 스킬 폴더를 Git 저장소에 포함시키는 것입니다. 프로젝트 레벨 경로(.agents/skills/)에 넣으면 저장소를 클론한 모든 팀원이 동일한 스킬을 쓸 수 있습니다. skills.sh를 통해 공개 배포하려면 GitHub 저장소에 올리고 skills.sh에 등록하면 됩니다.
Q5. 스킬이 충돌하면 어떻게 되나요?
스킬은 에이전트의 기본 동작을 대체하는 게 아니라 추가합니다. 여러 스킬이 동시에 매칭될 때 에이전트는 설명을 기반으로 가장 적합한 것을 선택하거나 복수를 로드합니다. 충돌이 생긴다면 두 스킬의 description이 너무 비슷한 경우가 많습니다. 하나로 합치거나 설명 범위를 더 명확하게 나누면 해결됩니다. (출처: inference.sh FAQ, 2026.02.27)
마치며
Agent Skills를 처음 접할 때 가장 자주 듣는 반응이 “Claude에서만 쓰는 거잖아요”입니다. 써보니까 그렇지 않습니다. 이미 Codex CLI·Cursor·GitHub Copilot·Gemini CLI까지 같은 SKILL.md를 읽습니다. 어떤 에이전트를 쓰든 스킬 자산이 그대로 따라옵니다.
다만 “어디서든 완벽하게”라는 말은 아직 약간 앞선 표현입니다. 플랫폼마다 구현 수준이 다르고 암묵적 자동 트리거는 플랫폼에 따라 동작이 다릅니다. 이 부분이 좀 아쉬웠습니다. 그래도 명시적 호출 방식으로 쓰면 호환성 문제는 거의 없습니다.
AI 에이전트 경쟁의 축이 “어떤 모델을 쓰느냐”에서 “어떤 스킬을 갖추고 있느냐”로 이동하고 있다는 건 체감이 옵니다. skills.sh에서 지금 바로 설치해볼 수 있는 스킬들이 수천 개인데, 대부분 무료입니다. 일단 하나 골라 설치해보는 것이 가장 빠른 이해 방법입니다.
📌 바로 시작하는 명령어 3개
# 1. skills.sh에서 스킬 검색
npx skills find
# 2. Anthropic 공식 문서 스킬 설치 (PDF·DOCX·XLSX·PPTX)
npx skills add anthropics/skills --skill pdf
# 3. 설치된 스킬 확인
npx skills list본 포스팅 참고 자료
- inference.sh 공식 블로그 — Agent Skills 개요 https://inference.sh/blog/skills/agent-skills-overview
- OpenAI Codex 공식 문서 — Agent Skills https://developers.openai.com/codex/skills/
- Firecrawl 공식 블로그 — Best Claude Code Skills (2026.03.13) https://www.firecrawl.dev/blog/best-claude-code-skills
- Medium / Alireza Rezvani — AI Agent Skills at Scale (2026.03.13) 링크
- daleseo.com — skills.sh 공개 에이전트 스킬 생태계 https://daleseo.com/skills-sh/
- Anthropic 공식 Agent Skills 저장소 https://github.com/anthropics/skills
본 포스팅은 2026년 3월 21일 기준으로 작성되었습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Agent Skills 오픈 표준 및 각 플랫폼의 구현 수준은 지속적으로 업데이트되고 있으므로, 최신 내용은 공식 문서에서 직접 확인하시기 바랍니다.
댓글 남기기