Claude Code 스킬 패턴 — 반복 작업을 재사용 가능한 스킬로 설계하는 법과 실무에서 쌓으며 배운 것

Claude Code 스킬을 설계하는 원칙과, 여러 스킬을 실제 개발 흐름에서 같이 쓰면서 확인한 점을 정리했습니다.

• 스킬의 description은 설명문이 아니라 트리거. "무엇을 하는가"보다 "언제 써야 하는가"를 적어야 에이전트가 제때 고름
• 본문은 핵심 절차·완료 조건·금지사항만 남기고, 상세 기준·템플릿·스크립트는 references/·assets/·scripts/로 분리(점진적 공개)
• 파이프라인 스킬과 도구 스킬을 분리: 상위 파이프라인은 단계만 조율하고, 빌드·테스트·포맷·린트는 범용 스킬을 불러 씀. CI 순서를 로컬에서 그대로 재현하는 사전 점검 스킬도 따로 둠
• 함정 목록은 스킬 본문이 아니라 별도 지식 파일로 키움: 작업이 끝날 때마다 교훈을 접두어별로 한 줄씩 누적
• 범용 스킬은 팀의 게이트를 모름: 플러그인에 TDD 스킬이 있어도 실제 TDD는 프로젝트 파이프라인 안에 따로 있어야 했음
• 스킬은 "하라"고 말하고, 훅은 "못 하게" 막음: 반드시 지켜야 하는 절차(예: 리뷰 문서 없이 push 금지)는 PreToolUse 훅으로 강제 — 차단하려면 exit 2
• 스킬이 많으면 매 세션 비용도 늘어남: 쓰지 않는 스킬도 목록·설명은 매번 컨텍스트에 들어옴
• 공개 컬렉션(Superpowers, GSD, Karpathy 규칙 파일 등)의 설계 철학 비교와 "언제 스킬로 분리할 가치가 있나" 체크리스트 포함