이 글에서 다루는 내용

이 글에서는 Claude Code의 세 가지 확장 요소인 커맨드(slash command), 스킬(skill), 훅(hook)을 쉬운 예시와 함께 설명하고, 각각을 어디에 어떻게 만드는지(적용 방법)와 언제 동작하는지(발동 시점)를 정리합니다. 셋의 발동 주체와 시점이 어떻게 다른지 비교한 뒤, 앱·서버 프로젝트를 생성할 때마다 반복하는 초기 세팅 작업을 커맨드로 등록해 자동화하는 실전 활용까지 다룹니다. 커맨드가 잘 맞는 경우와 셸 스크립트가 더 나은 경우의 구분, 인자 활용, 어디에 파일을 두어야 하는지도 함께 살펴봅니다.

커맨드, 스킬, 훅의 관계

최근 Claude Code에서는 커스텀 슬래시 커맨드가 스킬로 통합되었습니다(v2.1.101, 2026년 4월). .claude/commands/와 .claude/skills/ 둘 다 동작하지만 같은 이름이면 스킬이 우선합니다. 그래도 개념을 이해하기 위해 셋을 나누어 설명합니다.

커맨드 - "내가 부르는 단축키"

한 줄로 비유하면, 자주 쓰는 긴 지시문을 /이름 한 단어로 저장해 둔 매크로입니다.

쉬운 예시로 GitHub 이슈 번호를 주면 그것을 분석해 고치는 /fix-issue 커맨드를 보겠습니다. .claude/commands/fix-issue.md 파일로 만듭니다.

---
description: GitHub 이슈를 분석하고 수정합니다
---
이슈 #$ARGUMENTS 를 찾아서 고쳐줘. 다음 순서로:
1. 이슈 내용 파악
2. 관련 코드 수정
3. 테스트 추가

적용 방법은 프로젝트 루트의 .claude/commands/<이름>.md(또는 스킬 형식이면 .claude/skills/<이름>/SKILL.md)로 저장하는 것입니다. ~/.claude/에 두면 모든 프로젝트에서 쓸 수 있습니다.

발동 시점은 내가 직접 입력할 때만입니다. 인자는 명령 뒤에 붙여 전달합니다.

/fix-issue 1234

$ARGUMENTS 자리표시자를 넣으면 명령 뒤에 입력한 내용이 인자로 전달됩니다. 예를 들어 fix-issue.md에 "이슈 #$ARGUMENTS를 찾아 고쳐줘"라고 쓰고 /fix-issue 1234로 호출하는 식입니다.

스킬 - "Claude가 알아서 꺼내 쓰는 지식"

한 줄로 비유하면, "이런 상황이 오면 이 방법대로 해"라고 적어 둔 매뉴얼입니다. Claude가 맥락을 보고 스스로 판단해 적용합니다.

쉬운 예시로 커밋 메시지 작성 스킬을 보겠습니다. .claude/skills/commit-messages/SKILL.md 파일입니다.

---
name: generate-commit-messages
description: git diff로부터 명확한 커밋 메시지를 생성. 커밋 메시지를 쓰거나 스테이징된 변경을 리뷰할 때 사용.
---
## 지침
1. `git diff --staged`로 변경 내용 확인
2. 요약은 50자 이내, 상세 설명은 아래에

적용 방법은 디렉터리 + SKILL.md 파일 구조이며, 프로젝트용은 .claude/skills/, 모든 프로젝트에서 쓸 개인용은 ~/.claude/skills/에 둡니다.

발동 시점이 커맨드와 결정적으로 다릅니다. 커맨드가 수동 호출인 것과 달리, 스킬은 모델이 호출합니다. Claude가 맥락에 따라 자율적으로 사용합니다. 핵심은 description입니다. YAML frontmatter가 Claude가 언제 이 스킬을 불러올지를 제어합니다. 위 예시처럼 "커밋 메시지를 쓸 때 사용"이라고 적어두면, 내가 "커밋 메시지 만들어줘"라고 할 때 Claude가 알아서 이 스킬을 적용합니다. 물론 /generate-commit-messages로 수동 호출도 가능합니다. frontmatter로 자동 호출을 켤지, 수동만 둘지, 둘 다 할지를 제어합니다.

훅 - "이벤트가 터지면 자동으로"

한 줄로 비유하면, "이 일이 일어나면 무조건 이걸 실행해"라는 자동 트리거입니다. 내가 시키지 않아도 조건이 맞으면 돌아갑니다.

쉬운 예시로 파일 편집 후 자동 포맷팅을 보겠습니다.

hooks:
  PostToolUse:
    - matcher: "Edit"
      hooks:
        - type: command
          command: "./scripts/format.sh"

이것은 "Edit 도구가 실행된 후(PostToolUse)마다 포맷 스크립트를 돌려라"는 뜻입니다.

적용 방법은 두 가지입니다. 전역/프로젝트 설정 파일(settings.json)의 hooks 항목에 정의하면 항상 적용됩니다. 또는 에이전트·스킬·슬래시 커맨드의 YAML frontmatter 안에 직접 끼워넣으면 그 컴포넌트가 실행되는 동안에만 적용됩니다(생명주기에 한정). 세션 안에서 /hooks를 치면 설정된 훅을 읽기 전용으로 둘러볼 수 있는 브라우저가 열립니다.

발동 시점은 이벤트 기반입니다. 도구 호출 전(PreToolUse), 후(PostToolUse), 작업 종료 시(Stop) 등 정해진 이벤트가 발생하면 자동 실행됩니다. matcher로 어떤 도구/명령에 반응할지 좁힙니다. 예를 들어 PreToolUse 훅에 matcher: "Bash"를 걸면 Bash 명령이 실행되기 전에 보안 검증 스크립트를 돌릴 수 있습니다. 또한 UserPromptExpansion 훅은 사용자가 입력한 슬래시 커맨드가 프롬프트로 확장될 때 발동되어, 승인 파일이 없으면 /deploy를 막거나 리뷰 스킬에 팀의 체크리스트를 덧붙이는 데 쓸 수 있습니다.

세 가지 발동 시점 비교

발동 주체 발동 시점 한 마디
커맨드 사람 내가 /이름 입력 "불러서 쓰는 매크로"
스킬 Claude 맥락이 맞다고 판단할 때 (또는 수동) "알아서 꺼내는 매뉴얼"
훅 시스템 정해진 이벤트 발생 시 자동 "조건 맞으면 무조건 실행"

이를 한 흐름으로 엮으면 이렇게 됩니다. 내가 /deploy(커맨드)를 친다 → 배포 전 Claude가 우리 팀 배포 규칙(스킬)을 참고한다 → 실제 배포 명령 실행 전에 테스트 통과를 검사하는(훅) 자동 검증이 돈다. 셋이 역할을 나눠 한 워크플로를 완성하는 것입니다.

프로젝트 생성 반복작업을 커맨드로

앱·서버 프로젝트 초기 세팅처럼 매번 같은 순서로 반복하는 작업은 커맨드(또는 스킬)로 등록하기 좋은 케이스입니다.

---
description: 새 서버 프로젝트 기본 구조를 생성합니다
---
$ARGUMENTS 이름으로 새 서버 프로젝트를 만들어줘:
1. 디렉터리 구조 생성 (src, tests, config)
2. package.json / requirements.txt 초기화
3. 기본 .gitignore, README, .env.example 작성
4. 린터·포매터 설정 파일 추가
5. 기본 health-check 엔드포인트 1개 작성
6. git init 후 첫 커밋

/init-server my-api 처럼 호출하면 이 절차를 한 번에 돌립니다.

커맨드 vs 셸 스크립트 - 무엇으로 할까

반복 작업이라고 다 커맨드가 정답은 아닙니다. 기준은 "Claude의 판단이 필요한가"입니다.

작업 성격 더 나은 도구 이유
완전히 고정된 파일 복사·생성 셸 스크립트 / 템플릿 Claude 없이 결정론적으로 끝나는 게 빠르고 안정적
상황 따라 조정·작성이 필요 커맨드 / 스킬 도메인에 맞는 README·엔드포인트 작성 등 판단
둘이 섞임 커맨드 안에서 스크립트 호출 고정 부분은 스크립트로, 판단 부분은 Claude가

예를 들어 폴더 만들고 npm init 하는 것까지는 스크립트가 빠르지만, "이 API의 도메인에 맞는 모델 스키마 초안 작성"은 Claude가 해야 하는 일이라 커맨드가 빛납니다. 가장 실용적인 형태는 커맨드가 스크립트를 부르고, 그 위에서 Claude가 판단이 필요한 부분을 채우는 하이브리드입니다.

인자 활용과 커맨드 조직화

앱과 서버가 절차가 다르다면 커맨드를 나누거나 인자로 분기할 수 있습니다.

/init-project server my-api
/init-project app my-mobile

$ARGUMENTS로 받은 첫 단어(server/app)에 따라 다른 절차를 타도록 지시문에 적어두면 됩니다. 또는 서브디렉터리로 커맨드를 조직화할 수도 있습니다. 예를 들어 .claude/commands/frontend/component.md 파일은 /project:frontend:component 커맨드가 됩니다.

커맨드로 할까, 스킬로 할까

선택 기준은 발동 방식입니다. 내가 명시적으로 "프로젝트 만들자" 하고 시작한다면 커맨드(/init-server)가 자연스럽습니다. 의도가 분명하기 때문입니다. 반대로 "새 서버 짤 건데..." 하면 Claude가 알아서 세팅 절차를 적용하길 원한다면 스킬(자동 호출)이 편합니다. 프로젝트 생성은 보통 내가 의식적으로 시작하는 작업이라 커맨드 쪽이 잘 맞습니다.

어디에 둘까

프로젝트 초기화 커맨드는 특정 프로젝트가 아직 없을 때 쓰는 것이라, 개인 전역 위치에 두는 것이 좋습니다.

~/.claude/commands/init-server.md
~/.claude/skills/init-server/SKILL.md

이러면 어느 디렉터리에서든 /init-server를 부를 수 있습니다. 반대로 특정 레포 안에서만 쓰는 작업 절차는 그 프로젝트의 .claude/commands/에 두고 팀과 git으로 공유하면 됩니다.

정리하면, 프로젝트 스캐폴딩은 커맨드의 모범 사례입니다. 다만 고정 작업은 스크립트, 판단이 필요한 작업은 커맨드로 나누고, 둘을 엮으면 가장 강력합니다.