Claude Code 스킬, 이렇게 설계하면 실무에서 진짜 쓰입니다 — 현장에서 얻은 8가지 교훈
반복 작업을 매번 손으로 설명하는 대신, 재사용 가능한 "스킬"로 만들어두면 어떨까요? Claude Code 스킬을 여러 개 만들어 실제 개발 흐름에 녹여본 경험을 바탕으로, 설계 원칙과 함정을 정리한 글이 공유됐습니다. 단순한 사용법 소개가 아니라 실제로 돌려보며 깨진 지점들을 담고 있어서, 스킬을 도입할지 고민 중이라면 참고할 만합니다.
핵심 요약
description은 설명문이 아니라 트리거다 — "무엇을 하는가"보다 "언제 써야 하는가"- 스킬 본문은 얇게, 상세 내용은 별도 파일로 점진적 공개(progressive disclosure)
- 파이프라인 스킬과 도구 스킬을 분리하고, 상위는 조율만 담당
- 함정/교훈은 스킬 본문이 아니라 별도 지식 파일에 누적
- 스킬은 "하라"고 말할 뿐, 강제는 훅(hook)의 일
- 스킬이 많아지면 매 세션 컨텍스트 비용이 늘어난다
1. description은 "언제"를 적어야 한다
가장 먼저 강조되는 포인트입니다. 스킬의 description을 기능 설명처럼 쓰면 에이전트가 적절한 타이밍에 그 스킬을 고르지 못합니다. 에이전트 입장에서 description은 선택 기준이기 때문입니다.
- ❌ "테스트를 실행하고 결과를 요약한다"
- ✅ "코드를 수정한 뒤 커밋 전에, 변경이 기존 테스트를 깨뜨리지 않았는지 확인할 때 사용"
즉 설명문이 아니라 호출 조건문을 쓴다는 감각이 필요합니다.
2. 본문은 얇게, 디테일은 밖으로
스킬 본문에는 핵심 절차, 완료 조건, 금지사항만 남깁니다. 나머지는 역할별 디렉터리로 분리합니다.
references/— 상세 기준, 판단 근거, 배경 문서assets/— 템플릿, 보일러플레이트scripts/— 실행 스크립트
에이전트가 필요할 때만 해당 파일을 열어보게 하는 점진적 공개 구조입니다. 본문이 두꺼워지면 읽히지도 않고 컨텍스트만 잡아먹습니다.
3. 파이프라인 스킬 ≠ 도구 스킬
두 종류를 섞지 않는 것이 핵심입니다.
| 구분 | 역할 | | --- | --- | | 파이프라인 스킬 | 단계 순서만 조율 (오케스트레이션) | | 도구 스킬 | 빌드·테스트·포맷·린트 같은 범용 작업 |
상위 파이프라인은 "무엇을 어떤 순서로"만 알고, 실제 작업은 범용 스킬을 불러 씁니다. 여기에 더해 CI 순서를 로컬에서 그대로 재현하는 사전 점검 스킬을 따로 두면, CI에 올라가서야 깨지는 상황을 미리 걸러낼 수 있습니다.
4. 함정 목록은 "자라나는 지식 파일"로
겪은 함정을 스킬 본문에 계속 추가하면 본문이 비대해집니다. 대신 별도 지식 파일을 만들고, 작업이 끝날 때마다 교훈을 접두어별로 한 줄씩 누적하는 방식을 씁니다. 회고가 자산으로 쌓이는 구조라 시간이 지날수록 가치가 커집니다.
5. 범용 스킬은 우리 팀의 게이트를 모른다
흥미로운 발견입니다. 플러그인에 TDD 스킬이 이미 있더라도, 실제 TDD는 프로젝트 파이프라인 안에 따로 정의해야 했다고 합니다.
공개된 범용 스킬은 "일반적인 좋은 방법"은 알지만, 우리 팀의 통과 기준(gate)은 모릅니다.
외부 컬렉션을 그대로 가져다 쓰는 것으로는 부족하고, 팀 규칙은 결국 프로젝트 쪽에 명시해야 한다는 뜻입니다.
6. 스킬은 권고, 훅은 강제
가장 실용적인 구분입니다.
- 스킬 = "이렇게 하라"고 말한다
- 훅 = "못 하게" 막는다
반드시 지켜야 하는 절차(예: 리뷰 문서 없이 push 금지)는 스킬에 적어두는 것만으로는 부족합니다. PreToolUse 훅으로 강제해야 하고, 차단하려면 exit 2 로 종료하면 됩니다. 지켜지면 좋은 것과 반드시 지켜져야 하는 것을 구분해 배치하라는 조언입니다.
7. 스킬이 많으면 비용도 늘어난다
놓치기 쉬운 부분입니다. 그 세션에서 쓰지 않는 스킬도 목록과 설명은 매번 컨텍스트에 포함됩니다. 스킬을 무한정 늘리는 것이 공짜가 아니라는 뜻이죠. 그래서 원문에는 "언제 스킬로 분리할 가치가 있나" 체크리스트가 함께 담겨 있습니다.
8. 공개 컬렉션들의 설계 철학 비교
원문에서는 Superpowers, GSD, Karpathy 규칙 파일 등 공개 컬렉션들의 접근 방식을 비교합니다. 각각 철학이 다르기 때문에, 내 작업 방식에 맞는 쪽을 골라 참고하는 편이 좋습니다.
마무리
정리하면 이 글의 메시지는 명확합니다.
- 스킬은 언제 쓸지를 기준으로 설명하고
- 본문은 얇게, 디테일은 분리하고
- 조율과 실행을 계층으로 나누고
- 꼭 지켜야 할 건 훅으로 막고
- 늘리기 전에 비용을 계산한다
스킬을 몇 개 만들어보긴 했지만 제때 호출되지 않아 답답했던 분이라면, 먼저 description부터 "언제 써야 하는가"로 고쳐 써보시길 권합니다. 체감 차이가 가장 큰 변경일 가능성이 높습니다.