Claude Code 플러그인 만드는 법: 단계별 가이드

Claude Code는 대부분의 개발 작업을 기본으로 처리하지만, 팀마다 기본값으로는 다 커버되지 않는 고유한 워크플로가 있습니다. 회사 표준 구조로 컴포넌트를 스캐폴딩하는 커스텀 명령, 모든 커밋 전에 자동 린팅, 자주 사용하는 프레임워크 문서에 대한 빠른 접근 등을 원할 수 있습니다.

Claude Code 플러그인을 사용하면 이러한 기능을 직접 추가할 수 있습니다. 커뮤니티에서 만든 플러그인을 설치하거나 직접 만들 수 있습니다.

Anthropic의 에이전트형 코딩 도구가 처음이라면 Claude Code 가이드나 Claude 모델 소개 코스부터 시작하시길 권합니다. 이 튜토리얼은 Claude Code가 설치되어 있고 기본 작업에 사용해 보았다는 전제를 바탕으로 합니다.

끝까지 따라오시면 다음을 할 수 있습니다.

• Anthropic 디렉터리와 커뮤니티 소스에서 플러그인을 찾아 설치하기
• 플러그인이 포함할 수 있는 세 가지 컴포넌트 유형 이해하기
• 사용 사례에 맞는 올바른 유형 선택하기
• 직접 플러그인을 만들어 공유하기

Anthropic 최신 모델의 기능을 개괄적으로 보려면 Claude Sonnet 5 가이드를 확인하세요.

요약

• Claude Code 플러그인은 skills, MCP 서버, hooks를 묶어 공유 가능한 패키지로 만들며, claude plugin add로 설치합니다

• Skills는 필요 시 로드(각 ~100 토큰), MCP 서버는 도구 정의를 사전 로드(툴 검색으로 감소), hooks는 셸 스크립트로 토큰 비용 0

• 지식과 워크플로에는 skills, 외부 API 접근에는 MCP 서버, 매번 반드시 실행돼야 하는 규칙에는 hooks를 사용

• 플러그인은 세 파일로 구성: .claude-plugin/plugin.json 매니페스트, skills/ 디렉터리, SKILL.md 지시 파일

Claude Code 플러그인이란?

플러그인은 하나 이상의 Claude Code 확장을 손쉽게 공유하고 설치할 수 있도록 묶은 패키지입니다. 설정 파일을 기기나 팀원 간에 수동으로 복사하는 대신, 모든 것을 플러그인으로 감싸 단일 단위로 배포할 수 있습니다.

플러그인은 세 가지 유형의 컴포넌트를 포함할 수 있습니다.

• Skills: /skill-name로 호출하는 커스텀 명령어 또는 상황에 맞게 Claude가 자동으로 사용하는 컨텍스트 인지형 프롬프트

• MCP 서버: Claude가 평소에는 접근할 수 없는 데이터에 접근할 수 있도록 해주는 외부 서비스 및 API 연결

• Hooks: 파일 편집 전이나 커밋 후 같은 특정 이벤트에 자동으로 실행되는 셸 스크립트

플러그인은 이 중 하나만 포함할 수도 있고, 함께 동작하도록 여러 개를 결합할 수도 있습니다. 예를 들어 "배포" 플러그인은 수동 배포를 위한 /deploy 스킬, 스테이징 환경 상태를 확인하는 MCP 서버, 그리고 어떤 배포 명령이 실행되기 전에 테스트를 수행하는 훅을 포함할 수 있습니다.

plugin.json 매니페스트 파일은 플러그인의 구성 요소를 정의합니다. 설치할 스킬, MCP 서버, 훅과 함께 플러그인 이름, 버전, 작성자 같은 메타데이터를 지정합니다. 플러그인을 설치하면 Claude Code가 이 매니페스트를 읽고 각 컴포넌트를 올바른 위치에 설정합니다.

이 패키징 방식 덕분에 Claude Code 확장의 내부 파일 구조를 알 필요가 없습니다. 플러그인만 설치하면 모든 것이 제자리에 배치됩니다.

Claude Code 플러그인 찾기와 설치

대부분의 플러그인은 두 곳 중 하나에 있습니다. claude.com/plugins의 Anthropic 공식 디렉터리에는 Anthropic이 만든 플러그인, 검증된 커뮤니티 기여, 인기 서드파티 확장이 포함됩니다. 각 항목에는 플러그인 구성 요소, 호환성 정보, 설치 방법이 표시됩니다.

두 번째 소스는 GitHub입니다:

원하는 플러그인을 찾았다면, 설치 명령은 플러그인의 위치에 따라 달라집니다.

# From the official directory
claude plugin add @anthropic/deploy-helper
 
# From a GitHub repository
claude plugin add github:username/repo-name
 
# From a local directory (useful during development)
claude plugin add ./my-plugin

플러그인을 몇 개 설치하고 나면 관리를 원하게 됩니다. plugin 명령으로 나열, 업데이트, 제거를 처리할 수 있습니다.

# List all installed plugins
claude plugin list
 
# Update a specific plugin to the latest version
claude plugin update @anthropic/deploy-helper
 
# Update all plugins
claude plugin update --all
 
# Remove a plugin
claude plugin remove @anthropic/deploy-helper

설치 시 결정해야 할 사항 중 하나는 범위입니다. 플러그인은 두 위치 중 한 곳에 존재할 수 있습니다. 사용자 범위로 설치하면 ~/.claude/plugins/에 위치해 모든 프로젝트에서 동작하고, 프로젝트 범위로 설치하면 특정 저장소 내 .claude/plugins/에 위치합니다.

기본값은 사용자 범위입니다. 현재 프로젝트에만 플러그인을 설치하려면 --project 플래그를 추가하세요.

claude plugin add @anthropic/deploy-helper --project

프로젝트 범위 플러그인은 확장이 특정 코드베이스에 묶여 있을 때 적합합니다. 

회사 배포 프로세스를 아는 플러그인은 해당 프로젝트에 두는 것이 맞습니다. 개인 선호에 따라 코드를 포맷팅하는 플러그인은 사용자 수준에 두는 것이 좋습니다. 플러그인이 두 범위 모두에 존재하면 프로젝트 버전이 우선하여, 팀은 프로젝트별 구성을 강제하면서도 개발자는 다른 곳에서 개인 플러그인을 계속 활성화할 수 있습니다.

올바른 Claude Code 플러그인 유형 선택

세 가지 컴포넌트 유형은 목적이 다르고 컨텍스트 윈도우 토큰 소모도 다릅니다. 이러한 트레이드오프를 이해하면 작업별로 적합한 유형을 고를 수 있습니다.

Skills vs MCP 서버: 토큰 트레이드오프

MCP 서버는 세션 시작 시 모든 도구 정의를 컨텍스트 윈도우에 사전 로드합니다. 각 도구는 이름, 설명, 전체 파라미터 스키마가 필요하며, 일반적으로 도구당 100~300 토큰이 듭니다. 서버 5개 구성만으로도 아무것도 입력하기 전에 약 55,000 토큰을 소모합니다.

• GitHub: 35개 도구
•  Slack: 11개 도구
• Sentry: 5개 도구
• Grafana: 5개 도구
• Splunk: 2개 도구

한 분석에 따르면 7개 이상의 서버를 사용하는 구성은 67,000개 이상의 토큰을 소모하며, 대화가 시작되기도 전에 200K 컨텍스트 윈도우의 3분의 1이 사라집니다.

Skills는 점진적 공개 방식으로 접근합니다. 세션 시작 시 Claude는 YAML 프론트매터의 스킬 이름과 한 줄짜리 설명만 보며, 스킬당 약 100 토큰입니다. 

전체 지시는 해당 스킬이 현재 작업에 관련 있다고 Claude가 판단할 때만 로드됩니다. 참조 파일은 필요할 때만 로드됩니다. 그리고 스크립트는 컨텍스트 윈도우에 전혀 들어가지 않습니다. Claude가 외부에서 실행하고 출력만 돌아옵니다.

Anthropic은 2025년 말 Tool Search로 이 불균형을 해소했습니다. 

모든 도구 정의를 미리 로드하는 대신, 이제 Claude Code는 도구 설명이 사용 가능한 컨텍스트의 10%를 넘길 경우 온디맨드 로딩으로 전환합니다. 

내부 테스트에서는 대규모 도구 라이브러리의 컨텍스트 사용량이 약 134,000 토큰에서 약 5,000 토큰으로 감소했습니다. 도구 선택 정확도도 향상되어, Opus 4는 49%에서 74%로, Opus 4.5는 79.5%에서 88.1%로 MCP 평가에서 상승했습니다.

선택 기준은 다음과 같습니다.

스킬은 Claude가 판단을 적용할 수 있는 지식이나 워크플로에 접근하도록 하고 싶을 때 가장 적합합니다. 팀의 코드 리뷰 체크리스트를 설명하는 스킬은 Claude가 코드를 리뷰할 때 로드되지만, 각 항목을 어떻게 적용할지는 컨텍스트에 따라 Claude가 결정합니다. 

또한 무거운 계산을 스크립트로 처리해야 하는 작업에도 스킬이 적합합니다. 스크립트 코드는 컨텍스트 윈도우 밖에 머물기 때문입니다.

MCP 서버는 Slack 메시지, GitHub PR, 데이터베이스 쿼리 같은 외부 서비스의 실시간 데이터가 필요할 때 가장 적합합니다. 여러 AI 에이전트가 동일한 도구를 사용해야 하거나, 감사 로그 및 명시적 권한 같은 엔터프라이즈 기능이 필요할 때도 올바른 선택입니다.

많은 구성은 둘을 결합합니다. 스킬은 자연어 지시를 통해 "어떻게"와 "언제"를 제공하고, MCP 서버는 실제 API 호출을 처리합니다.

설치할 만한 인기 Claude Code 스킬

• Superpowers (자습서): TDD, 디버깅, 구조적 계획 수립을 위한 20개+ 프로덕션 검증 워크플로
• frontend-design: 진부한 미학을 피하고 대담한 디자인 결정을 내리도록 Claude를 안내
• mcp-builder: 외부 API 통합을 위한 MCP 서버 생성 가이드
•  webapp-testing: UI 검증을 위해 Playwright로 로컬 웹앱 테스트
•  skill-creator: 새 스킬 구축을 안내하는 대화형 도구

연결할 만한 인기 MCP 서버

• Context7: 실시간, 버전별 문서 조회
• GitHub: 저장소 검색, PR 관리, 이슈 추적
• Playwright: 스크린샷 대신 접근성 트리로 브라우저 자동화
• Supabase: 행 수준 보안(RLS)을 인지한 데이터베이스 쿼리
• Sentry: 에디터 내에서 오류 추적과 성능 모니터링

또한 최고의 원격 MCP 서버 가이드도 읽어보세요.

Hooks: 결정적 계층

Hooks는 스킬과 MCP 논쟁의 바깥에 있습니다. 스킬과 MCP 서버가 Claude 지향형(Claude가 사용할지 결정)인 반면, 훅은 시스템 지향형입니다. PreToolUse 또는 PostToolUse 같은 이벤트에서 발동하며, Claude가 특정 작업을 하기 전후에 셸 스크립트를 실행합니다. Claude는 훅 실행 여부에 관여하지 않습니다.

덕분에 훅은 반드시 예외 없이 이뤄져야 하는 작업(모든 커밋 전 린팅, 보호 디렉터리 쓰기 차단, 모든 bash 명령 로깅, 어떤 배포든 테스트 선행 실행 등)에 적합합니다.

이 개발자는 "block-at-write" 훅보다 "block-at-submit" 훅을 권장합니다. 작업 도중 Claude를 차단하면 에이전트가 혼란스러워져 결과가 나빠집니다. 그녀의 팀은 테스트가 통과했을 때만 존재하는 임시 파일을 확인하도록 PreToolUse 훅으로 Bash(git commit)을 감쌉니다. 파일이 없으면 커밋도 없습니다. 에이전트가 작업을 마친 뒤, 마지막에 검증이 이뤄집니다.

훅은 컨텍스트 윈도우 밖에서 셸 스크립트로 실행되므로 토큰 오버헤드가 없습니다.

유용한 Claude 훅 예시

• 편집 시 ESLint/Prettier: Claude가 파일을 쓴 뒤 자동 포맷
• 커밋 시 테스트 게이트: 테스트 통과 전까지 커밋 차단
• 보호 경로: 마이그레이션, 설정, 벤더 디렉터리 쓰기 방지
• 완료 알림: 긴 작업이 끝나면 Slack 또는 데스크톱 알림 전송
• 대화 로그 백업: 컴팩션 실행 전 대화 기록 저장

나만의 Claude Code 플러그인 만들기

스킬이 개인 .claude/ 디렉터리에만 있으면 본인만 사용할 수 있습니다. 플러그인으로 패키징하면 팀원과 공유하거나 여러 프로젝트에서 재사용할 수 있습니다.

이번에는 session-logger라는 플러그인을 만들어 /session-logger:summarize 명령을 추가하겠습니다. 호출하면 Claude가 대화를 검토하고 구조화된 요약을 SESSION_LOG.md에 추가합니다.

플러그인 구조 만들기

플러그인은 파일 시스템 어디에나 둘 수 있습니다. 이 튜토리얼에서는 홈 디렉터리에 만들겠습니다.

cd ~
mkdir -p session-logger/.claude-plugin
mkdir -p session-logger/skills/summarize

생성되는 구조는 다음과 같습니다.

~/session-logger/
├── .claude-plugin/
│   └── plugin.json  	# manifest goes here, nowhere else
└── skills/
	└── summarize/   	# folder name becomes the command name
    	└── SKILL.md 	# must be named exactly this

매니페스트 작성

~/session-logger/.claude-plugin/plugin.json을 만듭니다.

{
  "name": "session-logger",
  "description": "Log session summaries to a markdown file",
  "version": "1.0.0"
}

name 필드는 네임스페이스 접두사가 됩니다. 이 플러그인의 모든 명령은 /session-logger:로 시작합니다.

스킬 작성

다음 파일을 만듭니다: ~/session-logger/skills/summarize/SKILL.md.

---
description: Log a summary of the current session to SESSION_LOG.md
disable-model-invocation: true
---
 
When invoked, review the conversation and create a summary with these sections:
 
- **Date/time**: Current timestamp
- **Tasks completed**: What was accomplished
- **Files modified**: List of files created or changed
- **Decisions made**: Architectural or implementation choices
- **Open questions**: Unresolved items for future sessions
 
Append the summary to SESSION_LOG.md in the project root. Create the file if it doesn't exist.

disable-model-invocation: true 줄은 이 스킬을 사용자만 트리거할 수 있음을 Claude에 알립니다. 이 플래그가 없으면 Claude가 대화에 도움이 된다고 판단할 때 명령을 자율적으로 실행할 수 있습니다. 로거나 배포 도구에는 보통 수동 제어가 적합합니다.

로컬 테스트

플러그인을 사용하려는 프로젝트로 이동한 후, --plugin-dir 플래그로 플러그인 위치를 지정해 Claude Code를 시작하세요.

cd ~/your-project
claude --plugin-dir ~/session-logger

/session-logger:summarize를 입력해 명령을 호출하세요. 플러그인 명령은 전체 이름을 입력하기 전까지 자동완성 제안에 나타나지 않습니다. Claude Code가 유효한 명령으로 인식하면 텍스트가 파란색으로 변합니다.

세션에서 작업을 좀 한 뒤 명령을 실행하세요. Claude가 대화를 검토하고 현재 프로젝트 디렉터리의 SESSION_LOG.md에 항목을 추가합니다.

공유하기

플러그인을 GitHub에 푸시하세요. 수동 클로닝을 넘어 배포하려면 플러그인 마켓플레이스에 추가하세요. 마켓플레이스 가이드에는 직접 마켓플레이스를 만들거나 기존 마켓플레이스에 제출하는 방법이 나와 있습니다.

마무리

플러그인은 Claude Code를 범용 도우미에서 귀하의 워크플로에 맞춘 도구로 바꿔줍니다. 이번에 만든 세션 로거는 약 5분, 세 파일이면 충분했습니다. 대부분의 유용한 플러그인도 이보다 크게 복잡하지 않습니다.

함께 따라 하셨다면 이제 로컬에 작동하는 플러그인이 있습니다. 요약 형식을 바꾸거나 새 섹션을 추가하는 등 직접 수정해 보세요. 팀에 실제로 필요한 것으로 바꿔도 좋습니다. 개인용 빠른 도구든 수백 명의 개발자에게 배포할 도구든, 구조는 동일합니다.

시간이 될 때 커뮤니티 저장소도 둘러보세요. 다른 사람들이 플러그인을 어떻게 구성하는지 보면 문서만으로는 알기 어려운 패턴을 배울 수 있습니다.

Claude Code를 더 깊이 배우려면 Claude Code 모범 사례, Superpowers 스킬 프레임워크, 긴 세션을 위한 슬래시 명령, 보안과 권한 튜토리얼을 확인하세요. Claude 모델을 더 알고 싶다면 Introduction to Claude Models 코스를 추천합니다.