좋은 커맨드 하나가 '매일 30분'의 의사결정을 없앤다
팀에서 반복되는 작업은 늘 비슷한 곳에서 시간을 잡아먹습니다. 리뷰를 할 때 무엇을 볼지, 테스트를 어디까지 돌릴지, 릴리스 전에 어떤 체크리스트를 따라야 할지, 이런 판단을 매번 다시 꺼내야 하기 때문입니다. 손이 가는 시간도 문제지만, 더 큰 문제는 기준이 흔들린다는 점입니다.
Claude Code에서 이 문제를 가장 깔끔하게 줄이는 방법은, 반복 프롬프트를 머릿속이 아니라 파일로 옮기는 것입니다. Claude Code는 스킬(Skills)을 /skill-name 형태의 슬래시 명령처럼 직접 호출할 수 있습니다. 즉, "한 번 잘 쓴 프롬프트"를 "계속 재사용되는 작업 절차"로 바꿀 수 있습니다.1
이 챕터의 핵심은 단순합니다.
반복 업무를 프로젝트나 개인 스킬로 저장하고
호출은
/이름한 줄로 끝내며입력과 출력 형식을 고정해 결정의 편차를 줄입니다.
이 관점에서 보면 커스텀 슬래시 커맨드는 단순 편의 기능이 아니라, 팀의 SOP(표준 운영 절차)를 Claude Code 안에 심는 방법입니다.
Claude Code에서 '커스텀 슬래시 커맨드'는 사실상 스킬이다
공식 문서 기준으로 Claude Code의 재사용 가능한 확장 단위는 Skills입니다. 스킬은 SKILL.md 파일에 지침을 담아 두고, Claude가 상황에 맞게 자동으로 쓰거나, 사용자가 /skill-name으로 직접 호출할 수 있습니다.1
이 점이 중요합니다. 많은 사용자가 "슬래시 커맨드"를 별도 기능으로 생각하지만, 실제 운영에서는 다음처럼 이해하는 편이 더 정확합니다.
내장 슬래시 명령:
/help,/clear,/resume처럼 Claude Code 자체 기능을 제어하는 명령커스텀으로 만드는 재사용 명령: 보통 Skills로 구현하고
/이름으로 호출
즉, 팀이 반복 업무를 1줄 명령으로 만들고 싶다면, 실전에서는 대부분 프로젝트 스킬을 설계하는 방향으로 가는 것이 안전합니다.1
어디에 두는가: 개인 스킬 vs 프로젝트 스킬
스킬은 저장 위치에 따라 적용 범위가 달라집니다.1
개인 스킬:
~/.claude/skills/<skill-name>/SKILL.md프로젝트 스킬:
.claude/skills/<skill-name>/SKILL.md플러그인 스킬: 플러그인 디렉터리 내부
skills/
실무에서 가장 중요한 구분은 두 가지입니다.
개인 스킬: 어떤 저장소에서도 쓰는 나만의 작업 습관
개인 스킬은 모든 프로젝트에서 재사용하는 작업에 어울립니다.
예를 들면:
긴 로그를 읽고 원인 후보 3개만 뽑는 디버깅 스킬
내가 선호하는 리뷰 포맷으로 정리하는 리뷰 스킬
회의록/요약/체크리스트를 만드는 개인 생산성 스킬
프로젝트 스킬: 팀이 같은 방식으로 해야 하는 작업
프로젝트 스킬은 저장소에 커밋되므로, 팀 표준을 강제하기 좋습니다.1
예를 들면:
/review를 실행하면 반드시 팀 리뷰 포맷으로 출력/release-check를 실행하면 팀 릴리스 절차를 따름/onboard-ticket를 실행하면 티켓 분석 문서를 특정 위치에 기록
핵심은 이겁니다.
개인 취향은 개인 스킬에, 팀의 합의는 프로젝트 스킬에 둔다.
스킬 이름이 곧 명령 이름이다
스킬은 디렉터리 이름과 frontmatter의 name을 기준으로 식별되고, /skill-name 형태로 호출할 수 있습니다.1
예를 들어 아래 구조라면:
.claude/
skills/
review-pr/
SKILL.md세션에서 /review-pr로 호출하는 식입니다.
이 방식의 장점은 단순합니다.
이름이 곧 호출 방식이라 외우기 쉽고
스킬이 파일 단위로 버전 관리되며
팀이 같은 이름을 쓰므로 결과 형식도 안정됩니다.
너무 중요한 스킬 이름은 길게 짓지 않는 편이 좋습니다. 하지만 더 중요한 기준은 "짧음"보다 역할이 분명한가입니다. /review, /release-check, /test-gen, /onboard-ticket처럼 이름만 보고 목적이 떠오르는 편이 실제 운영에서 강합니다.
스킬 디렉터리 구조: SKILL.md 하나로 시작하고, 필요하면 지원 파일을 붙인다
공식 문서가 권장하는 기본 구조는 다음과 같습니다.1
my-skill/
├── SKILL.md # 메인 지침(필수)
├── template.md # Claude가 채울 템플릿(선택)
├── examples/
│ └── sample.md # 기대 출력 예시(선택)
└── scripts/
└── validate.sh # 실행 가능한 보조 스크립트(선택)처음부터 복잡하게 만들 필요는 없습니다. 대부분은 SKILL.md 하나만으로도 충분합니다. 다만 스킬이 자주 쓰이고 산출물 형식이 중요해지면 다음이 도움이 됩니다.
template.md: 온보딩 문서, 릴리스 노트, 리뷰 결과 템플릿 고정
examples/: 좋은 출력 예시를 넣어 형식을 더 안정화
scripts/: 검증용 셸 스크립트, 리포트 생성 스크립트 연결
즉, 스킬은 "긴 프롬프트 한 장"에서 출발하지만, 자주 쓰일수록 작은 도구 상자로 진화합니다.
SKILL.md의 기본 구성: 언제 쓰는지, 무엇을 하라는지, 무엇을 남기는지
좋은 스킬은 단순히 "무엇을 해라"만 적지 않습니다. 최소한 다음 세 덩어리가 있어야 안정적으로 작동합니다.
1) 언제 써야 하는가(When to Use)
Claude가 자동으로 판단하거나, 팀원이 직접 호출할 때 어떤 상황에 쓰는지 분명해야 합니다.
예:
PR 변경 파일이 10개 이상일 때
릴리스 전 체크리스트가 필요할 때
재현이 어려운 UI 버그를 정리할 때
2) 어떤 순서로 진행하는가(Instructions)
이 부분이 실질적인 작업 절차입니다. 애매한 수식어보다 단계가 중요합니다.
예:
변경 파일을 요약한다.
위험을 분류한다.
누락된 테스트를 점검한다.
결과를 지정 포맷으로 정리한다.
3) 무엇을 산출해야 하는가(Output)
출력 형식을 고정해야, 사람과 Claude 모두 다시 정리하는 비용이 줄어듭니다.
예:
Markdown 섹션 4개로만 출력
각 이슈에
file:line포함마지막에
How to verify를 반드시 포함특정 파일에 저장
실전에서는 이 세 가지가 거의 전부입니다. 스킬이 실패하는 가장 흔한 이유는 '절차가 없다'보다 출력 형식이 없다는 데 있습니다.
자동 호출과 직접 호출을 구분하라
공식 문서에 따르면 스킬은 Claude가 상황상 적절하다고 판단하면 자동으로 쓸 수 있고, 사용자가 /skill-name으로 직접 호출할 수도 있습니다. 그런데 모든 스킬이 자동 호출되길 원하는 것은 아닙니다. 배포, 릴리스, 대규모 수정처럼 명시적 호출만 허용하고 싶은 작업도 있습니다.1
이럴 때는 frontmatter의 disable-model-invocation: true를 고려할 수 있습니다.1
이 설정이 유용한 경우는 다음과 같습니다.
배포/릴리스처럼 의도적 실행만 허용해야 할 때
과도하게 자동 호출되면 비용이 커지는 스킬일 때
사람 승인 없이 돌아가면 위험한 절차일 때
즉, 스킬 설계에서는 "좋은 절차를 만드는 것"만큼 언제 자동으로 켜지지 않게 할지도 중요합니다.
컨텍스트 절약 관점에서 보는 스킬의 장점
스킬의 가장 큰 장점은 단지 '편하다'가 아닙니다. 컨텍스트를 절약한다는 점입니다.1
같은 긴 지침을 매번 대화에 붙여 넣으면 다음 문제가 생깁니다.
토큰이 낭비되고
프롬프트가 길어져 읽기 어려우며
사람마다 조금씩 다르게 써서 편차가 커집니다.
반면 스킬로 빼 두면:
호출은 짧아지고
절차는 파일로 고정되며
필요할 때만 불러오므로 세션이 덜 무거워집니다.
이 책 전체에서 강조한 "반복 설명은 영속 지침과 모듈로 옮겨라"는 원칙이 여기서도 그대로 적용됩니다.
스킬 설계 원칙 5가지
실무에서 오래 살아남는 스킬은 공통점이 있습니다.
1) 한 스킬은 한 가지 일을 한다
/review-and-fix-and-test-and-commit처럼 모든 걸 한 번에 하려는 스킬은 금방 불신을 부릅니다. 리뷰는 리뷰, 테스트 생성은 테스트 생성, 릴리스 점검은 릴리스 점검으로 쪼개는 편이 낫습니다.
2) 입력을 모호하게 두지 않는다
스킬이 받는 입력이 자유형이면 편해 보이지만, 실제로는 편차가 커집니다. 가능하면 argument-hint 또는 스킬 문서 안에서 "무엇을 넣어야 하는지"를 분명히 적어 두세요.1
예:
<PR 목적 또는 focus><티켓 번호와 한 줄 설명><대상 파일/함수/동작>
3) 출력 형식을 강제한다
결과가 항상 같은 구조로 나와야, PR 코멘트·문서·체크리스트로 바로 옮길 수 있습니다.
4) 중단 조건을 넣는다
스킬은 친절해서 과하게 넓은 탐색으로 흐르기 쉽습니다. 예를 들어 "파일이 너무 많으면 먼저 범위를 좁히라고 요청", "확신이 없으면 질문 목록만 출력" 같은 중단 조건이 있어야 합니다.
5) 스킬도 코드처럼 리뷰한다
프로젝트 스킬은 결국 팀의 운영 규칙입니다. 그러니 .claude/skills/ 변경도 PR 리뷰 대상이어야 합니다. 릴리스 절차가 바뀌면 릴리스 스킬도 같이 바뀌어야 하고, 리뷰 기준이 바뀌면 리뷰 스킬도 갱신되어야 합니다.
바로 쓸 수 있는 프로젝트 스킬 템플릿 4종
아래 템플릿은 '반복 업무를 1줄 명령으로 바꾸는' 출발점입니다. 모두 프로젝트 스킬 기준이며, 그대로 복사해 .claude/skills/ 아래에 두고 시작해도 됩니다.
1) /onboard-ticket
티켓을 읽고 다음 세션까지 이어갈 수 있는 온보딩 문서를 만드는 스킬입니다.
---
name: onboard-ticket
description: 티켓을 분석해 관련 코드, 질문, 계획을 온보딩 문서로 정리한다
context: fork
disable-model-invocation: true
---
# When to Use
- 새 이슈나 티켓을 맡았을 때
- 다음 세션을 위한 인수인계 문서가 필요할 때
# Instructions
1. 입력으로 받은 티켓 번호/설명을 바탕으로 관련 코드와 파일 경로를 탐색한다.
2. 요구사항이 모호하면 질문 목록을 만든다.
3. 변경 파일 후보, 테스트 전략, 검증 방법을 포함한 실행 계획을 쓴다.
4. 결과는 아래 형식으로 정리한다.
# Output
- 문제 요약
- 관련 파일/모듈
- 열린 질문
- 실행 계획
- How to verify
이 스킬의 목적은 "지금 당장 코딩"이 아니라, 다음 행동이 분명한 상태를 만드는 것입니다.2) /review-pr
팀 기준으로 PR을 일관되게 검토하는 스킬입니다.
---
name: review-pr
description: 현재 변경 사항을 팀 기준으로 리뷰한다
---
# When to Use
- PR을 올리기 전 셀프 리뷰
- 리뷰어가 보기 전에 1차 점검이 필요할 때
# Instructions
1. 변경 파일과 diff를 읽는다.
2. 정확성, 보안, 테스트 누락, 불필요한 복잡도를 점검한다.
3. 포맷팅만 지적하지 말고 행동/리스크 중심으로 평가한다.
# Output
## Critical
- [file:line] 문제
- 이유
- 수정안
- How to verify
## Warning
(동일 형식)
## Suggestion
(동일 형식)
## Summary
- Approve / Request changes / Discuss
- 가장 중요한 리스크 1~2개
핵심은 "리뷰를 잘해줘"가 아니라 리뷰 결과를 바로 코멘트로 옮길 수 있게 만드는 것입니다.3) /test-gen
테스트 추가를 표준화하는 스킬입니다.
---
name: test-gen
description: 지정한 대상에 대한 테스트 케이스와 검증 전략을 만든다
---
# When to Use
- 버그 수정 후 회귀 테스트가 필요할 때
- 새 기능에 최소 테스트를 추가해야 할 때
# Instructions
1. 관련 구현과 기존 테스트 패턴을 확인한다.
2. Happy path / Edge / Error로 케이스를 나눈다.
3. 외부 의존성은 필요한 최소 범위로 mock 전략을 제안한다.
# Output
1. 추가/수정할 테스트 파일 목록
2. 테스트 케이스 목록과 각 케이스의 필요 이유
3. How to verify(실행 명령과 기대 결과)4) /release-check
릴리스 직전 누락을 줄이기 위한 점검 스킬입니다.
---
name: release-check
description: 릴리스 전 체크리스트를 실행해 요약을 만든다
context: fork
disable-model-invocation: true
---
# When to Use
- 릴리스 직전
- 큰 변경이 포함된 배포 전 검증
# Instructions
1. 변경 범위를 요약한다.
2. 테스트/린트/타입체크 결과를 점검한다.
3. 마이그레이션, 롤백 포인트, 사용자 영향 범위를 정리한다.
4. 릴리스 노트 초안을 만든다.
# Output
- Release Summary
- Risks & Mitigations
- Verification (pre)
- Release Notes (draft)
- Verification (post)지원 파일을 붙이면 스킬이 더 안정된다
스킬이 자주 쓰이기 시작하면, SKILL.md 안에 모든 걸 우겨 넣지 말고 지원 파일로 분리하는 편이 좋습니다.1
예를 들어:
template.md: 온보딩 문서나 릴리스 노트 형식examples/sample.md: 좋은 리뷰 결과 예시scripts/validate.sh: 출력 후 실행할 검증 스크립트
이렇게 하면 SKILL.md는 "언제, 왜, 어떻게"를 설명하고, 세부 형식과 실행 로직은 파일로 빼 둘 수 있어 유지보수가 쉬워집니다.
팀에 정착시키는 운영 팁
좋은 스킬을 만들어도 팀이 안 쓰면 아무 의미가 없습니다. 실제로는 기술보다 운영 방식이 중요합니다.
README보다 호출 이름을 먼저 맞춘다
팀이 외워야 하는 것은 문서 경로가 아니라 호출 이름입니다. /review-pr, /test-gen, /release-check처럼 자주 쓰는 이름부터 합의하세요.
PR 템플릿과 연결한다
예를 들어 PR 템플릿에 "올리기 전 /review-pr 실행"을 명시하면, 스킬이 선택이 아니라 루틴이 됩니다.
스킬 변경도 운영 변경으로 본다
.claude/skills/ 변경은 단순 문서 수정이 아니라 팀 작업 방식의 변경입니다. 그래서 변경 이유를 남기고, 가능하면 코드 오너나 담당자가 리뷰하는 편이 좋습니다.
자주 겪는 문제와 해결
스킬이 보이지 않을 때
가장 먼저 경로를 확인합니다. 프로젝트 스킬은 .claude/skills/<name>/SKILL.md 구조여야 합니다.1
자동 호출이 과할 때
자주 불려선 안 되는 스킬이라면 disable-model-invocation: true를 검토하세요.1
결과 편차가 클 때
대개 입력이 모호하거나 출력 형식이 느슨해서 그렇습니다. When to Use, Instructions, Output 세 부분을 더 단단히 고치면 대부분 안정됩니다.
스킬이 점점 비대해질 때
하나의 스킬이 여러 일을 떠안고 있을 가능성이 큽니다. 기능을 나누고, 템플릿/예시/스크립트는 지원 파일로 분리하세요.
정리: 반복 업무는 '설명'하지 말고 '호출'하게 만들어라
반복 업무를 매번 자연어로 길게 설명하는 팀은, 결국 품질이 사람의 기억력과 체력에 좌우됩니다. 반대로 반복 업무를 스킬로 만들어 /이름 한 줄로 호출하는 팀은, 작업 기준이 파일로 고정되고 계속 개선됩니다.
이 장의 결론은 간단합니다.
팀 표준은 프로젝트 스킬로 둔다.
개인 습관은 개인 스킬로 둔다.
한 스킬은 한 가지 일만 하게 만든다.
출력 형식을 강제해 바로 쓸 수 있게 만든다.
자주 쓰는 절차는 '설명'이 아니라 '호출'로 바꾼다.
이 구조가 자리 잡히면 Claude Code는 단순히 프롬프트를 잘 받아주는 도구가 아니라, 팀의 반복 업무를 기억하는 작업 플랫폼이 됩니다.
참고
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.