스킬이 무엇이고 어떻게 등록하는지는 기초 과정('클로드 코드 완전 정복'의 스킬 레슨)에서 다뤘습니다. 이번 레슨은 그 위에서 '좋은 스킬을 어떻게 쓰느냐'에 집중합니다. 결론부터 말하면, 스킬의 품질은 저작의 8할이 description에서 결정됩니다.
왜일까요? 스킬에는 '이 스킬을 실행하라'는 강제 스위치가 없습니다. 앞 레슨에서 봤듯, 평소 컨텍스트에는 스킬의 이름과 description만 올라가 있고, 클로드는 그 한 줄을 읽고 '지금 이 스킬을 써야겠다'를 스스로 판단합니다. 즉 description은 사람에게 보여 주는 소개문이 아니라, 클로드가 자기 자신에게 내리는 '언제 이걸 꺼내 쓸지'의 지침입니다.
나쁜 description vs 좋은 description
description 한 줄이 스킬의 운명을 가른다
나쁜 예 — 추상적
- "리포트 생성 스킬"
- 무엇을 언제 쓰는지 알 수 없음
- 클로드가 매칭 못 해 스킬이 잠들어 있음
- 결국 사용자가 매번 수동으로 지목해야 함
좋은 예 — 구체적 + 트리거
- 첫 문장에 핵심 기능을 명확히: '주간 지표를 모아 임원용 요약 리포트를 만든다'
- 사용자가 실제로 말할 표현 3개+: '주간 리포트 만들어줘', '이번 주 지표 정리', '위클리 요약'
- 언제 써야 하는지 클로드가 즉시 판단 가능
- 사용자가 지목하지 않아도 알아서 발동
핵심 기능 첫 문장 + 실제 트리거 표현 = 클로드가 스스로 켠다
description은 '무엇을 하는가'와 '사용자가 이럴 때 말한다'를 함께 담아야 합니다. 클로드가 읽고 켤 수 있어야 스킬입니다.
SKILL.md의 구조
스킬은 SKILL.md 파일 하나로 정의됩니다. 최근 이 형식은 여러 AI 도구가 공유하는 '에이전트 스킬(agent skills)' 개방 표준으로 정리되어, 클로드 코드뿐 아니라 다른 에이전트에서도 같은 파일을 재사용하는 방향으로 가고 있습니다. 구조는 두 부분입니다. 위쪽 프론트매터에 name과 description을 적고, 아래 본문에 실제 워크플로우와 체크리스트를 적습니다.
.claude/skills/weekly-report/SKILL.md — 신선한 예시
---
name: weekly-metrics-report
description: 주간 핵심 지표(가입·매출·리텐션)를 모아 임원용 한 장 요약 리포트를 만든다. 사용자가 "주간 리포트 만들어줘", "이번 주 지표 정리해줘", "위클리 요약"이라고 말할 때 사용한다.
---
# 주간 지표 리포트 생성
## 목적
지난 7일간의 핵심 지표를 모아, 읽는 데 30초면 되는 임원용 요약을 만든다.
## 워크플로우
1. 지난 7일과 그 직전 7일의 기간을 계산한다.
2. 가입 수, 매출, 7일 리텐션을 각각 조회한다. (데이터 소스는 프로젝트 설정을 따른다)
3. 두 기간을 비교해 증감률(%)을 계산한다.
4. 아래 체크리스트를 채워 마크다운 한 장으로 정리한다.
## 리포트 체크리스트
- [ ] 요약 3줄: 이번 주 가장 중요한 변화
- [ ] 지표 표: 지표 / 이번 주 / 지난 주 / 증감률
- [ ] 눈에 띄는 이상치와 그 추정 원인
- [ ] 다음 주 지켜볼 것 1~2개
## 주의
- 숫자는 반드시 실제 조회 결과만 쓴다. 추정치로 채우지 않는다.
- 데이터가 비면 '데이터 없음'이라고 명시하고 넘어간다.본문에 워크플로우와 체크리스트를 넣는 이유는, 스킬이 '무엇을'뿐 아니라 '어떤 순서로, 무엇을 빠뜨리지 않고'까지 굳혀 두는 그릇이기 때문입니다. 잘 쓴 스킬 하나는, 매번 길게 설명하던 지시를 이름 한 번으로 대체합니다.
저장 위치에 따른 범위
| 저장 위치 | 적용 범위 | 주로 쓰는 용도 |
|---|---|---|
| .claude/skills/ (프로젝트) | 이 프로젝트에서만 | 이 프로젝트 고유의 작업 방식 (팀과 Git으로 공유) |
| ~/.claude/skills/ (개인) | 내 모든 프로젝트 | 어디서나 쓰는 개인 워크플로우 (커밋 정리, 리서치 등) |
| 플러그인으로 배포 | 플러그인을 설치한 모두 | 여러 사람·팀에 공유·배포하는 스킬 묶음 |
"스킬 만들어줘"라고만 해도 초안을 잡아 주는 스킬 제작용 플러그인도 있습니다. 잘 만든 스킬을 플러그인으로 묶어 배포하고, 남이 만든 스킬을 설치해 쓰는 흐름이 자리 잡으면서, 스킬은 점점 '앱스토어처럼 공유·설치하는 능력 단위'로 진화하고 있습니다.
새 스킬을 만들면 description만 바꿔 가며 테스트하세요. 실제로 사용자가 할 법한 문장을 던졌을 때 클로드가 그 스킬을 스스로 집어 드는지 확인하는 것입니다. 안 집어 들면 기능 설명이 부족하거나 트리거 표현이 빠진 것이니, 본문이 아니라 description부터 손보세요.
하나의 스킬에 너무 많은 일을 몰아넣지 마세요. description이 여러 기능을 뭉뚱그리면 클로드가 '이게 맞나?'를 판단하기 어려워집니다. 스킬은 좁고 뚜렷하게 — '주간 리포트'와 '월간 정산'은 별개의 스킬로 나누는 편이 각자 더 잘 발동합니다.
스킬이 '재사용하는 작업 방식'이라면, 다음은 '일을 대신 처리해 줄 일꾼'입니다. 다음 레슨에서는 서브에이전트를 격리·병렬·체인·재귀 네 패턴으로 정리하고, 언제 위임해야 하는지 판단 기준을 세웁니다.