Claude Code의 hooks, slash commands, skills는 기능 이름보다 “누가 실행하는가”로 나누는 것이 가장 안전합니다. 사람이 지금 시작해야 하는 작업이면 slash command 또는 user-invoked skill을 씁니다. Claude가 반복 가능한 방법, 참고 파일, 템플릿, 체크리스트를 필요할 때 불러와야 한다면 skill을 씁니다. 특정 lifecycle event가 발생할 때마다 검증, 알림, 명령, HTTP 요청, prompt, agent handler가 반드시 실행되어야 한다면 hook을 씁니다.
2026년 6월 1일 기준 공식 Claude Code 문서에서는 custom commands가 skills에 통합되었지만 기존 .claude/commands/ 파일은 계속 동작한다고 설명합니다. 그래서 실무 질문은 “옛 commands 폴더를 써도 되는가”가 아니라 “이 작업을 사람이 시작해야 하는가, Claude가 방법으로 불러야 하는가, 실행 이벤트가 강제로 실행해야 하는가”입니다.
빠른 경로표
| 워크플로우가 필요한 것 | 먼저 쓸 것 | 보통 위치 | 피해야 할 용도 |
|---|---|---|---|
| 명시적 시작 시점, 인자, 사람의 의도 | Slash command 또는 user-invoked skill | 내장 / commands, /skill-name, 기존 .claude/commands/*.md | 사람이 입력하지 않아도 반드시 실행되어야 하는 가드레일 |
| 반복 가능한 방법, 참고 자료, 체크리스트, 스크립트, 템플릿 | Skill | .claude/skills/ | 한 번 쓰는 prompt 또는 강제 실행 규칙 |
| 이벤트 기반 검증, 알림, 로그, 차단 | Hook | settings의 hooks, command/HTTP/prompt/agent handler 호출 | 넓은 리뷰 판단, 취향 판단, 장기 기억 |
짧게 말하면 slash command는 timing, skill은 method, hook은 certainty를 맡습니다. Slash command는 사람이 누르는 버튼이고, skill은 Claude가 재사용할 작업 지식 패키지이며, hook은 이벤트에 연결된 확정 실행 규칙입니다.
세 가지 모두 반복 입력을 줄여 주지만 실패 방식은 다릅니다. command는 사람이 잊을 수 있습니다. skill은 너무 넓게 또는 너무 좁게 로드될 수 있습니다. hook은 자동으로 실행되기 때문에 잘못 만들면 매 세션을 느리게 만들거나 정상 작업까지 막습니다. 파일을 만들기 전에 먼저 실패 모드를 정해야 합니다.
Slash Commands는 사람이 시작하는 순간을 맡는다
Slash command는 사람이 시작 시점을 직접 선택해야 할 때 맞습니다. 메시지 맨 앞에서 /를 입력하고 필요한 경우 인자를 넘깁니다. 세션 제어, 리뷰 시작, 릴리스 체크리스트, 상태 요약, 실행 전 계획 만들기 같은 작업에 적합합니다.
부작용이 있는 작업에서는 이 명시성이 안전장치입니다. 배포, 삭제, 과금, 게시, 대량 파일 수정, 외부 서비스 호출, 브랜치 상태 변경이 있다면 사람이 시작 버튼을 누르는 것이 안전 모델의 일부입니다. 내부 방법은 skill에 둘 수 있지만 시작 시점은 보이게 남겨야 합니다.
Custom commands가 skills에 통합되었다고 해서 slash command 표면이 사라진 것은 아닙니다. 더 정확히는 복잡한 custom workflow를 skill로 포장하고, 필요할 때 /skill-name으로 사람이 호출하는 방식이 더 풍부해졌다는 뜻입니다. 기존 .claude/commands/*.md는 작고 안정적인 작업이면 그대로 둘 수 있습니다.
깨끗한 패턴은 이렇습니다. 내장 commands는 세션 제어에 사용합니다. 반복 절차는 user-invoked skill에 둡니다. 오래된 command file은 보조 파일이나 metadata가 필요 없을 때만 유지합니다. 사람의 시작 시점이 왜 필요한지 설명하지 못한다면 그것은 command가 아니라 skill 또는 hook 후보입니다.
Skills는 반복 가능한 방법을 담는다
Skill은 Claude가 같은 방식으로 일해야 할 때 씁니다. 필요한 단위는 좋아하는 prompt가 아니라 절차, 참고, 예시, 템플릿, 스크립트, 경계가 묶인 작업 패키지입니다. SKILL.md가 진입점이 되고 보조 파일이 방법을 지탱합니다.
PR review 기준, 마이그레이션 감사, API 문서 작성, 로컬라이징, 브라우저 QA, 릴리스 점검처럼 매번 설명하면 누락이 생기는 작업은 skill에 적합합니다. 반대로 한 번만 쓰는 짧은 지시는 아직 skill로 만들지 않는 편이 유지보수에 좋습니다.
Skill에는 호출 방식도 설계해야 합니다. Claude가 맥락에 따라 자동으로 불러도 되는 skill과, 사람이 명시적으로 불러야 하는 skill은 다릅니다. production, 과금, 외부 시스템, 대량 수정, 삭제가 관련된 skill은 user-invoked로 두어 시작 책임을 사람에게 남깁니다.
이미 skill 경로를 선택했다면 /ko/posts/claude-code-best-skills를 볼 수 있습니다. 그러나 외부 시스템 접근 부족을 skill로 해결하려고 하면 안 됩니다. Skill은 방법을 알려 주지만 GitHub, browser, database, deploy system에 대한 access를 자동으로 만들지는 않습니다. 그 문제는 MCP나 tool permission 쪽입니다.
Hooks는 이벤트와 좁은 불변식을 강제한다
Hook은 이벤트가 발생할 때마다 같은 동작이 실행되어야 하는 경우에 맞습니다. tool use 전후, session start, notification, context compaction 같은 lifecycle event에 연결되고 command, HTTP request, prompt, agent handler를 호출할 수 있습니다.
좋은 hook은 좁고 설명하기 쉽습니다. 편집 뒤 formatter를 실행하거나, 위험한 shell command 전에 protected path를 검사하거나, 세션 시작 때 작은 current context를 넣거나, 알림을 보내거나, 종료 때 짧은 작업 기록을 남기는 식입니다. 이런 규칙은 결정적으로 확인하기 쉽습니다.
넓은 판단을 hook에 넣는 것은 위험합니다. “이 review가 충분한가”는 skill, subagent, 명시적 review workflow에 둘 일입니다. “이 command가 보호 디렉터리를 삭제하려 하는가”는 hook에 둘 수 있습니다. 자동으로 실행되는 표면일수록 규칙은 더 좁아야 합니다.
처음에는 observe와 log부터 시작하세요. 신호가 안정된 뒤 block으로 바꿉니다. 나쁜 skill은 문맥을 낭비하거나 방향을 흐릴 수 있지만, 나쁜 hook은 모든 세션에 끼어들고 지연을 만들며 정상 작업을 막을 수 있습니다.
조합할 때는 각 계층의 일이 달라야 한다
강한 설정은 command, skill, hook을 함께 쓰기도 합니다. 하지만 계층이 많다고 좋은 것이 아닙니다. 각 계층이 서로 다른 불확실성을 없앨 때만 조합할 가치가 있습니다.
| 워크플로우 | Command 역할 | Skill 역할 | Hook 역할 |
|---|---|---|---|
| 릴리스 체크 | 사람이 /release-checklist를 시작 | 단계, 증거, 롤백, 보고 형식 | 잘못된 branch나 environment의 위험 명령 차단 |
| 코드 리뷰 | 사람 또는 Claude가 review 시작 | 기준, 심각도, 출력 형식 | tool use 뒤 format 또는 log 정리 |
| 배포 준비 | 사람이 /deploy-plan 시작 | 배포 체크리스트와 확인 순서 | branch, environment, approval 검증 |
나쁜 조합은 command가 skill을 반복하고, skill이 정책 강제를 맡고, hook이 섬세한 판단을 요구합니다. 좋은 조합은 command가 순간을 고르고, skill이 방법을 가르치고, hook이 하나의 invariant를 지킵니다. 한 문장으로 설명할 수 없는 계층은 제거하세요.
중단 규칙: .claude를 숨은 자동화 덩어리로 만들지 않기
섬세한 판단을 hook에 넣지 마세요. Hook은 path, command pattern, event payload처럼 좁은 조건을 다룹니다. 리뷰 품질, 설계 판단, 제품 판단은 skill 또는 명시적 review에 둡니다.
파괴적인 skill을 자동 실행하지 마세요. publish, deploy, delete, billing, production change, large rewrite는 사람이 시작해야 합니다. 방법은 skill에 둘 수 있지만 시작은 보이게 두어야 합니다.
한 번 쓰는 prompt를 skill로 만들지 마세요. Skill은 references, examples, scripts, templates로 반복 가치가 생길 때 만듭니다.
Command list를 전략으로 삼지 마세요. /help, /skills, /hooks, /context를 확인하는 것은 좋지만 설계는 timing, method, enforcement, access, runtime ownership 중 무엇이 빠졌는지로 결정됩니다. 외부 접근은 /ko/posts/claude-code-best-mcp-servers, 반복 실행 위치는 /ko/posts/routines-in-claude-code 쪽입니다.
Hook을 memory로 쓰지 마세요. 시작 전부터 보여야 하는 규칙은 project instructions나 memory surface에 둡니다. Hook은 이벤트 처리이지 숨은 정책 문서가 아닙니다.
구현 전 체크리스트
구현 전에 순서대로 답하세요. 누가 실행하는가. 한 번 하는 작업인가 반복 방법인가. 자동으로 실행되어야 하는가. 결정적으로 검사할 수 있는가. 비용, 삭제, 게시, production 변경이 있는가. 외부 접근이 부족한가. 팀원이 이 계층이 왜 있는지 이해할 수 있는가.
답이 explicit timing이면 slash command 또는 user-invoked skill부터 시작합니다. 답이 method이면 skill을 씁니다. 답이 deterministic event handling이면 hook을 설정합니다. 답이 external access이면 MCP를 봅니다. 답이 unattended runtime이면 확장 파일을 늘리기 전에 실행 위치를 먼저 고릅니다.
유지보수 가능한 Claude Code 설정은 짧게 설명됩니다. “이 command가 workflow를 시작하고, 이 skill이 방법을 담고, 이 hook이 하나의 invariant를 지킨다.” 이 설명이 길어지면 확장이 아니라 복잡도가 늘어난 것입니다.
팀 인수인계 기록으로 남기기
문제는 처음 파일을 만들 때보다 몇 주 뒤 다른 사람이 .claude를 열어 보는 순간에 더 자주 생깁니다. 새 slash command, skill, hook을 추가할 때마다 누가 실행하는지, 실패하면 누가 보는지, 어떤 side effect를 허용하는지, 언제 삭제해야 하는지 기록하세요. 위치는 SKILL.md, project rules, runbook, PR description 중 어디라도 괜찮지만, 파일 이름만으로 의도가 전달된다고 가정하면 안 됩니다.
Slash command 기록은 사람이 왜 그 순간을 골라야 하는지 설명해야 합니다. /release-check는 release가 중요해서가 아니라 branch, approval state, rollback window, 공지 시점을 사람이 확인해야 해서 필요합니다. 입력이 모두 기계적으로 확인된다면 일부는 hook이나 CI check가 맡을 수 있습니다. 판단 절차, 예외, report format이 필요하다면 그 방법은 skill로 분리하고 command는 시작 버튼으로 남깁니다.
Skill 기록은 어떤 방법을 재사용하는지 보여야 합니다. 좋은 skill은 목표, 필요한 증거, 단계, 출력 형식, 금지된 행동, 실패 처리 방식을 가집니다. 한 번 쓰는 prompt를 포장하는 것은 팀 자산이 아닙니다. 반대로 매번 반드시 실행되어야 하는 규칙을 skill에 두면 Claude가 잊을 가능성이 남습니다. 그런 규칙은 hook, CI, 또는 별도 runtime owner로 보내는 편이 안전합니다.
Hook 기록은 자동으로 지킬 invariant를 설명해야 합니다. Hook에 맞는 일은 tool use logging, 위험한 path 차단, formatter 실행, missing test 알림, audit endpoint 전송처럼 좁고 검사 가능한 동작입니다. Product judgment, 설계 판단, 리뷰 품질, 예외 설명이 필요하면 hook이 아니라 skill이나 명시적 review로 돌려야 합니다. Hook의 장점은 예측 가능성이지 토론을 없애는 능력이 아닙니다.
기존 설정을 정리할 때는 owner 없는 hook, 지원 자료가 없는 skill, skill 이름만 다시 부르는 command부터 제거하세요. 성숙한 Claude Code 설정은 많이 추가한 설정이 아니라 각 계층의 trigger, owner, failure path, rollback을 설명할 수 있는 설정입니다.
자주 묻는 질문
Slash commands와 skills는 이제 같은 것인가요?
같지 않습니다. custom commands가 skills에 통합되었고 skill을 /skill-name으로 호출할 수는 있습니다. 그러나 slash command는 여전히 명시적 호출 표면입니다. Command는 timing, skill은 packaging으로 보세요.
모든 .claude/commands를 skill로 옮겨야 하나요?
아닙니다. 보조 파일, metadata, dynamic context, tool control, discoverability가 필요할 때만 옮기면 됩니다. 작고 안정적인 command는 그대로 둘 수 있습니다.
Hooks가 skills보다 더 믿을 만한가요?
더 deterministic할 뿐 항상 더 좋은 것은 아닙니다. Hook은 configured event에 반응하므로 log, formatter, notification, narrow guard에 좋습니다. Skill은 method, context, examples, checklist에 좋습니다.
추가하기 전에 무엇을 확인하나요?
/help 또는 commands reference, /skills, /hooks, /context를 확인하세요. 그래도 빠진 계층을 말할 수 없다면 새 surface를 만들지 않는 편이 안전합니다.
프로젝트 전체 규칙은 어디에 두나요?
항상 보여야 하는 넓은 규칙은 CLAUDE.md나 memory surface에 둡니다. 반복 절차는 skill, 이벤트 기반 좁은 제약은 hook입니다. Hook 안에 전체 프로젝트 정책을 숨기지 마세요.
짧은 결론
실행 주체로 고르세요. Slash command는 사람이 명시적으로 시작할 때, skill은 재사용 가능한 방법을 담을 때, hook은 deterministic lifecycle event를 강제할 때 씁니다. 조합은 각 계층의 일이 다를 때만 합니다. 외부 접근과 반복 실행 문제를 skills나 hooks만으로 해결하려고 하지 않는 것이 Claude Code 설정을 오래 유지하는 방법입니다.