Skills부터 Hooks까지
Claude Code를 처음 쓰면 “프롬프트 잘 쓰면 되는 거 아닌가”라고 생각하게 된다. 그런데 비슷한 작업을 열 번 쯤 반복하다 보면 매번 같은 설명을 하고 있는 자신을 발견하게 된다. 회의록 형식을 다시 설명하고, 코드 리뷰 기준을 다시 설명하고, 이 반복 설명 비용이 쌓이기 시작할 때, 아래 기능들이 필요해진다
Skills – 반복 작업을 파일 밖에 빼기
Skills는 “저장해둔 프롬프트”가 아니다. 더 정확하게는 반복되는 작업의 절차를 담은 작은 폴더다
어떤 작업을 Skill로 만들어야 할까? 기준은 세 가지다
- 결과물 형식이 매번 비슷한 작업: 회의록, 주간 브리프, 코드 리뷰처럼 찾는 항목이 고정된 것들
- 사람마다 편차를 줄여야 하는 작업: 브랜드 보이스, 법무 문구처럼 “누가 하든 비슷해야 하는” 것들
- 도구만 있어서는 안 되는 작업: Slack에 연결했다고 “어느 채널에 어떤 형식으로”까지 알지는 못한다
반대로 매번 주제가 바뀌는 탐색적 대화나 일회성 브레인스토밍은 그냥 대화로 푸는 게 낫다
Skill 폴더 구조
meeting-notes/ ├── SKILL.md # 언제, 어떤 순서로 실행할지 ├── references/ # 고정 배경 정보 ├── assets/ # 산출물 형식 템플릿 ├── examples/ # 잘 된 결과물 예시 └── scripts/ # 보조 검증 스크립트
한 파일에 모든 것을 몰아넣지 않는 이유가 있다. Claude는 먼저 SKILL.md의 상단 정보만 보고 “이 상황에서 Skill이 필요한가”를 판단하고, 필요할 때만 나머지를 더 읽는다. 폴더 구조 자체가 필요한 정보만 단계적으로 읽게 하는 설계다
Skill 작성의 핵심 두 가지
description은 홍보 문구가 아니라 호출 기준이다. “언제 이 Skill을 써야 하는가”를 판단하는 힌트를 담아야 한다. 실제 사용자가 할 법한 표현을 여러 개 넣어두는 게 효과적이다
--- name: meeting-notes description: Use for meeting notes, meeting summaries, or when the user asks "회의록 만들어줘", "미팅 메모 정리해줘", "오늘 회의 요약해줘" ---
Gotchas는 일반론이 아니라 Skill이 자주 망가지는 방식을 적는 곳이다
# Gotchas - 불확실한 정보는 추정하지 말고 `확인 필요`로 남길 것 - 지난 회의 내용을 이번 회의 내용인 것처럼 쓰지 말 것
만들고 끝내면 안 된다: 테스트 체크리스트
| 테스트 | 확인 내용 |
| trigger test | 다양한 표현에서 잘 불리는가 |
| negative test | 무관한 요청에서 괜히 발동하지 않는가 |
| format test | 출력이 템플릿을 실제로 따르는가 |
| gotcha test | 불확실할 때 추정하지 않고 확인 필요로 남기는가 |
Plugins – 역할 단위 설치 패키지
Skills가 “이 작업 절차를 써 주세요”라면, Plugin은 “이 역할을 바로 설치해서 쓰세요”에 가깝다
Plugin 하나 안에는 skills, agents, hooks, MCP 설정까지 함께 들어있다. 예를 들어 코드 리뷰 Plugin을 설치하면 /review 커맨드, 코드 리뷰 에이전트, 보안 리뷰 에이전트, lint/test 훅, GitHub MCP 설정이 한 번에 딸려온다
언제 Plugin이 필요한가
팀 단위 온보딩 시간을 줄이고 싶을 때, skill과 hook, MCP를 함께 배포해야 할 때. 반대로 개인 실험이나 아직 검증 안 된 워크플로우는 .claude/ 폴더에서 먼저 빠르게 반복하고, 공유할 준비가 됐을 때 Plugin으로 올리는 것이 권장 순서다
MCP – 외부 도구를 연결하는 규격
MCP는 Claude Code가 GitHub, Slack, Notion, DB 같은 외부 시스템에 실제로 닿을 수 있게 하는 연결 규격이다
여기서 중요한 착각이 있다. “Slack을 연결했으니 알아서 잘 쓰겠지”는 틀렸다. MCP는 길을 열어주는 층이고, “어느 채널에 어떤 형식으로 어떤 말투로”는 Skill이 정리해줘야 한다. 연결과 사용법은 다른 문제다
그리고 MCP는 많이 연결할수록 좋지 않다. 도구가 많아질수록 Claude가 어떤 도구를 언제 써야 할지 판단이 흐려지고, 토큰도 더 소모되고, 보안 표면도 넓어진다. 자주 쓰는 경로만 열어두고 나머지는 끄는 편이 더 안정적이다
Hooks – 반드시 지켜야 할 규칙을 실행 환경에 고정하기
Hook의 핵심은 한 문장으로 정리된다. 기억해주길 기대하지 말고, Hook으로 강제한다
Hook이 효과적인 네 가지 용도
- 위험 행동 차단: 민감 파일 편집 막기, 프로덕션 배포 전 승인 요구
- 자동 후처리: prettier, eslint, 테스트 실행처럼 사람이 자꾸 잊어버리는 검증을 자동으로 붙이기
- 알림: 긴 작업이 끝나는지 계속 지켜보지 않아도 되게
- 요약과 필터링: 긴 출력을 줄여 컨텍스트 오염 방지
반대로 매 편집마다 무거운 검증을 붙여 속도가 크게 떨어지거나, 의미 판단이 필요한 복잡한 리뷰는 Hook보다 사람이 직접 하는게 낫다. 좋은 Hook은 많은 Hook이 아니라, 팀이 반복해서 놓치는 부분을 짧고 단단하게 막아주는 Hook이다
Subagents – 메인 세션을 깨끗하게 유지하기
Subagent의 가치는 병렬 처리가 아니다. 진짜 가치는 메인 세션을 오염시키지 않는 것이다
대규모 코드 탐색, 독립적인 리뷰, 장시간 테스트처럼 메인 세션과 어느 정도 분리되어도 되는 작업에 Subagent를 쓴다. 반대로 메인 세션과 촘촘하게 상태를 공유해야 하거나 파일 충돌 가능성이 있는 동시 수정에는 맞지 않는다
자동화 표면 선택 – 헷갈리는 네 가지 구분
Claude Code의 자동화 기능이 여러 개 생기면서 “뭘 써야 하지?”가 헷갈리기 시작한다. 이름보다 트리거가 무엇인가로 구분하면 훨씬 명확하다
| 트리거 | 적합한 기능 | 예시 |
| 시간이 오면 | Scheduled Tasks | 매주 월요일 경쟁사 브리프 |
| 외부 사건이 생기면 | Channels | CI 실패, 모니터링 경보 |
| 사람이 멀리서 조작 | Remote Control | 외근 중 배포 상태 확인 후 후속 지시 |
| 새 작업을 던지고 나중에 결과 수거 | Dispatch | 밤새 시장 조사 돌리고 아침에 결과 회수 |
Remote Control과 Channels의 차이를 헷갈린다면 “누가 먼저 말을 거는가”로 기억하면 된다. Remote Control은 사람이 세션에 먼저 말을 건다. Channels는 시스템이 세션에 먼저 신호를 보낸다
어떤 순서로 시작해야 하나
한 번에 모든 기능을 붙이려 하면 어디서 막혔는지 파악하기 어렵다. 권장 순서는 이렇다
CLAUDE.md와 기본 규칙 먼저: 가장 자주 설명하는 것들을 파일로 빼내기- Skill 하나: 구조가 뚜렷한 반복 작업부터 (회의록이나 주간 브리프가 시작하기 좋다)
- Hook 최소화: 팀이 반복해서 놓치는 검증 한두 가지만
- MCP는 나중에: 자주 쓰는 외부 도구 하나만 조심스럽게
규약과 검증 없이 연결과 자동화부터 붙이면, 나중에 붙이는 확장이 오히려 더 위험해진다
출처 – Claude Code Claude Cowork 마스터 가이즈 – 제작자 CHOI