Agent Skills는 Claude가 특정 시나리오에서 반복적으로 따라야 할 행동 지침을 파일로 정의한 확장 기능이다. Claude Code나 Claude.ai에서 스킬을 로드하면, Claude가 해당 상황에서 자동으로 그 지침을 따른다. Anthropic은 이 형식을 오픈 표준으로 공개했으며, 커뮤니티 생태계가 빠르게 성장 중이다.
스킬의 기본 구조
스킬은 하나의 폴더로 구성된다.
my-skill/
├── SKILL.md # 스킬의 핵심 — 트리거 조건과 실행 지침
└── README.md # 사람이 읽는 문서 (폴더 밖에 위치)SKILL.md가 Claude가 실제로 읽는 파일이다. README.md는 GitHub에 배포할 때 저장소 루트에 위치한다.
SKILL.md 작성법
frontmatter 필드
name: my-skill-name
description: >
이 스킬을 언제 사용하는지 설명. Claude가 이 텍스트를 보고
스킬을 발동시킬지 결정하므로 구체적인 사용자 facing 언어로 작성.
triggers:
- "사용자가 X를 요청할 때"
- "Y 작업을 시작하기 전"
compatibility:
- claude-code
- claude.ai지침 본문
frontmatter 아래에 실행 지침을 마크다운으로 작성한다. Claude가 따를 절차, 피해야 할 패턴, 출력 형식 등을 명확하게 기술한다.
흔한 실수와 해결법
| 문제 | 원인 | 해결 |
|---|---|---|
| 스킬이 절대 발동되지 않음 | description이 모호하고 트리거 문구 없음 | 구체적인 사용자 언어로 description 재작성 |
| 스킬이 과도하게 발동됨 | description이 너무 넓음 | “Do NOT use when” 조건 명시 |
| 지침이 무시됨 | 지침이 모호하거나 서로 충돌 | 구체적 명령어와 예상 출력으로 수정 |
| MCP 호출 실패 | 서버 미실행 또는 인증 만료 | 재연결 단계를 스킬에 포함 |
| Claude.ai에서는 동작, Code에서는 실패 | 환경 의존성 누락 | compatibility 필드에 요구사항 문서화 |
| 세션마다 결과 불일치 | 지침이 너무 유연함 | 품질 체크리스트 추가 및 자기 검증 요구 |
배포
개인 사용자
Claude.ai에서 Settings → Capabilities → Skills에서 스킬 폴더(zip)를 업로드한다.
Claude Code에서는 플러그인 명령어를 사용한다:
# 마켓플레이스 등록
/plugin marketplace add your-org/your-repo
# 특정 스킬 설치
/plugin install your-skill-name@your-marketplace-name조직 단위 배포
관리자가 조직 수준에서 스킬을 배포하면, 워크스페이스 전체 멤버의 Claude에 자동으로 로드된다. 개별 설치 없이 중앙에서 관리·업데이트할 수 있다 (2025년 12월 18일부터 지원).
GitHub을 통한 커뮤니티 공유
구조 규칙: 사람이 읽는 README.md는 저장소 루트에, 스킬 폴더는 별도 디렉터리에 위치한다.
Anthropic의 공식 저장소(github.com/anthropics/skills)가 구조, 네이밍 컨벤션, 품질 기준의 정식 참조다.
오픈 표준: agentskills.io
Anthropic은 Agent Skills 형식을 agentskills.io 에서 오픈 표준으로 공개했다. 동일한 SKILL.md 형식이 Claude 외 다른 AI 플랫폼에서도 동작하도록 설계됐다. Claude Code에서 작성한 스킬을 다른 에이전트 플랫폼에서도 재사용할 수 있는 이식성이 목표다.
누가 사용하면 좋은가
- Claude Code나 Claude.ai에서 반복적으로 수행하는 작업 패턴이 있는 개발자
- 팀 전체에 일관된 에이전트 행동 기준을 배포해야 하는 엔지니어링 리드
- AI 에이전트 워크플로를 커스텀 도메인에 맞춰 최적화하려는 팀
관련 문서
- agent-skills — Agent Skills 개요 및 생태계
- awesome-agent-skills — 공식팀이 만든 1,184개+ 에이전트 스킬 큐레이션
- claude-code — 터미널에서 동작하는 Anthropic의 AI 코딩 에이전트
참고 자료
- Anthropic’s Complete Guide to Claude Skills Building — KDnuggets (2026-06-09)