AI/Skills

Agent Skill 오픈 표준(Claude Skills는 Claude 전용이 아니다) - SKILL.md 하나로 Claude, Cursor, Copilot, Gemini 전부 쓰는 방법

안녕하세요! 갓대희입니다.

AI 도구를 새로 바꿀 때마다 이런 생각 해본 적 있지 않나? "Claude Code에서 공들여 만든 커스텀 설정, Cursor로 넘어가면 다시 처음부터 만들어야 하나?" 아니면 팀원이 Copilot을 쓰고 나는 Gemini CLI를 쓰는데, 같은 코딩 컨벤션 스킬을 각자 따로 관리하고 있지 않나?

"Claude Skills는 Claude Code 전용이겠지?"

아니다. Agent Skill(SKILL.md)은 Claude, Codex, Gemini, Cursor, Copilot 등 어디서나 작동하는 크로스플랫폼 오픈 표준이다.

2025년 12월에 오픈 표준으로 공개된 이 규격은 현재 32개 이상의 AI 에이전트에서 공식 지원받고 있다. 한 번 만들어두면 Claude Code에서도, Cursor에서도, GitHub Copilot에서도 그대로 쓸 수 있다는 뜻이다.

오늘은 Agent Skill 표준의 탄생 역사부터 SKILL.md 스펙, 크로스플랫폼 지원 현황, 주목할 스킬 6가지, 그리고 5분 만에 나만의 스킬을 만드는 방법까지 빠짐없이 정리한다. 지금 쓰는 에이전트가 무엇이든 바로 적용할 수 있다.

오늘 정리해볼 것들

Agent Skill 오픈 표준의 탄생 역사 — Anthropic → 오픈 표준 공개까지
SKILL.md 완전 스펙 — frontmatter, 디렉토리 구조, Progressive Disclosure 3단계
32개+ 플랫폼 설치 경로 — Claude, Codex, Gemini, Cursor, Copilot 등 정확한 경로
주목할 스킬 6가지 — Frontend Design, Planning with Files, Superpowers, Humanizer, MCP Builder, Dev-Browser
처음 만드는 SKILL.md 템플릿 — 복붙해서 바로 쓸 수 있는 최소 예시
스킬 찾는 곳 3가지 — skills.sh, anthropics/skills, agentskills.io
실제 사용 시나리오 3가지 — 에이전트 이전, 팀 공유, Before/After 비교
흔한 함정 4가지 — 토큰 낭비, 경로 혼란, description 모호함, name 규칙 위반

Agent Skill이란? — Claude 전용이 아니다
- 흔한 오해 깨기
- 오픈 표준의 탄생 역사 (2025-12 공개)
- 현재 생태계 규모
SKILL.md 완전 스펙
- 디렉토리 구조
- Frontmatter 필드 정의
- Progressive Disclosure 3단계
크로스플랫폼 지원 현황
- 32개+ 공식 지원 플랫폼
- 플랫폼별 설치 경로
- 표준 경로 ~/.agents/skills/
주목할 스킬들
- Frontend Design
- Planning with Files
- Superpowers
- Humanizer
- MCP Builder
- Dev-Browser / Superpowers-Chrome
스킬 직접 만들기
- 최소 예시 (복붙 가능)
- 작성 팁 5가지
스킬 찾는 곳
실제 사용 시나리오 3가지
- Claude Code → Codex CLI 이전
- 팀 레포 공유 (.agents/skills/)
- Frontend Design 스킬 Before/After
주의사항 — 흔한 함정 4가지
2026년 3월 커뮤니티 최신 동향
- 이번 주 신규 스킬 PR 하이라이트
- npx skills v1.1.1 신기능
- 커뮤니티 핵심 논쟁 — AGENTS.md vs SKILL.md
- 실용 팁 — description 표현 방식, 인스트럭션 한도
- SkillsBench 논문 핵심 결론
결론 — 지금 시작하기

1. Agent Skill이란? — Claude 전용이 아니다

흔한 오해 깨기

"Claude Skills"라는 이름 때문에 Claude Code 전용으로 오해하는 경우가 많다.

실제로는 Agent Skill은 특정 벤더에 종속되지 않는 오픈 표준 규격이다. SKILL.md 파일 형식을 따르는 모든 스킬은 표준을 지원하는 어떤 AI 에이전트에서도 작동한다.

이런 오해를 하고 있다면 수정이 필요하다

"Claude Code에서만 쓸 수 있겠지" → 아니다. Cursor, Copilot, Gemini CLI에서도 된다
"Anthropic이 만든 거면 Claude에 최적화되어 있겠지" → 표준을 오픈했기 때문에 어디서나 동일하게 동작한다
"직접 만들기 어렵겠지" → SKILL.md 하나로 5분이면 만든다

오픈 표준의 탄생 역사

Agent Skill 표준이 지금의 모습이 되기까지의 타임라인이다.

시점	내용
2025-12-16	agentskills/agentskills 저장소 첫 커밋 (init)
2025-12-18	오픈 표준으로 공개 — agentskills.io 론칭, agentskills/agentskills 저장소 공개 (Apache 2.0)
이후	Vercel Labs가 skills.sh 디렉토리 사이트 + npx skills CLI 제작. Cursor, GitHub Copilot, Gemini CLI 등 주요 플랫폼들이 순차적으로 공식 지원 추가
2026-03 현재	32개 이상의 AI 에이전트/IDE가 공식 지원. agentskills/agentskills 저장소 13,220 (2026-03-16 기준)

현재 생태계 규모

2026-03-16 기준 확인된 수치

agentskills/agentskills (표준 저장소): 13,220, Apache 2.0
anthropics/skills (Anthropic 공식 스킬 모음): 94,479
공식 지원 플랫폼: 32개+ (agentskills.io 기준)
공식 문서: agentskills.io

agentskills 커뮤니티가 표준을 운영하고, Anthropic이 공식 스킬 모음을 제공하며, Vercel이 CLI/디렉토리를 담당하는 구조다. 어떤 단일 기업에도 종속되지 않는 오픈 생태계라는 점이 핵심이다.

2. SKILL.md 완전 스펙

Agent Skill의 핵심은 SKILL.md 파일 하나다. YAML frontmatter + Markdown 본문으로 이루어진 단순한 텍스트 파일이지만, AI 에이전트가 이 파일을 읽어 어떤 기능을 수행할지 결정한다.

디렉토리 구조

스킬 하나는 하나의 디렉토리로 구성된다. 필수 파일은 SKILL.md 뿐이고, 나머지는 모두 선택이다.

my-skill/
├── SKILL.md          ← 필수. 스킬의 전부가 여기에
├── scripts/          ← 선택. 스킬이 사용할 스크립트/도구
│   ├── setup.sh
│   └── validate.py
├── references/       ← 선택. 참고 문서, 예시 파일
│   ├── example.md
│   └── patterns.md
└── assets/           ← 선택. 이미지, 기타 리소스

SKILL.md Frontmatter 필드 정의

SKILL.md는 파일 상단의 YAML frontmatter와 그 아래의 Markdown 본문으로 구성된다. frontmatter에서 스킬의 메타데이터를 정의한다.

---
name: my-awesome-skill          # 필수. 최대 64자. 소문자+숫자+하이픈만
description: |                  # 필수. 최대 1024자
  이 스킬은 무엇을 하는지 한 문단으로 설명한다.
  언제 호출되어야 하는지도 여기에 적는다.
license: MIT                       # 선택
compatibility: |               # 선택. 최대 500자. 지원 플랫폼, 버전 제약 등
  Claude Code 1.0+, Cursor 0.40+
  Node.js 18+ required for scripts/
metadata:                         # 선택. 임의 키-값 쌍
  version: 1.2.0
  author: your-name
  tags: [productivity, frontend]
allowed-tools: Bash(git:*) Bash(npm:*) Read  # 선택. 실험적 기능. 허용할 도구 목록
---

필드	필수	제약 / 설명
`name`	필수	최대 64자. 소문자 영문자·숫자·하이픈(-)만 허용
`description`	필수	최대 1024자. Tier 1에서 로딩되는 핵심 정보. 언제 활성화되는지 명확히 기술
`license`	선택	SPDX 라이선스 식별자 권장 (MIT, Apache-2.0 등)
`compatibility`	선택	최대 500자. 지원 플랫폼, 버전 요구사항, 의존성 명시
`metadata`	선택	임의 키-값 쌍. version, author, tags 등 자유 형식
`allowed-tools`	선택	실험적 기능. 스킬이 사용할 수 있는 도구(Bash, Read, Write 등)를 제한

Progressive Disclosure 3단계

Agent Skill의 가장 중요한 설계 원칙은 Progressive Disclosure다. 에이전트가 모든 스킬의 전체 내용을 한꺼번에 로딩하면 컨텍스트 윈도우가 금방 채워진다. 그래서 3단계에 걸쳐 필요한 만큼만 로딩한다.

Tier 1 — 세션 시작 시 자동 로딩

로딩 내용: name + description 만
토큰 비용: 약 50~100 토큰 / 스킬
역할: "이런 요청이 들어오면 이 스킬을 써야겠다"는 판단 기준. 에이전트가 모든 설치된 스킬의 Tier 1을 읽고 대기한다.

Tier 2 — 스킬 활성화 시 로딩

로딩 내용: SKILL.md 전체 본문
권장 크기: 5,000 토큰 미만
역할: 실제 수행 지침. 에이전트가 "이 스킬이 필요하다"고 판단한 뒤 전체 본문을 읽고 작업을 수행한다.

Tier 3 — 필요 시 온디맨드 로딩

로딩 내용: scripts/, references/, assets/
역할: 보조 리소스. 스킬 본문에서 참조할 때만 로딩된다. 대용량 참고 문서나 실행 스크립트 등을 여기에 넣는다.

실전 팁: description은 "언제 나를 써야 하는지"를 명확하게 써야 한다. Tier 1에서 에이전트가 이 텍스트만 보고 스킬 활성화 여부를 결정하기 때문이다. "코드 리뷰 요청, PR 피드백, 코드 개선 제안 시 활성화"처럼 구체적인 트리거 조건을 포함하는 것이 좋다.

3. 크로스플랫폼 지원 현황

2026-03-16 기준 agentskills.io에 따르면 32개 이상의 플랫폼이 Agent Skills 표준을 공식 지원한다. 각 플랫폼별로 스킬 설치 경로가 다르기 때문에, 정확한 경로를 한 번 파악해두는 것이 중요하다.

주요 플랫폼별 설치 경로

플랫폼	전역(Global) 설치 경로	프로젝트 설치 경로
Claude Code	`~/.claude/skills/`	`.claude/skills/`
Codex CLI	`~/.agents/skills/` (권장) `~/.codex/skills/` (레거시)	`.agents/skills/`
Gemini CLI	`~/.gemini/skills/`	`.agents/skills/`
Cursor	`~/.cursor/skills/`	`.cursor/skills/`
Windsurf	`~/.codeium/windsurf/skills/`	`.agents/skills/`
GitHub Copilot	`~/.copilot/skills/`	`.copilot/skills/`
OpenCode	`~/.config/opencode/skills/`	`.agents/skills/`

경로 표기 안내: 플랫폼별 경로는 각 클라이언트 구현체 코드 기반 수치이며, 공식 표준 문서(agentskills.io)는 ~/.<client>/skills/ 패턴만 명시한다. 실제 경로는 버전에 따라 다를 수 있으므로 각 도구 공식 문서에서 확인하자. 참고로, ~/.claude/skills/는 관행적으로 널리 사용되는 경로이나, agentskills.io 공식 표준은 ~/.agents/skills/이다.

크로스플랫폼 표준 경로: ~/.agents/skills/

여러 AI 에이전트를 동시에 사용하는 개발자라면 매번 각각 경로에 복사해야 하는 번거로움이 있다. 이를 해결하기 위한 크로스플랫폼 표준 경로가 있다.

표준 크로스플랫폼 경로

전역: ~/.agents/skills/
프로젝트: .agents/skills/

Codex CLI는 ~/.agents/skills/를 스캔 경로로 지원하며, 다른 플랫폼들도 이 경로를 점차 지원하는 방향으로 이동 중이다.

가장 실용적인 방법은 ~/.agents/skills/에 스킬을 저장하고, 각 에이전트별 디렉토리에는 심볼릭 링크(symlink)를 거는 방식이다.

# 표준 경로에 스킬 보관
mkdir -p ~/.agents/skills/my-skill

# Claude Code용 심볼릭 링크
ln -s ~/.agents/skills/my-skill ~/.claude/skills/my-skill

# Cursor용 심볼릭 링크
ln -s ~/.agents/skills/my-skill ~/.cursor/skills/my-skill

# npx skills CLI 사용 (자동으로 경로 처리)
npx skills add my-skill

4. 주목할 스킬들

커뮤니티 반응이 좋고 실용성이 검증된 스킬들을 골라 소개한다. GitHub 스타 수는 모두 2026-03-16 기준이며, 이후 변동될 수 있다.

1. Frontend Design — "AI 티" 없애기

저장소: github.com/anthropics/skills (전체 94,479)

제작: Anthropic 공식

AI가 생성한 UI를 보면 금방 알아볼 수 있다. Inter 폰트, 파란색 그라디언트, 카드 UI의 과다 사용... Frontend Design 스킬은 이런 패턴을 명시적으로 금지하고, 독창적인 디자인을 유도한다.

금지 폰트

Inter, Roboto, Arial, system fonts, Space Grotesk — "기본값으로 보이는" 폰트 전체 금지

금지 색상 패턴

흰 배경 위 보라색 그라디언트 — AI 생성 UI의 가장 흔한 패턴

선택 가능한 디자인 방향

brutalist/raw: 거친 날것 그대로의 웹 디자인
retro-futuristic: 복고풍 미래 감성
organic/natural: 자연스럽고 유기적인 형태
luxury/refined: 고급스럽고 세련된 스타일
playful/toy-like: 장난감 같은 귀여운 감성
editorial/magazine: 잡지풍 레이아웃
art deco/geometric: 기하학적 아르데코
soft/pastel: 부드럽고 파스텔한 색감
industrial/utilitarian: 산업적이고 실용주의적
brutally minimal: 극단적 미니멀리즘 — 장식 0, 기능만
maximalist chaos: 과잉이 미학인 맥시멀리즘

2. Planning with Files — Manus 스타일 파일 기반 작업 계획

저장소: github.com/OthmanAdi/planning-with-files 16,151

버전: v2.18.2, 96.7% pass rate (출처: GitHub README)

지원 플랫폼: 16개

Manus가 사용하는 방식에서 영감을 받은 스킬이다. 핵심 아이디어는 간단하다: Context Window = RAM, Filesystem = Disk. AI 에이전트가 작업 계획과 진행 상황을 파일에 저장해두면, 컨텍스트가 초기화되더라도 파일을 읽어 이어서 작업을 계속할 수 있다.

생성되는 파일

task_plan.md: 전체 작업 계획 및 단계 분해
findings.md: 조사/리서치 결과 누적 저장
progress.md: 현재까지의 진행 상황 추적

내장 Hooks (3종)

PreToolUse, PostToolUse, Stop — 워크플로우 각 단계에서 자동으로 파일 업데이트

3. Superpowers — 7단계 개발 워크플로우 올인원

저장소: github.com/obra/superpowers 86,879

포함 스킬: 14개 (Chrome DevTools Protocol 포함 시 별도 저장소: obra/superpowers-chrome 204)

AI 코딩 에이전트를 위한 완전한 개발 워크플로우를 제공하는 스킬 모음이다. 단순한 "코드 짜줘" 수준을 넘어, brainstorming부터 최종 마무리까지 7단계를 구조화한다.

7단계 워크플로우

brainstorming: 접근 방식 탐색 및 아이디어 발산
git-worktrees: 병렬 개발을 위한 Git 워크트리 활용
writing-plans: 구체적인 구현 계획 수립
executing-plans: 계획 실행 및 구현
TDD: 테스트 주도 개발 패턴 적용
code-review: 코드 품질 검토
finishing: 최종 점검 및 정리

4. Humanizer — AI 문체 제거기

저장소: github.com/blader/humanizer 9,423

참고 자료: Wikipedia "Signs of AI writing" 가이드 기반

한국어 버전: devswha/oh-my-humanizer 23

AI가 작성한 글에는 특유의 패턴이 있다. Humanizer는 이 패턴들을 구체적으로 정의하고 제거하는 스킬이다.

제거 대상 주요 AI 패턴 (아래 6가지 포함, 전체 목록은 원본 저장소 참조)

과도한 의미 부여: 중요성·레거시·더 큰 트렌드를 지나치게 강조하는 패턴
promotional language: 마케팅 문구 같은 홍보성 표현
vague attributions: "전문가들에 따르면", "연구 결과" 같은 출처 불명 표현
em dash overuse: em dash(—) 남용
rule of three: 세 가지를 나열하는 패턴 남용
AI vocabulary: "delve into", "tapestry", "nuance" 같은 AI 특유 단어

한국어 사용자 참고: 한국어 버전인 devswha/oh-my-humanizer는 현재 23으로 규모는 작지만, 한국어 AI 문체 패턴을 제거하는 데 특화되어 있다. 영어 원본 스킬과 함께 참고해볼 만하다.

5. MCP Builder — MCP 서버 개발 가이드

저장소: github.com/anthropics/skills

제작: Anthropic 공식

MCP(Model Context Protocol) 서버를 직접 개발하고 싶은 사람을 위한 스킬이다. 설계 원칙부터 구현, 테스트까지 4단계로 안내한다.

Planning: MCP 서버의 목적과 노출할 도구/리소스 설계
Implementation: 실제 서버 코드 구현
Review & Test: MCP Inspector를 활용한 테스트 방법 가이드 포함
Evaluation: 품질 기준 검토 및 배포 준비

6. Superpowers-Chrome — 브라우저 자동화

저장소: github.com/obra/superpowers-chrome 204

기술: Chrome DevTools Protocol (CDP) 기반

Chrome DevTools Protocol을 사용해 AI 에이전트가 실제 Chrome 브라우저를 제어할 수 있게 해주는 스킬이다. Superpowers 스킬 패밀리의 브라우저 자동화 모듈이다.

수치 미확인 항목: 일부 커뮤니티 게시물에서 "Dev-Browser 3.3k" 수치가 언급되지만, 이는 확인이 어렵다. 위에 표기한 obra/superpowers-chrome 204는 2026-03-16 기준 직접 확인한 수치다. Dev-Browser라는 별도 저장소가 있다면 공식 출처를 직접 확인하기 바란다.

주요 스킬 한눈에 비교

위에서 소개한 스킬들을 한 표로 정리한다. GitHub Stars는 2026-03-16 기준이며 이후 변동될 수 있다.

스킬명	제작	GitHub Stars	주요 기능	설치 명령	대상 사용자
Frontend Design	Anthropic	94,479 (모음집)	AI 티 없애기, 독창적 UI 유도, 금지 폰트/색상 패턴 정의	`npx skills add frontend-design`	프론트엔드 개발자, 디자이너
Planning with Files	OthmanAdi	16,151	파일 기반 작업 계획, 컨텍스트 초기화 대응, Hooks 내장	`npx skills add planning-with-files`	장기 작업, 복잡한 리팩터링
Superpowers	obra	86,879	brainstorming→finishing 7단계 워크플로우, TDD, 코드 리뷰	`npx skills add superpowers`	풀스택 개발자, AI 코딩 에이전트 활용
Humanizer	blader	9,423	AI 문체 패턴 제거, em dash 남용·vague attributions 금지	`npx skills add humanizer`	테크 라이터, 마케터, 블로거
MCP Builder	Anthropic	94,479 (모음집)	MCP 서버 설계→구현→테스트→배포 4단계 가이드	`npx skills add mcp-builder`	MCP 서버 개발자
Superpowers-Chrome	obra	204	Chrome DevTools Protocol 기반 브라우저 자동화	`npx skills add superpowers-chrome`	E2E 테스트, 웹 스크래핑 자동화

설치 명령 안내: anthropics/skills의 스킬은 npx skills add anthropics/skills --skill <name> 형식이 권장 문법이다. 위 표의 짧은 슬러그 형식은 skills.sh에 등록된 경우 지원될 수 있으나, 정확한 명령어는 skills.sh에서 직접 확인하자.

5. 스킬 직접 만들기

남이 만든 스킬을 쓰는 것도 좋지만, 나만의 팀 컨벤션이나 반복 작업을 스킬로 만들어 두면 훨씬 강력하다. 아래는 복붙해서 바로 시작할 수 있는 최소 예시다.

최소 예시 — 커밋 메시지 작성 스킬

1단계: 디렉토리 만들기

# 개인 스킬로 설치
mkdir -p ~/.claude/skills/commit-helper

# 또는 크로스플랫폼 표준 경로
mkdir -p ~/.agents/skills/commit-helper

2단계: SKILL.md 작성

---
name: commit-helper
description: |
  Git 커밋 메시지를 작성할 때 활성화된다.
  Conventional Commits 형식을 따르고, 한국어로 작성하며,
  본문에 변경 이유를 포함한다.
  트리거: "커밋", "commit message", "git commit" 요청 시
license: MIT
metadata:
  version: 1.0.0
  author: your-name
---

# Commit Helper

Git 커밋 메시지를 Conventional Commits 형식에 맞게 작성하는 스킬이다.

## 형식

```
<type>(<scope>): <subject>

<body>

<footer>
```

## 타입 정의

- **feat**: 새 기능 추가
- **fix**: 버그 수정
- **docs**: 문서 변경
- **refactor**: 리팩터링 (기능 변화 없음)
- **test**: 테스트 추가/수정
- **chore**: 빌드, 의존성 등 기타

## 규칙

1. subject는 50자 이내, 명령형 동사로 시작 (한국어: "추가한다" 아닌 "추가")
2. body에는 "왜" 변경했는지 반드시 포함
3. 관련 이슈 번호는 footer에 "Closes #123" 형식으로

3단계: 즉시 테스트

# Claude Code 재시작 후 테스트
# "이 변경사항에 맞는 커밋 메시지 작성해줘"라고 입력하면
# commit-helper 스킬이 자동으로 활성화된다

스킬 작성 팁 5가지

description에 트리거 조건을 명시한다
에이전트는 Tier 1에서 description만 보고 스킬 활성화 여부를 결정한다. "어떤 상황에서 이 스킬을 써야 하는지"를 구체적으로 적어야 정확하게 호출된다.
SKILL.md 본문은 5,000 토큰 미만으로 유지한다
Tier 2 권장 상한선이다. 그 이상의 내용은 references/ 폴더로 분리하고 필요할 때만 참조하게 한다.
name은 소문자 영문자·숫자·하이픈만 사용한다
최대 64자 제한이 있다. 언더스코어(_)나 대문자는 표준에서 허용하지 않는다.
compatibility 필드로 지원 범위를 명확히 한다
scripts/ 폴더의 셸 스크립트가 macOS에서만 동작한다면, 그 사실을 compatibility에 적어야 한다.
팀 스킬은 프로젝트 루트의 .agents/skills/에 넣는다
개인 스킬은 ~/.claude/skills/ 또는 크로스플랫폼 표준 경로인 ~/.agents/skills/에, 팀 전체가 공유해야 하는 스킬은 프로젝트 루트의 .agents/skills/에 넣고 git에 커밋한다. Claude 전용 프로젝트라면 .claude/skills/도 가능하지만, 팀원이 다른 에이전트를 쓴다면 .agents/skills/가 더 범용적이다.

6. 스킬 찾는 곳

스킬을 찾을 수 있는 공식 경로가 세 곳 있다. 각각 역할이 다르기 때문에 상황에 맞게 활용한다.

1. skills.sh — Vercel이 만든 공식 디렉토리 + CLI

URL: https://skills.sh / CLI 저장소: github.com/vercel-labs/skills

Vercel Labs가 제작한 공식 스킬 디렉토리 사이트와 CLI 도구다. 브라우저에서 스킬을 검색할 수도 있고, 터미널에서 한 줄로 설치할 수도 있다.

# 스킬 검색 (키워드 검색 또는 인터랙티브 선택)
npx skills find frontend

# 스킬 설치 — GitHub 저장소 지정 방식 (권장)
npx skills add anthropics/skills --skill frontend-design

# 설치된 스킬 목록
npx skills list

# 스킬 제거
npx skills remove frontend-design

2. anthropics/skills — Anthropic 공식 스킬 저장소

URL: github.com/anthropics/skills — 94,479 (2026-03-16 기준)

Anthropic이 직접 관리하는 공식 스킬 저장소다. Frontend Design, MCP Builder 등 Anthropic이 검증한 스킬들이 여기에 있다. Claude Code에 최적화되어 있지만 오픈 표준을 따르기 때문에 다른 에이전트에서도 사용 가능하다.

3. agentskills.io — 표준 공식 문서

URL: https://agentskills.io / 표준 저장소: github.com/agentskills/agentskills

SKILL.md 표준의 공식 문서 사이트다. 스킬 설치보다는 표준 스펙 자체를 이해하거나, 직접 스킬을 만들 때 참고한다. 지원 플랫폼 목록(32개+)도 여기서 확인할 수 있다.

skillsmp.com (커뮤니티 마켓플레이스): 커뮤니티 보고 기준으로 270,000개 이상의 오픈소스 스킬이 인덱싱되어 있으며 Claude Code, ChatGPT, Codex 등과 호환된다고 알려져 있다. 다만 접근 안정성 및 수치의 정확성은 직접 확인이 필요하다. (skillsmp.com / 2026-03-19 기준 커뮤니티 보고)

7. 실제 사용 시나리오 3가지

개념을 알았으면 실제로 어떻게 쓰는지가 중요하다. 현업에서 자주 만나는 세 가지 상황을 구체적으로 살펴본다.

시나리오 A — Claude Code에서 만든 스킬을 Codex CLI로 이전하기

Claude Code로 한 달 동안 써온 커스텀 커밋 메시지 스킬이 있다. OpenAI Codex CLI로 프로젝트를 옮기게 됐다. 스킬을 다시 만들어야 할까?

상황: 기존 스킬이 ~/.claude/skills/commit-helper/SKILL.md에 있다.

# 방법 1: 표준 경로로 이동 후 양쪽에 심볼릭 링크
mv ~/.claude/skills/commit-helper ~/.agents/skills/commit-helper

# Claude Code용 링크 (기존 경로 복원)
ln -s ~/.agents/skills/commit-helper ~/.claude/skills/commit-helper

# Codex CLI는 ~/.agents/skills/를 직접 읽으므로 추가 작업 불필요
# ~/.agents/skills/commit-helper/SKILL.md가 있으면 바로 인식

# 방법 2: npx skills CLI로 재설치 (클라우드 저장한 경우)
npx skills add commit-helper

핵심: SKILL.md 파일 자체는 그대로다. 에이전트만 바뀌었을 뿐이고, 오픈 표준이기 때문에 수정 없이 바로 작동한다.

시나리오 B — 팀 레포에 .agents/skills/로 스킬 공유하기

팀 전체가 같은 코드 리뷰 기준을 써야 한다. 각자가 개별적으로 스킬을 설치하면 버전이 달라질 수 있다. 프로젝트 레포에 스킬을 커밋해서 공유하는 방법이다.

# 프로젝트 루트에 스킬 디렉토리 생성
mkdir -p .agents/skills/code-review

# SKILL.md 작성
touch .agents/skills/code-review/SKILL.md

# git에 커밋 (팀 전체가 자동으로 동기화)
git add .agents/skills/
git commit -m "feat: 팀 코드 리뷰 스킬 추가"

팀원이 레포를 클론하거나 pull 받으면 .agents/skills/code-review/SKILL.md가 자동으로 반영된다. Claude Code, Codex CLI, Gemini CLI 등 표준 지원 에이전트라면 프로젝트 로컬 스킬을 자동으로 인식한다.

팀 스킬 폴더 구조 예시

my-project/
├── src/
├── .agents/
│   └── skills/
│       ├── code-review/    ← 팀 코드 리뷰 기준
│       │   └── SKILL.md
│       ├── commit-style/   ← 커밋 메시지 컨벤션
│       │   └── SKILL.md
│       └── test-guide/     ← 테스트 작성 가이드
│           └── SKILL.md
└── README.md

시나리오 C — Frontend Design 스킬 활성화 후 실제로 달라지는 점

"랜딩 페이지 만들어줘"라고 요청했을 때, Frontend Design 스킬이 있는 경우와 없는 경우의 차이를 정리한다.

스킬 없을 때 (AI 기본값)	Frontend Design 스킬 있을 때
Inter 또는 Roboto 폰트 자동 선택	Inter·Roboto 금지, 요청한 디자인 방향에 맞는 폰트 선택
흰 배경 + 파란색 그라디언트 버튼	그라디언트 금지, brutalist·editorial 등 방향에 맞는 색 체계 사용
카드 UI + 그림자 과다 사용	카드 남용 억제, 선택한 디자인 방향의 레이아웃 패턴 적용
모든 UI가 비슷해 보임 ("AI가 만든 티")	의도적으로 구분되는 디자인 방향 유지

참고: 위 Before/After는 Frontend Design 스킬 SKILL.md에 명시된 규칙을 기반으로 정리한 것이다. 실제 결과는 모델 버전과 프롬프트에 따라 다를 수 있다.

8. 주의사항 — 흔한 함정 4가지

함정 1 — SKILL.md 본문이 너무 크면 토큰을 낭비한다

Tier 2에서 SKILL.md 전체가 로딩된다. 본문이 10,000 토큰이 넘으면 스킬이 활성화될 때마다 그만큼의 컨텍스트가 소비된다. 5,000 토큰 미만을 권장 상한으로 유지하고, 긴 참고 자료는 references/ 폴더로 분리해서 Tier 3 온디맨드 로딩을 활용한다.

함정 2 — 플랫폼별 경로가 달라 "왜 안 되지?" 하는 경우

Claude Code는 ~/.claude/skills/, Cursor는 ~/.cursor/skills/를 각각 본다. 스킬을 ~/.agents/skills/에 두고 각 에이전트 경로에 심볼릭 링크를 거는 방식, 또는 npx skills add을 쓰면 이 문제를 피할 수 있다.

함정 3 — description이 모호하면 스킬이 엉뚱한 타이밍에 활성화된다

에이전트는 Tier 1에서 description 텍스트만 보고 스킬 활성화 여부를 결정한다. "코드를 개선할 때 사용"처럼 범위가 넓은 description은 관련 없는 요청에도 스킬이 켜지거나, 반대로 꼭 필요한 순간에 켜지지 않는 경우가 생긴다. 구체적인 트리거 조건을 명시하는 것이 중요하다. ("git commit 메시지 작성 요청 시 활성화" vs "코드 작업 시 활성화")

함정 4 — name 필드에 언더스코어나 대문자를 쓰면 표준 위반

name 필드는 소문자 영문자·숫자·하이픈(-)만 허용한다. commit_helper(언더스코어), CommitHelper(대문자)는 표준 위반이다. commit-helper처럼 하이픈을 사용한다. 표준을 엄격하게 지키는 에이전트에서는 로딩 자체를 거부할 수 있다.

2026년 3월 커뮤니티 최신 동향

스킬명	설명
`supabase-skill`	Supabase MCP 연동 및 데이터베이스 작업 자동화
`session-wrap-up`	세션 종료 시 작업 내용 자동 요약 및 다음 액션 정리
`eileen`	능동적 요구사항 도출 — 모호한 지시를 받으면 먼저 질문해서 정확한 요구사항을 끌어내는 스킬
`agent-notify`	작업 완료/실패 시 Slack, Discord, 이메일 등 크로스 플랫폼 알림 발송
`skill-security-scanner`	SKILL.md 파일의 보안 취약점 및 과도한 권한 설정 자동 감지
`context7-cache`	Context7 MCP 조회 결과를 캐싱해 반복 토큰 비용 절감

npx skills v1.1.1 — find · update 신기능 추가

[최근] Vercel이 2026년 2월 skills v1.1.1을 릴리스하며 두 가지 유용한 명령어를 추가했다. (출처: InfoQ, 2026-02)

# 대화형 스킬 탐색 (v1.1.1 신기능) — 검색어로 스킬 목록 브라우징
npx skills find

# 설치된 모든 스킬 일괄 업데이트 (v1.1.1 신기능)
npx skills update

# 기존 명령어 — GitHub 저장소에서 바로 설치
npx skills add vercel-labs/agent-skills

skill-creator — 스킬 자체 평가·벤치마크 기능 추가

[최근] Anthropic이 2026년 3월 skill-creator 스킬을 업데이트하며 스킬이 제대로 작동하는지 자동으로 테스트하고 개선하는 eval(평가) 기능을 추가했다. 스킬 정의 → 초안 생성 → 자동 벤치마크 → 문제 발견 시 자동 수정 사이클이 가능해진 것이다. (출처: adwaitx.com)

설치: npx skills add anthropics/skills --skill skill-creator
"스킬을 만들었는데 제대로 작동하는지 모르겠다"는 문제를 해결하는 도구다. 만든 스킬을 바로 eval로 검증할 수 있다.

커뮤니티 핵심 논쟁 — AGENTS.md vs SKILL.md

쟁점 1 — 스킬 자동 활성화 신뢰성 문제

커뮤니티 사용자 SOLAR_FIELDS: "에이전트가 적절한 시점에 스킬을 자동으로 활성화하지 않는 경우가 많다 — 조용한 실패(silent failure) 문제". 이는 현재 가장 많이 보고되는 불만 사항이다.

쟁점 2 — AGENTS.md 방식과의 성능 차이

Vercel 팀이 AGENTS.md 방식(압축 문서 인덱스)이 일부 평가에서 SKILL.md보다 높은 성공률(79% → 100%)을 보였다고 보고. 반론으로 OJFord: "AGENTS.md는 판단 없이 항상 컨텍스트에 존재하고, SKILL.md는 언제 호출할지 판단·비동기 로딩 등이 추가로 필요하다 — 설계 철학이 다를 뿐".

실용 팁 — description 표현 방식과 인스트럭션 한도

[최근] HN 사용자 postalcoder가 실무 테스트에서 발견한 중요한 팁이다. description 작성 방식이 스킬 활성화율에 직접 영향을 미친다.

명령형 표현 (낮은 활성화율)	선언형 표현 (높은 활성화율)
`You must follow these commit rules when...` (3번 중 0번 활성화)	`I will follow these commit rules when...` (3번 중 3번 활성화)

AgentLinter 분석 결과 — 150개 인스트럭션 한도

커뮤니티에서 공유된 AgentLinter 도구가 500개 이상의 프로덕션 워크스페이스를 분석한 결과, 인스트럭션(스킬 포함)이 150개를 넘으면 에이전트 성능이 약 40% 저하되는 경향이 관찰됐다고 보고됐다. 스킬은 작은 단위로 분리해서 필요한 것만 설치하는 방식을 권장한다. (출처: SmartScope 가이드 / 커뮤니티 보고 기반으로, 독립 검증 필요)

SkillsBench 논문 — AI 자체 생성 스킬 vs 큐레이션 스킬

[최근] 2026년 2월 arXiv에 공개된 SkillsBench 논문 (arXiv:2602.12670)이 HN에서 큰 논쟁을 일으켰다. 86개 태스크, 11개 도메인에 걸쳐 스킬 효과를 측정한 결과다.

큐레이션 스킬(사람이 만든 스킬): 기준 대비 평균 +16.2%p 성능 향상. 특히 헬스케어·금융 등 LLM이 약한 도메인에서 효과 극대화 (+51.9%p).

AI 자체 생성 스킬: 평균적으로 효과 없음. 인터넷에 유통되는 일반 사용자 생성 스킬 평균 품질 점수는 12점 만점에 6.2점.

실용적 시사점: AI에게 "SKILL.md 만들어줘"라고 하는 것보다, 실제 작업을 여러 번 완료한 뒤 그 경험을 토대로 스킬을 정제하는 방식이 훨씬 효과적이다. 스킬의 퀄리티는 생성 방식이 아닌 검증 반복 횟수에 달려 있다.

9. 결론

Agent Skill(SKILL.md) 표준은 특정 회사의 독점 기술이 아니다.

Anthropic이 씨앗을 심었고, Vercel이 CLI를 만들었으며, 커뮤니티가 스킬을 만들어 가는 크로스플랫폼 오픈 표준이다.

오늘 배운 핵심 정리

Agent Skill은 Claude 전용이 아니다 — Anthropic이 2025-12 오픈 표준으로 공개, 32개+ 플랫폼 지원
SKILL.md = YAML frontmatter + Markdown 본문 — name(필수, 64자), description(필수, 1024자) 두 필드면 최소 스킬 완성
Progressive Disclosure 3단계 — Tier 1(name+desc 로딩), Tier 2(전체 본문), Tier 3(scripts/references/assets)
크로스플랫폼 표준 경로는 ~/.agents/skills/ — 여기에 저장하고 각 에이전트 경로로 심볼릭 링크, 또는 npx skills add이 자동 처리
스킬 찾기 — skills.sh(CLI), github.com/anthropics/skills(공식), agentskills.io(표준 문서)
팀 공유는 .agents/skills/ 커밋 — 프로젝트 루트에 넣고 git에 커밋하면 팀 전체 자동 동기화
함정 주의 — 본문 5,000 토큰 미만 유지, description 트리거 조건 명확히, name은 소문자+하이픈만

지금 당장 해볼 수 있는 것 3가지

읽고 끝내지 말고, 바로 하나씩 시도해보자.

① npx skills add로 스킬 하나 설치해보기 (1분)
인기 스킬 하나를 지금 바로 설치해서 에이전트가 어떻게 반응하는지 확인한다.

npx skills add anthropics/skills --skill frontend-design

② 나만의 첫 SKILL.md 만들기 (5분)
반복하는 작업 하나를 골라 name과 description만 채우면 스킬이 완성된다. 섹션 5의 commit-helper 예시를 복붙해서 팀 컨벤션에 맞게 수정하면 된다.

mkdir -p ~/.agents/skills/my-skill
touch ~/.agents/skills/my-skill/SKILL.md
# name, description 두 줄로 시작 → 에이전트 재시작하면 바로 인식

③ 팀 레포에 .agents/skills/ 디렉토리 만들기 (3분)
팀 전체가 쓰는 코드 리뷰 기준이나 커밋 스타일을 스킬로 만들어 레포에 커밋하면, 팀원 누구나 어떤 에이전트를 쓰더라도 동일한 기준을 자동으로 적용받는다.

어떤 AI 에이전트를 쓰든, 오늘 만든 스킬은 내일 다른 에이전트에서도 그대로 쓸 수 있다. 도구는 바뀌어도 지식은 남는다. 그게 오픈 표준의 힘이다.

더 자세한 내용은 아래 공식 출처에서 확인할 수 있다.

agentskills.io — 공식 표준 문서 (출처: 공식 사이트)
github.com/agentskills/agentskills — 표준 저장소 Apache 2.0 (출처: GitHub)
github.com/anthropics/skills — Anthropic 공식 스킬 모음 (출처: GitHub)
skills.sh — Vercel Labs 스킬 디렉토리 + npx CLI (출처: 공식 사이트)

저작자표시 비영리 변경금지 (새창열림)

Contents