1단계: 이 스킬이 무엇을 가르칠지 정하기
좋은 스킬은 정확히 한 가지만 잘하고, 그 "올바른 방식"을 한 문장으로 요약할 수 있어야 해요.
- ✅ 좋은 예: "우리 브랜드 가이드라인에 맞춰 회사 계정용 게시물 작성하기", "프론트엔드 코드의 접근성 문제 검토하기"
- ❌ 나쁜 예: "뭐든 도와줘" (너무 넓어서 AI가 언제 사용해야 할지 알 수 없어요)
2단계: SKILL.md 작성하기
표준 구조는 다음과 같아요(그대로 가져가도 돼요):
---
name: weekly-report-writer
description: 흩어져 있는 업무 메모를 잘 정리된 주간 보고서로 바꿔 줘요. 사용자가 "주간 보고서 써 줘"라고 말하거나 업무 메모를 붙여 넣을 때 사용해요.
---
# 주간 보고서 작성
1. 사용자의 원본 기록을 읽고 먼저 "이번 주 성과 / 문제 / 다음 주 계획"으로 분류해요
2. 성과는 중요도순으로 정렬하고, 각 항목을 "한 문장 성과 + 뒷받침 수치" 형식으로 작성해요
3. 빠진 데이터는 [TBD]로 표시하고, 절대 데이터를 지어내지 않아요
4. 마지막에 보고서 제목 2가지를 제안해요
## 예시
사용자 입력: "월요일에 회의가 있었고, 화요일에 버그를 고쳤고, 수요일에 기능을 배포했어요."
출력:
### 이번 주 성과
1. XX 기능 배포 완료 (데이터 효과 [TBD])
........
name
소문자 kebab-case로 지은 고유 식별자
description
가장 중요해요. 무엇을 하는지 + 언제 사용하는지를 명확히 적으면 AI가 이를 보고 활성화 여부를 판단해요
본문
구체적인 단계 + 예시 + 규칙 — 구체적일수록 좋아요
3단계: 선택 보조 폴더
scripts/— AI가 필요할 때 호출하는 실행 스크립트(Python, Bash 등)references/— 필요할 때 로드되는 참고 자료/문서assets/— 템플릿과 예시 같은 정적 리소스
4단계: 테스트하고 다듬기
- 서로 다른 입력 3가지로 테스트하고 출력이 기대에 맞는지 확인해요
- AI가 틀렸던 부분을 본문에 보충해요 — 스킬은 반복하며 다듬어지는 거예요
- description이 예상되는 모든 트리거 시나리오를 커버하도록 하세요 (사용자는 천 가지 방식으로 표현하니까요)
- 평점 높은 커뮤니티 스킬의 작성 방식을 연구해 보세요: 엄선 목록을 살펴보세요(공식 anthropics/skills 저장소가 훌륭한 본보기예요)
자주 하는 실수
- description이 너무 막연함 → AI가 언제 활성화해야 할지 몰라 스킬이 무용지물이 돼요
- 막연한 단계("신중하게 분석해" 같은) → 검증 가능한 구체적 행동으로 바꿔요
- 관련 없는 내용으로 분량을 채움 → 점진적 로딩에 어긋나고 에이전트를 느리게 만들어요
- "언제 사용하면 안 되는지" 경계를 정의하지 않음 → 어울리지 않는 시나리오에 억지로 적용돼요