Claude Code 템플릿: 스킬, 에이전트, 훅 등

Claude Code 템플릿이란?

Claude Code 템플릿은 프로젝트나 로컬 환경 전반에서 Claude Code의 동작을 맞춤화하는 재사용 가능한 구성 파일입니다. 

중요한 점은 템플릿이 파일 기반이라는 것입니다. 일반적인 설정 GUI에서 설치한 뒤 화면을 클릭해 설정하는 방식이 아닙니다. 대신 Claude Code가 특정 파일과 폴더를 찾아 관련 메타데이터를 컨텍스트에 로드하고, 그 정보를 바탕으로 동작을 결정합니다.

실제로는 보통 Markdown, JSON, 셸 기반 파일이며 .claude/ 같은 프로젝트 수준 폴더에 저장하거나, 공유를 위해 플러그인 형태 디렉터리로 패키징합니다.

일반적인 프로젝트 수준 구조는 다음과 같습니다:

my-app/
├── CLAUDE.md
├── .mcp.json
└── .claude/
    ├── skills/
    │   └── database-migration/
    │       └── SKILL.md
    ├── agents/
    │   └── security-auditor.md
    ├── commands/
    │   └── summarize-pr.md
    └── settings.json

Claude 코드 템플릿 vs CLAUDE.md

CLAUDE.md는 여전히 중요하지만 역할이 다릅니다. CLAUDE.md는 프로젝트 브리핑이라고 생각하세요. 프로젝트가 무엇인지, 어떤 커맨드가 중요한지, 어떤 코딩 표준이 적용되는지, Claude가 기억해야 할 아키텍처 관례가 무엇인지 등을 담습니다. 

자세한 설명은 CLAUDE.md 작성 가이드를 참고하세요.

템플릿은 더 모듈식입니다:

• 스킬은 마이그레이션 워크플로를 인코딩할 수 있습니다. 
• 에이전트는 보안 검토 페르소나를 분리할 수 있습니다. 
• 훅은 파일 편집 후 실행될 수 있습니다. 
• MCP 구성은 Claude를 GitHub, SQLite 또는 다른 외부 시스템에 연결할 수 있습니다.

템플릿은 더 넓은 Claude Code 워크플로 설계와도 연결됩니다. 탄탄한 템플릿은 기획, 테스트, 컨텍스트 전달의 좋은 습관과 함께할 때 가장 효과적입니다. 

이러한 실천법은 모범 사례 가이드에 자세히 나와 있습니다.

사용자 정의 커맨드는 스킬 시스템에서도 다루지만, 기존 .claude/commands/ 형식도 여전히 작동합니다. 권장되는 새로운 형식은 .claude/skills/<name>/SKILL.md로, 슬래시 커맨드 호출과 Claude의 자동 호출을 모두 지원합니다.

어떤 종류의 Claude Code 템플릿을 사용할 수 있나요?

Claude Code 템플릿 생태계는 일반적으로 스킬, 에이전트, 커맨드, 훅, MCP 통합, 플러그인의 여섯 가지 범주로 구성됩니다. 

앞의 다섯 가지는 Claude의 동작을 직접 변경합니다. 플러그인은 약간 다른데, 스킬, 에이전트, 훅, 커맨드, MCP 서버 등 구성 요소를 재사용 가능한 패키지로 묶는 배포 형식입니다.

아래에서 각 범주를 살펴보겠습니다.

1. 스킬

스킬은 반복 가능한 다단계 작업을 위한 지시 모음입니다. 스킬은 보통 YAML 프런트매터와 Markdown 본문을 포함한 SKILL.md 파일이 들어 있는 폴더입니다. 

프런트매터는 스킬이 무엇을 어떻게 수행해야 하는지 설명하고, 본문은 Claude가 따라야 할 단계를 안내합니다. 자세한 내용은 Claude 스킬 가이드를 참고하세요.

Claude는 스킬의 설명을 바탕으로 해당 스킬이 관련 있는지 판단합니다. 기본적으로 사용자와 Claude 모두 스킬을 호출할 수 있습니다. 사용자는 /skill-name을 입력하거나, 현재 작업이 스킬 설명과 일치하면 Claude가 자동으로 로드할 수 있습니다. 배포처럼 수동 제어가 필요한 워크플로에서는 모델의 자동 호출을 비활성화할 수도 있습니다.

간단한 파일 예시: .claude/skills/database-migration/SKILL.md

---
name: database-migration
description: Use when creating, reviewing, or modifying database migrations. Ensures migrations are reversible, tested, and checked before and after execution.
allowed-tools:
  - Read
  - Write
  - Bash
---

# Database Migration Skill

When working on a database migration:

1. Inspect the existing schema and migration history before writing changes.
2. Confirm whether the migration is additive, destructive, or data-transforming.
3. Create a reversible migration whenever the framework supports rollback.
4. Run the project’s migration check command before applying the migration.
5. Run tests that cover the affected models, queries, or API endpoints.
6. After writing the migration, summarize:
   - schema changes
   - rollback behavior
   - affected tables
   - test commands run

이 방식이 유용한 이유는 지시가 절차적이기 때문입니다. 단지 “마이그레이션에 주의하라”라고만 말하는 게 아니라, 반복 가능한 체크리스트를 제공합니다. 

스킬은 API 엔드포인트 생성, 변경 로그 작성, 테스트 스캐폴딩, 릴리스 노트 생성, PR 리뷰, 마이그레이션 점검 등 두 번 이상 Claude에 붙여넣게 될 만한 작업에 가장 적합합니다.

개발자들이 어떤 작업을 재사용 가능한 AI 워크플로로 만드는지 더 넓은 영감을 얻고 싶다면 에이전트 스킬 목록을 참고하세요.

2. 에이전트

에이전트, 정확히 말하면 Claude Code의 사용자 정의 서브에이전트는 자체 Markdown 정의, YAML 프런트매터, 도구 제한, 모델 선택, 시스템 프롬프트를 가진 특화된 AI 도우미입니다. 

프로젝트 범위는 .claude/agents/, 개인 범위는 ~/.claude/agents/에 둘 수 있습니다. 에이전트는 Claude에 요청하거나 .claude/agents/ 폴더의 마크다운 파일을 직접 편집해 생성합니다.

스킬과 에이전트는 실제로 차이가 있습니다. 스킬은 작업 수행 방법을 정의합니다. 에이전트는 작업을 수행하는 동안 Claude가 어떤 존재여야 하는지를 정의합니다. 즉 역할, 초점, 권한, 경계를 정합니다.

다음은 에이전트 예시입니다:

---
name: security-auditor
description: Reviews code for security vulnerabilities and produces a findings report without modifying files.
tools: Read, Glob, Grep, Bash
model: sonnet
---

You are a security auditor.

Your task is to inspect the codebase for vulnerabilities, risky patterns, and missing safeguards.

Rules:
- Do not edit files.
- Do not suggest broad rewrites unless directly tied to a security issue.
- Focus on authentication, authorization, input validation, secrets, dependency risk, and unsafe shell or SQL usage.
- Produce a findings report with severity, affected files, evidence, and recommended next steps.

이 에이전트는 Claude에게 명확한 경계를 제공합니다. 일반 세션에서는 Claude가 문제를 찾자마자 고치려 들 수 있습니다. 보안 감사 에이전트는 검사와 보고만 하도록, 수정은 피하도록 지시합니다. 

에이전트는 보안 감사, 문서 검토, 아키텍처 검토, 데이터 엔지니어링, 코드 품질 점검 등 맥락 분리와 권한 경계가 중요한 전문 영역에 적합합니다.

전문화된 스킬과 함께 사용할 때도 유용합니다. 예를 들어 보안 감사 에이전트는 결과 보고 스킬을 호출하고, 프런트엔드 리뷰어 에이전트는 컴포넌트 테스트 스킬을 사용할 수 있습니다.

3. 커맨드

커맨드는 /generate-tests, /check-deps, /summarize-pr와 같은 슬래시로 호출하는 단축 명령입니다. 과거에는 사용자 정의 커맨드를 .claude/commands/ 아래의 Markdown 파일로 저장했고, 파일명이 커맨드명이었습니다. 

Claude Code는 이 레거시 형식을 여전히 지원하지만, 새로운 커맨드형 워크플로에는 스킬 사용을 권장합니다. 동일한 /name 호출을 지원하고, 상황에 맞을 때 자동 호출도 되기 때문입니다.

커맨드는 트리거를 명시적으로 하고 싶을 때 최적입니다. 스킬은 Claude가 일치하는 작업을 감지하면 자동 활성화될 수 있지만, 커맨드는 사용자가 선택할 때만 실행되어야 합니다. 따라서 “지금 테스트 생성”, “지금 이 PR 요약”, “지금 의존성 점검”, “지금 커밋 메시지 준비” 같은 체크포인트에 유용합니다.

4. 훅

훅은 Claude Code 수명주기 이벤트에 반응해 실행되는 자동화 규칙입니다. 사용자가 정의한 셸 명령이 Claude Code 수명주기의 특정 시점에 실행되어 동작을 결정론적으로 제어할 수 있습니다. 

지금까지 다룬 다른 템플릿과의 차이는, 훅은 사용자의 요청이 아니라 Claude의 행위에 의해 트리거된다는 점입니다.

간단히 말해, 파일 편집 후 포매팅을 Claude가 매번 기억하길 바랄 필요가 없습니다. 훅이 자동으로 처리할 수 있습니다.

현재 훅 이벤트 이름에는 PreToolUse, PostToolUse, Notification, Stop 등이 포함됩니다. 

예시: Claude가 파일을 편집하거나 쓸 때 포매터를 실행하기:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Example: block risky shell commands before Claude runs them:
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/block-dangerous-bash.py"
          }
        ]
      }
    ]
  }
}

훅은 Claude가 건너뛰면 안 되는 규칙에 가장 적합합니다. 린터 실행, 편집된 파일 포매팅, 보호된 파일 편집 차단, 생성 코드 점검, Claude가 입력이 필요할 때 알림 보내기 등이 이에 해당합니다. 

자세한 튜토리얼은 Claude Code 훅 가이드를 참고하세요.

5. MCP 통합

MCP 통합은 모델 컨텍스트 프로토콜(Model Context Protocol)을 통해 Claude Code를 외부 도구, 데이터 소스, API에 연결합니다. MCP는 AI 시스템과 외부 도구 사이의 커넥터 레이어로 작동합니다. Claude Code에서는 로컬 파일과 셸 명령을 넘어설 수 있음을 의미합니다. 

설정한 MCP 서버에 따라 GitHub, 데이터베이스, 문서 시스템, 클라우드 플랫폼, 내부 API 등 외부 서비스와 상호작용할 수 있습니다. 전체 설명과 데모 프로젝트는 모델 컨텍스트 프로토콜 튜토리얼을 참고하세요.

MCP 서버는 크게 세 가지 기능을 노출할 수 있습니다:

• 도구: GitHub 이슈 생성, 데이터베이스 쿼리 실행 같은, Claude가 호출할 수 있는 실행 함수
• 리소스: 파일, 데이터베이스 행, 문서 등 읽기 전용 컨텍스트 소스
• 프롬프트: 서버에서 제공하는 재사용 가능한 작업 템플릿

프로젝트 수준 .mcp.json은 여러 서버를 나란히 구성할 수 있습니다:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "sqlite": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "./data/app.db"
      ]
    }
  }
}

이 점이 중요한 이유는 Claude가 접근 가능한 컨텍스트와 도구로만 추론할 수 있기 때문입니다. MCP가 없으면 로컬 파일은 살펴볼 수 있어도 이슈 트래커, 데이터베이스, 클라우드 환경, 내부 API는 볼 수 없습니다. 

MCP는 정적 코드 스냅샷이 아니라 실제 스택과 작업해야 하거나 외부 데이터 접근이 필요할 때 가장 적합합니다.

6. 플러그인

플러그인은 패키지화된 묶음입니다. 스킬, 에이전트, 훅, MCP 구성, 커맨드 등 구성 요소를 하나의 설치 가능한 구조에 포함할 수 있습니다. 

Claude Code에서 플러그인은 일반적으로 .claude-plugin/plugin.json 매니페스트와 skills/, agents/, hooks/, 플러그인 루트의 .mcp.json 같은 구성 요소 폴더를 포함합니다.

플러그인 구조 예시:

frontend-workflow-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── component-test/
│       └── SKILL.md
├── agents/
│   └── frontend-reviewer.md
├── hooks/
│   └── hooks.json
└── .mcp.json

플러그인 JSON 예시:

{
  "name": "frontend-workflow",
  "displayName": "Frontend Workflow",
  "version": "1.0.0",
  "description": "Frontend development workflow with review agents, test skills, and formatting hooks",
  "author": {
    "name": "Your Team"
  }
}

플러그인은 새로운 동작 유형을 추가하지 않습니다. 다른 유형을 휴대 가능하게 만듭니다. 팀 전체에 완전한 구성을 공유하거나, 여러 프로젝트에서 같은 워크플로를 재사용하거나, 각 파일을 수동으로 만들지 않고 커뮤니티에서 유지 관리하는 묶음을 설치하고 싶을 때 플러그인을 사용하세요.

처음부터 만들려면 DataCamp의 Claude Code 플러그인 단계별 가이드를 참고하세요.

어떤 템플릿 유형을 선택해야 하나요?

유형이 많아 혼란스러울 수 있습니다. 모두 Claude의 동작을 바꿀 수 있지만, 차이는 주로 트리거 방식과 제공하는 제어 수준에 있습니다.

더 명확히 하기 위해 비교를 정리했습니다:

간단한 선택 규칙은 다음과 같습니다:

• Claude가 코드를 건드릴 때마다 규칙을 자동 강제하고 싶다면 훅을 사용하세요. 
• 특정 작업에서 Claude가 깊은 도메인 전문성을 갖추길 원한다면 에이전트를 사용하세요. 
• Claude가 일관되게 반복해야 할 워크플로를 인코딩하려면 스킬을 사용하세요. 
• 적절한 순간에 직접 액션을 호출하고 싶다면 커맨드 또는 커맨드형 스킬을 사용하세요. 
• Claude가 외부 서비스나 실시간 데이터가 필요하다면 MCP를 사용하세요. 
• 완전한 워크플로 구성을 설치·공유하고 싶다면 플러그인을 사용하세요.

실제 프로젝트에서는 보통 이 유형들을 조합합니다. 보안 플러그인은 security-auditor 에이전트, audit-findings 스킬, 의존성 점검 커맨드, pre-commit 훅을 묶을 수 있습니다. 에이전트는 역할을, 스킬은 보고 구조를, 커맨드는 명시적 체크포인트를, 훅은 가드레일을 제공합니다.

구현 전에 Claude가 정식 계획을 따르도록 해야 하는 워크플로에는 스펙 주도 개발이 종종 즉흥 프롬프트보다 더 잘 맞습니다.

Claude Code 템플릿은 어디서 찾을 수 있나요?

실용적인 출처는 세 가지입니다: Anthropic, 커뮤니티 컬렉션, 그리고 직접 작성.

먼저 Anthropic 공식 자료와 문서 Anthropic의 Claude Code 문서는 스킬, 서브에이전트, 훅, MCP, 플러그인을 다루며, 프로덕션에 반영하기 전 최신 파일 형식과 동작을 검증하기에 최적의 출발점입니다.

둘째, 커뮤니티 컬렉션을 활용하세요. 가장 눈에 띄는 커뮤니티 허브는 aitmpl.com으로, Claude Code 프로젝트용 즉시 사용 가능한 구성의 카탈로그를 표방합니다. 현재 내비게이션에는 스킬, 에이전트, 커맨드, 설정, 훅, MCP, 플러그인이 포함되어 있습니다. 

현재 상호작용 설치 커맨드는 다음과 같습니다:

npx claude-code-templates@latest

프로젝트 문서에는 더 짧은 별칭도 나와 있습니다:

npx cct@latest

특정 구성 요소의 경우, 라이브 GitHub README에는 다음과 같은 설치 커맨드가 표시됩니다:

npx claude-code-templates@latest --agent development-tools/code-reviewer --yes
npx claude-code-templates@latest --command performance/optimize-bundle --yes
npx claude-code-templates@latest --hook git/pre-commit-validation --yes
npx claude-code-templates@latest --mcp database/postgresql-integration --yes

여러 플래그를 한 번에 사용해 전체 스택을 일괄 설치하는 방법도 나와 있습니다.

커뮤니티 템플릿을 평가할 때는 다음 품질 신호를 확인하세요:

• description이 충분히 구체적이어서 Claude가 스킬이나 에이전트를 올바르게 트리거할 수 있나요?

• allowed-tools 범위가 적절히 좁나요, 아니면 불필요하게 광범위한 쓰기·bash 권한을 요구하나요?

• 리포지토리가 최근에도 유지·보수되었나요?

• 템플릿이 무엇을 변경하는지 설명하나요?

• 검토하지 않은 코드를 실행하는 훅이나 MCP 서버가 포함되어 있나요?

셋째, 직접 작성하세요. 스택과 밀접하게 결합된 워크플로에는 보통 이 방법이 최선입니다. 커뮤니티 템플릿은 유용한 베이스라인이 될 수 있지만, 내부 마이그레이션 정책, 명명 규칙, 데이터 모델, 배포 위험 허용도까지 알 수는 없습니다.

마무리

Claude Code 템플릿은 Claude Code를 세션 단위 도우미에서 지속적인 개발 환경으로 발전시키는 방법입니다. 

소개한 여섯 범주는 사실 레이어입니다. 스킬은 워크플로를, 에이전트는 역할을, 커맨드는 명시적 액션을, 훅은 가드레일을, MCP는 외부 시스템을, 플러그인은 재사용을 위한 패키징을 담당합니다.

시작점은 거대한 플러그인 스택이 아닙니다. 가장 자주 반복하는 워크플로를 위한 스킬 하나부터 시작해 보세요. Claude의 기본 동작이 여전히 마찰을 만드는 부분이 보이면, 전문 검토를 위한 에이전트, 강제를 위한 훅, 실시간 시스템 접근을 위한 MCP 서버를 추가하세요.

Claude Code를 더 배우고 싶다면 Claude Code 101과 Claude Code in Action 코스를 확인하세요.