Agent Skills 튜토리얼 – Claude Skills를 직접 만들고 배포하는 방법

스킬의 기본 구조
SKILL.md 작성법
frontmatter 필드
지침 본문
흔한 실수와 해결법
배포
개인 사용자
조직 단위 배포
GitHub을 통한 커뮤니티 공유
오픈 표준: agentskills.io
스킬 라이브러리 운영 패턴
누가 사용하면 좋은가
관련 문서
참고 자료

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에서 작성한 스킬을 다른 에이전트 플랫폼에서도 재사용할 수 있는 이식성이 목표다.

스킬 라이브러리 운영 패턴

Meng To의 Skills 저장소는 스킬을 단순 프롬프트 모음이 아니라 운영 절차와 참고 자료 묶음으로 다룬다. 저장소는 “prompts are assets”, “specs beat vibes”, “references beat paragraphs”, “skills are operating procedures”라는 원칙을 내세운다.

실무적으로는 SKILL.md에 모든 지식을 길게 넣기보다, 트리거 조건과 실행 절차를 명확히 쓰고 필요한 디자인 참조, 템플릿, 체크리스트는 별도 파일로 분리하는 편이 낫다. 이렇게 하면 모델은 필요한 순간에 관련 자료만 읽고, 팀은 스킬을 코드처럼 리뷰·버전 관리할 수 있다.

누가 사용하면 좋은가

Claude Code나 Claude.ai에서 반복적으로 수행하는 작업 패턴이 있는 개발자
팀 전체에 일관된 에이전트 행동 기준을 배포해야 하는 엔지니어링 리드
AI 에이전트 워크플로를 커스텀 도메인에 맞춰 최적화하려는 팀

참고 자료

Anthropic’s Complete Guide to Claude Skills Building — KDnuggets (2026-06-09)
Agent Skills — Agent Skills 공식 표준 문서
anthropics/skills — Anthropic의 Claude Skills 참조 저장소
MengTo/Skills — 디자이너·빌더를 위한 커뮤니티 스킬 큐레이션 저장소

Like?

AI Sparkup