플러그인 만들기

skills, agents, hooks, MCP servers를 사용하여 Claude Code를 확장하는 사용자 정의 플러그인을 만듭니다.

플러그인을 사용하면 프로젝트와 팀 전체에서 공유할 수 있는 사용자 정의 기능으로 Claude Code를 확장할 수 있습니다. 이 가이드에서는 skills, agents, hooks, MCP servers를 사용하여 자신의 플러그인을 만드는 방법을 다룹니다.

기존 플러그인을 설치하려고 하시나요? 플러그인 발견 및 설치를 참조하세요. 완전한 기술 사양은 플러그인 참조를 참조하세요.

플러그인 대 독립 실행형 구성 사용 시기

Claude Code는 사용자 정의 skills, agents, hooks를 추가하는 두 가지 방법을 지원합니다:

빠른 시작

이 빠른 시작은 사용자 정의 skill을 사용하여 플러그인을 만드는 과정을 안내합니다. 매니페스트(플러그인을 정의하는 구성 파일)를 만들고, skill을 추가하고, --plugin-dir 플래그를 사용하여 로컬에서 테스트합니다.

필수 조건

• Claude Code 설치 및 인증

첫 번째 플러그인 만들기

mkdir my-first-plugin

mkdir my-first-plugin/.claude-plugin

{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0",
"author": {
"name": "Your Name"
}
}

mkdir -p my-first-plugin/skills/hello

---
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

claude --plugin-dir ./my-first-plugin

/my-first-plugin:hello

---
description: Greet the user with a personalized message
---

# Hello Skill

Greet the user named "$ARGUMENTS" warmly and ask how you can help them today. Make the greeting personal and encouraging.

/my-first-plugin:hello Alex

기술 디렉토리에서 플러그인 개발

매번 시작할 때 --plugin-dir을 전달하는 대신 기술 디렉토리에 플러그인을 유지하고 Claude Code가 자동으로 로드하도록 할 수 있습니다. claude plugin init이 스캐폴딩합니다:

claude plugin init my-tool

이는 .claude-plugin/plugin.json 매니페스트와 시작 SKILL.md를 포함하는 ~/.claude/skills/my-tool/을 만듭니다. 다음 세션에서는 마켓플레이스나 설치 단계 없이 my-tool@skills-dir로 로드됩니다.

자동 로드 규칙, 개인 대 프로젝트 범위, 작업 공간 신뢰 요구 사항, 업데이트 또는 제거 방법은 기술 디렉토리 플러그인을 참조하세요.

플러그인 구조 개요

skill을 사용하여 플러그인을 만들었지만, 플러그인에는 훨씬 더 많은 것이 포함될 수 있습니다: 사용자 정의 agents, hooks, MCP servers, LSP servers, 백그라운드 모니터.

정확히 하나의 skill을 제공하는 플러그인은 skills/ 디렉토리를 만드는 대신 SKILL.md를 플러그인 루트에 직접 배치할 수 있습니다. Claude Code는 이를 단일 skill로 로드하고 frontmatter name 필드를 호출 이름으로 사용합니다. 플러그인이 하나 이상의 skill로 성장할 수 있는 경우 skills/ 레이아웃을 사용하세요.

더 복잡한 플러그인 개발

기본 플러그인에 익숙해지면 더 정교한 확장 기능을 만들 수 있습니다.

플러그인에 Skills 추가

플러그인은 Claude의 기능을 확장하기 위해 Agent Skills를 포함할 수 있습니다. Skills는 모델 호출입니다: Claude는 작업 컨텍스트에 따라 자동으로 사용합니다.

플러그인 루트에 SKILL.md 파일을 포함하는 Skill 폴더가 있는 skills/ 디렉토리를 추가합니다:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── code-review/
        └── SKILL.md

각 SKILL.md는 YAML 프론트매터와 지침을 포함합니다. Claude가 skill을 언제 사용할지 알 수 있도록 description을 포함하세요:

---
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

플러그인을 설치한 후 설치 요약을 확인합니다: Run /reload-plugins to activate.를 보고하면 플러그인 변경 사항을 다시 시작하지 않고 적용을 참조하여 현재 세션에서 Skills를 로드합니다. 점진적 공개 및 도구 제한을 포함한 완전한 Skill 작성 지침은 Agent Skills를 참조하세요.

플러그인에 LSP servers 추가

LSP (Language Server Protocol) 플러그인은 Claude에 실시간 코드 인텔리전스를 제공합니다. 아직 공식 LSP 플러그인이 없는 언어를 지원해야 하는 경우 플러그인에 .lsp.json 파일을 추가하여 자신의 플러그인을 만들 수 있습니다:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

플러그인을 설치하는 사용자는 자신의 머신에 언어 server 바이너리를 설치해야 합니다.

서버가 시작되는지 확인하려면 플러그인이 활성화된 상태에서 Claude Code를 시작하고 /plugin Errors 탭을 확인합니다: 시작에 실패한 언어 server는 바이너리가 설치되지 않았을 때 Executable not found in $PATH와 같은 오류와 함께 나타납니다. 잘못된 구성이 있는 항목은 건너뛰어집니다. 이유를 확인하려면 claude --debug를 실행하세요.

완전한 LSP 구성 옵션은 LSP servers를 참조하세요.

플러그인에 백그라운드 모니터 추가

백그라운드 모니터를 사용하면 플러그인이 로그, 파일 또는 외부 상태를 백그라운드에서 감시하고 이벤트가 도착할 때 Claude에 알릴 수 있습니다. Claude Code는 플러그인이 활성화될 때 각 모니터를 자동으로 시작하므로 Claude에 감시를 시작하도록 지시할 필요가 없습니다.

플러그인 루트에 monitors/monitors.json 파일을 추가하고 모니터 항목의 배열을 포함합니다:

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

command의 각 stdout 줄은 세션 중에 Claude에 알림으로 전달됩니다. when 트리거 및 변수 대체를 포함한 전체 스키마는 Monitors를 참조하세요.

플러그인과 함께 기본 설정 제공

플러그인은 플러그인 루트에 settings.json 파일을 포함하여 플러그인이 활성화될 때 기본 구성을 적용할 수 있습니다. 현재 agent 및 subagentStatusLine 키만 지원됩니다.

agent를 설정하면 플러그인의 사용자 정의 agents 중 하나를 주 스레드로 활성화하여 시스템 프롬프트, 도구 제한, 모델을 적용합니다. 이를 통해 플러그인은 활성화될 때 Claude Code의 동작 방식을 기본적으로 변경할 수 있습니다.

{
  "agent": "security-reviewer"
}

이 예제는 플러그인의 agents/ 디렉토리에 정의된 security-reviewer agent를 활성화합니다. settings.json의 설정은 plugin.json에 선언된 settings보다 우선합니다. 알 수 없는 키는 자동으로 무시됩니다.

복잡한 플러그인 구성

많은 구성 요소가 있는 플러그인의 경우 기능별로 디렉토리 구조를 구성합니다. 완전한 디렉토리 레이아웃 및 구성 패턴은 플러그인 디렉토리 구조를 참조하세요.

플러그인을 로컬에서 테스트

개발 중에 플러그인을 테스트하려면 --plugin-dir 플래그를 사용합니다. 이는 설치를 요구하지 않고 플러그인을 직접 로드합니다.

claude --plugin-dir ./my-plugin

플래그는 플러그인 디렉토리의 .zip 아카이브도 허용합니다.

claude --plugin-dir ./my-plugin.zip

--plugin-dir 플러그인이 설치된 마켓플레이스 플러그인과 동일한 이름을 가진 경우 로컬 복사본이 해당 세션에 우선합니다. 이를 통해 먼저 제거하지 않고도 이미 설치한 플러그인의 변경 사항을 테스트할 수 있습니다. 관리 설정에 의해 강제로 활성화되거나 비활성화된 플러그인은 유일한 예외이며 --plugin-dir로 재정의할 수 없습니다.

플러그인을 변경할 때 /reload-plugins를 실행하여 다시 시작하지 않고 업데이트를 적용합니다. 이는 플러그인, skills, agents, hooks, 플러그인 MCP servers, 플러그인 LSP servers를 다시 로드합니다. 대화형 터미널이 없는 세션에서 플러그인 MCP server 변경 사항은 다음 세션을 기다립니다. 플러그인 구성 요소를 테스트합니다:

• /plugin-name:skill-name으로 skills를 시도해보세요
• agents가 /context의 Custom Agents 아래에 나타나는지 확인하거나 범위가 지정된 이름으로 @-mention하세요
• 각 hook이 일치하는 이벤트를 트리거합니다(예: 파일을 편집하도록 Claude에 요청하여 PostToolUse hook을 트리거하고 그 효과를 확인합니다). Claude Code는 일치한 hooks, 종료 코드, 출력을 debug log에 기록합니다.

--plugin-dir로 플러그인을 시도하면 작동할 수 있음을 알 수 있습니다. Claude가 실제로 얼마나 자주 도달하고 올바른 결과를 얻는지 알아보려면 claude plugin eval을 사용하여 테스트 프롬프트 세트에 대해 실행하세요. 각 프롬프트는 플러그인이 로드된 상태와 로드되지 않은 상태에서 여러 번 실행되므로 플러그인이 기여하는 바를 확인하고 변경하거나 새 모델이 출시될 때 회귀를 포착할 수 있습니다.

한 곳에서 여러 플러그인을 로드하려면 플러그인을 보유한 폴더를 전달합니다(예: --plugin-dir ./plugins). 플러그인 폴더를 로드하려면 Claude Code v2.1.265 이상이 필요합니다. Claude Code는 폴더의 최상위 수준을 읽어 어떤 플러그인을 로드할지 결정하며, 대화형 세션에서는 나중에 변경 사항을 위해 폴더를 감시합니다:

• 로드되는 항목: 폴더에 최상위 수준의 매니페스트 또는 플러그인 구성 요소가 없으면 Claude Code는 이를 플러그인 폴더로 취급합니다. .claude-plugin/plugin.json 매니페스트가 있는 각 즉시 하위 폴더는 별도의 플러그인으로 로드됩니다. Claude Code는 오류를 보고하지 않고 매니페스트가 없는 플러그인을 포함하여 폴더의 다른 모든 항목을 건너뜁니다.
• 대화형 세션 중 변경 사항: 추가하는 하위 폴더는 매니페스트가 준비되면 새 플러그인으로 로드되며, 하위 폴더를 제거하면 해당 플러그인이 언로드됩니다. Claude Code는 각 변경에 대해 세션에 줄을 출력합니다. 변경 사항을 중간 대화에 적용하면 프롬프트 캐시가 무효화될 경우 Claude Code는 이를 보류하고 줄에서 /reload-plugins를 실행하도록 말합니다.

URL에서 호스팅되는 .zip 아카이브로 이미 패키징된 플러그인을 테스트하려면(예: CI 빌드 아티팩트) 대신 --plugin-url을 사용하세요. Claude Code는 시작 시 아카이브를 가져오고 해당 세션에만 로드합니다. Claude Code가 아카이브를 가져올 수 없거나 아카이브가 유효하지 않으면 플러그인 없이 시작하고 /plugin 관리자의 Errors 탭에서 검토할 수 있는 플러그인 로드 오류를 기록합니다. 모든 플러그인 소스에 대해 동일한 신뢰 고려 사항이 적용됩니다: 이 플래그를 제어하거나 신뢰하는 아카이브에만 지정하세요.

여러 플러그인을 로드하려면 각 URL에 대해 플래그를 반복합니다:

claude --plugin-url https://example.com/my-plugin.zip --plugin-url https://example.com/other.zip

또는 공백으로 구분된 URL을 하나의 따옴표로 묶인 인수로 전달합니다:

claude --plugin-url "https://example.com/my-plugin.zip https://example.com/other.zip"

플러그인 문제 디버깅

플러그인이 예상대로 작동하지 않는 경우:

1. 구조 확인: 디렉토리가 .claude-plugin/ 내부가 아닌 플러그인 루트에 있는지 확인하세요
2. 구성 요소를 개별적으로 테스트: 각 skill, agent, hook을 별도로 확인하세요
3. 검증 및 디버깅 도구 사용: CLI 명령 및 문제 해결 기법은 디버깅 및 개발 도구를 참조하세요

플러그인 공유

플러그인을 공유할 준비가 되면:

1. 문서 추가: 설치 및 사용 지침이 포함된 README.md를 포함하세요
2. 버전 관리 전략 선택: 명시적 version을 설정할지 또는 버전 관리에 설명된 폴백에 의존할지 결정하세요.
3. 마켓플레이스 만들기 또는 사용: 플러그인 마켓플레이스를 통해 배포하여 설치하세요
4. 다른 사람과 테스트: 더 광범위한 배포 전에 팀원이 플러그인을 테스트하도록 하세요

플러그인이 마켓플레이스에 있으면 다른 사람들이 플러그인 발견 및 설치의 지침을 사용하여 설치할 수 있습니다. 플러그인을 팀 내부로만 유지하려면 비공개 저장소에서 마켓플레이스를 호스팅하세요.

플러그인을 커뮤니티 마켓플레이스에 제출

Anthropic은 Claude Code 플러그인을 위한 두 개의 공개 마켓플레이스를 유지합니다:

• claude-plugins-official: Anthropic에서 유지 관리하는 엄선된 플러그인 세트입니다. Claude Code를 처음 대화형으로 시작할 때 자동으로 등록됩니다. 첫 번째 시작 전에 Claude Code를 비대화형으로 실행하거나 마켓플레이스 정책이 이전 시도를 차단한 경우 claude plugin marketplace add anthropics/claude-plugins-official로 직접 등록하세요.
• claude-community: 검토 후 타사 제출이 도착하는 공개 커뮤니티 마켓플레이스입니다. 사용자는 /plugin marketplace add anthropics/claude-plugins-community로 추가하고 @claude-community로 설치합니다.

커뮤니티 마켓플레이스 검토를 위해 플러그인을 제출하려면 다음 앱 내 양식 중 하나를 사용하세요:

• claude.ai: claude.ai/admin-settings/directory/submissions/plugins/new
• Console: platform.claude.com/plugins/submit

claude.ai 양식은 Team 또는 Enterprise 조직과 디렉토리 관리 액세스가 필요합니다. 조직 소유자는 기본적으로 이 액세스 권한을 가집니다. Team 또는 Enterprise 조직에 속하지 않은 개별 작성자는 대신 Console 양식을 사용할 수 있습니다.

제출하기 전에 로컬에서 claude plugin validate ./your-plugin을 실행하세요. 플러그인 디렉토리의 경로로 ./your-plugin을 바꾸세요. 검토 파이프라인은 모든 제출에 대해 동일한 검사를 실행하며, 자동화된 안전 검사도 함께 수행합니다. 검증이 통과하면 Claude Code는 ✔ Validation passed 또는 경고가 있는 경우 ✔ Validation passed with warnings를 출력합니다. 경고는 검증을 실패하지 않습니다. --strict를 추가하여 경고를 오류로 취급하세요.

승인된 플러그인은 anthropics/claude-plugins-community 카탈로그의 특정 커밋 SHA에 고정되며, CI는 저장소에 새 커밋을 푸시할 때 자동으로 핀을 업데이트합니다. 공개 카탈로그는 검토 파이프라인에서 매일 밤 동기화되므로 승인과 플러그인이 marketplace.json에 나타나는 사이에 지연이 있을 수 있습니다. 플러그인이 설치 가능한지 확인하려면 커뮤니티 카탈로그에서 이름을 검색하세요.

공식 마켓플레이스인 claude-plugins-official은 별도로 엄선됩니다. Anthropic은 자신의 재량에 따라 포함할 플러그인을 결정합니다. 신청 절차가 없으며, 제출 양식은 플러그인을 공식 마켓플레이스에 추가하지 않습니다.

Anthropic이 플러그인을 공식 마켓플레이스에 나열하면 CLI에서 Claude Code 사용자에게 설치를 권장할 수 있습니다. CLI에서 플러그인 권장을 참조하세요.

기존 구성을 플러그인으로 변환

.claude/ 디렉토리에 이미 skills 또는 hooks가 있는 경우 더 쉬운 공유 및 배포를 위해 플러그인으로 변환할 수 있습니다.

마이그레이션 단계

mkdir -p my-plugin/.claude-plugin

{
"name": "my-plugin",
"description": "Migrated from standalone configuration",
"version": "1.0.0"
}

cp -r .claude/commands my-plugin/

cp -r .claude/agents my-plugin/

cp -r .claude/skills my-plugin/

mkdir my-plugin/hooks

{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
}
]
}
}

claude --plugin-dir ./my-plugin

마이그레이션 시 변경되는 사항

다음 단계

이제 Claude Code의 플러그인 시스템을 이해했으므로 다양한 목표에 대한 제안된 경로는 다음과 같습니다:

플러그인 사용자의 경우

• 플러그인 발견 및 설치: 마켓플레이스를 검색하고 플러그인을 설치합니다
• 팀 마켓플레이스 구성: 팀을 위한 저장소 수준 플러그인을 설정합니다

플러그인 개발자의 경우

• evals를 사용하여 플러그인 테스트: 플러그인이 변경하는 내용을 측정하고 CI에서 이를 제어합니다
• 마켓플레이스 만들기 및 배포: 플러그인을 패키징하고 공유합니다
• 플러그인 참조: 완전한 기술 사양
• 특정 플러그인 구성 요소에 대해 더 깊이 있게 살펴보세요:
  • Skills: skill 개발 세부 사항
  • Subagents: agent 구성 및 기능
  • Hooks: 이벤트 처리 및 자동화
  • MCP: 외부 도구 통합