첫 번째 Skill을 처음부터 끝까지 작성하기
- 동작하는 Skill을 처음부터 만들고 실제로 활성화되는지 증명하기
- 적절한 시점에 트리거되는 description 작성하기 — 스킬이 실행될지 말지를 결정하는 유일한 필드
- 결정론적 데이터 수집을 위해 언제 헬퍼 스크립트를 추가할지 판단하기
- 절대 실행되지 않는 스킬을 진단하고, 그 원인이 되는 세 가지 함정 알기
처음부터 동작하는 Skill을 만들고 그것이 활성화되는지 증명해 봅시다. 작은 "체인지로그 항목" 스킬을 만들겠습니다 — 범용적이고 재사용 가능합니다.
1단계 — 폴더 생성
스킬 폴더 생성
mkdir -p .claude/skills/changelog-entry
(모든 프로젝트에서 쓰는 개인용 스킬은 ~/.claude/skills/…를 사용하세요.)
2단계 — SKILL.md 작성
.claude/skills/changelog-entry/SKILL.md:
---
name: changelog-entry
description: Use when the user wants to turn recent git commits into a Keep a Changelog entry.
---
# Changelog Entry
When asked for a changelog entry:
1. Run `git log --oneline -20` to see recent commits.
2. Group them into Added / Changed / Fixed / Removed (Keep a Changelog style).
3. Write concise, user-facing bullets (not raw commit messages).
4. Output only the formatted entry.
description이 트리거입니다 — Claude가 적절한 시점에 로드하도록 "Use when…" 형식으로 작성하세요.
3단계 — (선택) 헬퍼 스크립트 추가
스킬에는 스크립트를 포함할 수 있습니다. 결정론적으로 데이터를 수집하고 싶다면 scripts/recent.sh를 추가하고 SKILL.md에서 참조하세요:
#!/usr/bin/env bash
git log --oneline -20
4단계 — 트리거되는지 증명하기
세션을 시작하고 아래 프롬프트를 시도해 보세요. Claude가 의도를 인식하고, 스킬을 로드하고, 그 단계들을 따라야 합니다. 활성화되지 않는다면, 언제 사용해야 하는지에 대해 description이 충분히 구체적이지 않을 가능성이 높습니다 — 더 다듬으세요.
스킬이 트리거되는지 증명하기
Draft a changelog entry for recent work.
5단계 — 공유하기
(다른 스킬들과 함께) 플러그인으로 묶어 팀이 한 번에 설치하게 하거나 — AILmanac의 스킬 팩에 기여하세요.
흔한 함정
- 모호한 description → 절대 트리거되지 않거나(혹은 항상 트리거됨). 구체적으로 작성하세요.
- 하나의 스킬에 너무 많은 내용 → 하나의 명확한 작업으로 유지하세요.
- 공유 스킬에 비밀 값 포함 → 절대 금지; 서드파티 코드 검토하기를 참고하세요.
- 스킬은 폴더 하나와 SKILL.md입니다 — 프로젝트용은 .claude/skills/<name>/, 모든 프로젝트용은 ~/.claude/skills/
- description이 트리거입니다. Claude가 적절한 순간에 로드하도록 "Use when…" 형식으로 작성하세요
- 스킬에는 스크립트를 포함할 수 있습니다 — Claude가 명령을 즉흥적으로 만드는 대신 결정론적 데이터 수집을 원할 때 사용하세요
- 스킬 이름을 부르는 대신 의도를 프롬프트로 던져 동작을 증명하세요. 트리거되지 않는다면 description이 언제(WHEN) 쓸지에 대해 충분히 구체적이지 않은 것입니다
- 하나의 스킬은 하나의 명확한 작업으로 유지하고, 공유하는 스킬에는 절대 비밀 값을 넣지 마세요