Claude 스킬 만들고 쓰기 — 30건 쓰며 굳어진 규칙을 프로젝트 스킬 aiusecase-writer로

skill-creator 로 뼈대를 만든다

  클로드 스킬 사용법에 관한 유스케이스를 추가
  

Claude 는 먼저 skill-creator 스킬을 불러 절차를 읽습니다(스킬 사용 규칙: 해당되는 스킬이 있으면 그걸 먼저 읽는다). 절차의 1단계 “구체적 사용 예를 이해한다” 는 이 세션에 30건이 있어 건너뛰고, 바로 뼈대를 만듭니다.

python3 ~/.claude/skills/skill-creator/scripts/init_skill.py aiusecase-writer --path .claude/skills

.claude/skills/ 에 둔 이유: 저장소와 함께 배포됩니다. 이 repo 를 clone 한 누구의 Claude 든 같은 규칙으로 사례를 씁니다. ~/.claude/skills/ 는 내 Mac 에서만.

스킬의 뼈대는 셋입니다.

이 3단계 로딩이 핵심입니다. description 은 항상 컨텍스트에 있으니 짧고 정확하게, 본문은 5천 단어 이하, 긴 건 references 로.

SKILL.md 에 절차와 목소리를, references 에 세부를

30건에서 뽑은 규칙이 이렇게 들어갔습니다.

• 워크플로 6단계 — 스캐폴드 → 작업하며 캡처 → index.md → 번들 파일(.md→.txt) → hugo 빌드 exit 0 확인 → 커밋·푸시
• 목소리 — 한국어, 숫자 우선, 실패는 본문에 남긴다, 마지막 세 섹션 고정
• references/page-structure.md — front matter 키 전부, 섹션 순서, 숏코드 3종 문법, relref 규칙
• references/captures.md — 상황별 캡처 방법 표(ego-browser / AppleScript+screencapture / Claude 앱 / 터미널 렌더 / 비디오 프레임), 마스킹 체크리스트(이메일·아바타·파일명·탭·크레딧·키)

SKILL.md 는 다른 Claude 인스턴스가 읽는 문서입니다. 그래서 “You should…” 가 아니라 “Do X. Never Y.” 로, 당연한 건 빼고 비직관적인 것만 씁니다 — 예: “번들 안 .md 는 Hugo 가 콘텐츠로 삼켜 404 난다”, “존재하지 않는 페이지로 relref 걸면 빌드가 깨진다”. 둘 다 이번 주에 실제로 겪은 것입니다.

매번 다시 짜던 코드를 scripts/ 로

스킬의 scripts/ 는 “같은 코드를 세 번째 짜고 있다” 는 신호에 대한 답입니다.

• render_terminal.py — 명령/출력 줄을 터미널 PNG 로. $ 줄은 초록, // 주석은 주황, FAIL/error 는 빨강. 이 사례의 이미지 1·2·4 가 이 스크립트 결과물입니다
• mask.py — --box x0,y0,x1,y1 로 픽셀화, --crop 으로 잘라내기. 위 화면이 결과

스크립트는 컨텍스트에 읽어 들이지 않고 실행만 하면 되니 토큰도 아낍니다. 6번 다시 짠 코드가 이제 한 줄 호출입니다.

검증·패키징, 그리고 ‘같은 세션에서는 못 부른다’

python3 ~/.claude/skills/skill-creator/scripts/package_skill.py .claude/skills/aiusecase-writer ./dist
# ✅ Successfully packaged skill to: ./dist/aiusecase-writer.zip

검증은 frontmatter 형식, name 규칙, description 품질, 폴더 구조를 봅니다. zip 은 다른 사람에게 건네는 배포본 — aiusecase-writer.zip.

만들자마자 Skill(skill="aiusecase-writer") 로 불러 봤더니 Unknown skill. 사용 가능한 스킬 목록은 세션이 시작될 때 한 번 읽습니다. 그래서 이 사례 자체는 스킬 파일을 직접 읽고 그 규칙대로 썼고, 다음 세션부터 /aiusecase-writer 한 줄로 부릅니다.