[Claude Code 스킬] 커스텀 스킬(Agent Skills) — SKILL.md 한 장으로 Claude에게 전문 능력 심기 | DAKER 커뮤니티
커스텀 스킬(Agent Skills)이란
무엇 — Agent Skills는 SKILL.md 파일 한 장으로 Claude에게 특정 작업의 "전문 매뉴얼"을 심어 주는 기능입니다. 폴더 안에 YAML frontmatter(name·description)와 마크다운 지시문을 담은 SKILL.md를 두면, Claude가 관련 상황을 감지해 그 매뉴얼을 펼쳐 읽고 그대로 수행합니다. 매번 프롬프트에 길게 반복하던 절차를, 재사용 가능한 한 장의 문서로 외부화하는 셈입니다.
언제 쓰나
같은 작업 절차(보고서 양식, 코드 컨벤션, 배포 체크리스트)를 반복해서 시키는데 매번 길게 설명해야 할 때
회사·팀 고유의 도메인 규칙을 Claude가 일관되게 따르길 원할 때
스크립트·템플릿·참고 문서를 작업과 함께 묶어 제공하고 싶을 때
슬래시 커맨드가 "내가 직접 부르는 단축키"라면, 스킬은 "상황을 감지해 Claude가 알아서 펴 보는 설명서"에 가깝습니다.
사용법
스킬은 폴더 하나로 시작합니다. 개인용(모든 프로젝트 공통)은 ~/.claude/skills/, 프로젝트용(레포 공유)은 .claude/skills/에 둡니다.
# 개인 스킬 폴더 생성
mkdir -p ~/.claude/skills/pdf-report그 안에 SKILL.md를 작성합니다.
---
name: pdf-report
description: 월간 운영 지표를 표준 A4 PDF 보고서로 만들 때 사용.
"월간 리포트", "운영 보고서" 요청 시 트리거.
allowed-tools: Read, Write, Bash
---
# 월간 운영 보고서 생성
1. data/metrics.csv 를 읽는다
2. scripts/render.py 로 차트를 만든다 → 검증: PDF 4쪽
3. templates/cover.html 표지를 앞에 붙인다description가 가장 중요합니다 — Claude는 이 한 줄만 보고 "언제 이 스킬을 펼칠지" 판단합니다. 트리거 상황과 키워드를 구체적으로 적을수록 정확히 발동합니다.
핵심 원리 — 점진적 공개(Progressive Disclosure)
스킬은 잘 정리된 도서관과 같습니다. Claude는 평소 description(목차)만 메모리에 띄워 두고, 관련 작업이 들어오면 그제야 SKILL.md 본문(챕터)을, 더 깊은 정보가 필요하면 references/ 폴더(부록)를 펼칩니다. 덕분에 스킬을 수십 개 깔아도 컨텍스트는 가볍게 유지됩니다.
팁
폴더 구조 — SKILL.md(지시문) + scripts/(실행 스크립트) + references/(참고 문서) + assets/(템플릿·이미지). 본문은 짧게 쓰고, 무거운 내용은 references/로 미루세요.
우선순위 — 같은 이름이 겹치면 enterprise > personal > project 순으로 덮어씁니다. 팀 표준을 개인 설정이 덮어쓰지 않도록 주의하세요.
묶어서 배포 — 스킬 여러 개에 MCP·커맨드를 묶으면 플러그인(plugin)이 되고, 플러그인을 모으면 마켓플레이스가 됩니다. 팀 배포는 플러그인 단위로 하세요.
