플러그인 만들기

스킬, 에이전트, 훅, MCP 서버를 활용하여 Claude Code를 확장하는 커스텀 플러그인을 만드세요.

플러그인을 사용하면 프로젝트와 팀 간에 공유할 수 있는 커스텀 기능으로 Claude Code를 확장할 수 있습니다. 이 가이드에서는 스킬, 에이전트, 훅, MCP 서버를 포함한 자체 플러그인을 만드는 방법을 다룹니다.

기존 플러그인을 설치하려면 플러그인 검색 및 설치를 참조하세요. 전체 기술 사양은 플러그인 레퍼런스를 참조하세요.

플러그인 vs 독립 실행형 설정 사용 시점

Claude Code는 커스텀 스킬, 에이전트, 훅을 추가하는 두 가지 방법을 지원합니다:

접근 방식	스킬 이름	적합한 용도
독립 실행형 (`.claude/` 디렉토리)	`/hello`	개인 워크플로우, 프로젝트별 커스터마이징, 빠른 실험
플러그인 (`.claude-plugin/plugin.json`이 있는 디렉토리)	`/plugin-name:hello`	팀원과 공유, 커뮤니티 배포, 버전 관리된 릴리스, 프로젝트 간 재사용

독립 실행형 설정을 사용해야 하는 경우:

단일 프로젝트에 대해 Claude Code를 커스터마이징하는 경우
설정이 개인적이며 공유할 필요가 없는 경우
패키징하기 전에 스킬이나 훅을 실험하는 경우
/hello나 /review 같은 짧은 스킬 이름을 원하는 경우

플러그인을 사용해야 하는 경우:

팀이나 커뮤니티와 기능을 공유하고 싶은 경우
여러 프로젝트에서 동일한 스킬/에이전트가 필요한 경우
확장 기능에 대한 버전 관리와 간편한 업데이트를 원하는 경우
마켓플레이스를 통해 배포하는 경우
/my-plugin:hello와 같은 네임스페이스 스킬을 사용해도 괜찮은 경우 (네임스페이스는 플러그인 간 충돌을 방지합니다)

팁:

빠른 반복 작업을 위해 .claude/의 독립 실행형 설정으로 시작한 다음, 공유할 준비가 되면 플러그인으로 변환하세요.

빠른 시작

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

사전 요구 사항

Claude Code 설치 및 인증 완료
Claude Code 버전 1.0.33 이상 (claude --version으로 확인)

참고:

/plugin 명령어가 보이지 않으면 Claude Code를 최신 버전으로 업데이트하세요. 업그레이드 방법은 문제 해결을 참조하세요.

첫 번째 플러그인 만들기

Step 1: 플러그인 디렉토리 생성

모든 플러그인은 매니페스트와 스킬, 에이전트 또는 훅을 포함하는 자체 디렉토리에 위치합니다. 지금 하나 만들어 보세요:

mkdir my-first-plugin

Step 2: 플러그인 매니페스트 생성

.claude-plugin/plugin.json에 있는 매니페스트 파일은 플러그인의 정체성(이름, 설명, 버전)을 정의합니다. Claude Code는 이 메타데이터를 사용하여 플러그인 관리자에서 플러그인을 표시합니다.

플러그인 폴더 안에 .claude-plugin 디렉토리를 생성합니다:

mkdir my-first-plugin/.claude-plugin

그런 다음 다음 내용으로 my-first-plugin/.claude-plugin/plugin.json을 생성합니다:

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

필드	용도
`name`	고유 식별자이자 스킬 네임스페이스. 스킬에 이 이름이 접두사로 붙습니다 (예: `/my-first-plugin:hello`).
`description`	플러그인을 검색하거나 설치할 때 플러그인 관리자에 표시됩니다.
`version`	시맨틱 버저닝을 사용하여 릴리스를 추적합니다.
`author`	선택 사항. 저작자 표시에 유용합니다.

homepage, repository, license 등 추가 필드는 전체 매니페스트 스키마를 참조하세요.

Step 3: 스킬 추가

스킬은 skills/ 디렉토리에 위치합니다. 각 스킬은 SKILL.md 파일을 포함하는 폴더입니다. 폴더 이름이 플러그인의 네임스페이스와 결합되어 스킬 이름이 됩니다 (my-first-plugin이라는 플러그인의 hello/는 /my-first-plugin:hello를 생성합니다).

플러그인 폴더에 스킬 디렉토리를 생성합니다:

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

그런 다음 다음 내용으로 my-first-plugin/skills/hello/SKILL.md를 생성합니다:

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

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

Step 4: 플러그인 테스트

--plugin-dir 플래그를 사용하여 Claude Code에서 플러그인을 로드합니다:

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

Claude Code가 시작되면 새 스킬을 사용해 보세요:

/my-first-plugin:hello

Claude가 인사로 응답하는 것을 볼 수 있습니다. /help를 실행하면 플러그인 네임스페이스 아래에 스킬이 나열되는 것을 확인할 수 있습니다.

참고:

네임스페이스를 사용하는 이유는? 플러그인 스킬은 항상 네임스페이스가 지정되어 (예: /greet:hello) 여러 플러그인이 동일한 이름의 스킬을 가질 때 충돌을 방지합니다.

네임스페이스 접두사를 변경하려면 plugin.json의 name 필드를 수정하세요.

Step 5: 스킬 인자 추가

사용자 입력을 받아 스킬을 동적으로 만들 수 있습니다. $ARGUMENTS 플레이스홀더는 스킬 이름 뒤에 사용자가 제공하는 텍스트를 캡처합니다.

SKILL.md 파일을 업데이트합니다:

---
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.

변경 사항을 적용하려면 Claude Code를 재시작한 다음, 이름과 함께 스킬을 사용해 보세요:

/my-first-plugin:hello Alex

Claude가 이름을 불러 인사할 것입니다. 스킬에 인자를 전달하는 방법에 대한 자세한 내용은 스킬을 참조하세요.

플러그인을 성공적으로 만들고 테스트했습니다. 핵심 구성 요소는 다음과 같습니다:

플러그인 매니페스트 (.claude-plugin/plugin.json): 플러그인의 메타데이터를 정의합니다
스킬 디렉토리 (skills/): 커스텀 스킬을 포함합니다
스킬 인자 ($ARGUMENTS): 동적 동작을 위한 사용자 입력을 캡처합니다

팁:

--plugin-dir 플래그는 개발 및 테스트에 유용합니다. 다른 사람들과 플러그인을 공유할 준비가 되면 플러그인 마켓플레이스 생성 및 배포를 참조하세요.

플러그인 구조 개요

스킬이 포함된 플러그인을 만들었지만, 플러그인에는 커스텀 에이전트, 훅, MCP 서버, LSP 서버 등 훨씬 더 많은 것을 포함할 수 있습니다.

주의:

흔한 실수: commands/, agents/, skills/, hooks/를 .claude-plugin/ 디렉토리 안에 넣지 마세요. .claude-plugin/ 안에는 plugin.json만 들어갑니다. 다른 모든 디렉토리는 플러그인 루트 레벨에 있어야 합니다.

디렉토리	위치	용도
`.claude-plugin/`	플러그인 루트	`plugin.json` 매니페스트 포함 (컴포넌트가 기본 위치를 사용하면 선택 사항)
`commands/`	플러그인 루트	Markdown 파일 형태의 스킬
`agents/`	플러그인 루트	커스텀 에이전트 정의
`skills/`	플러그인 루트	`SKILL.md` 파일이 포함된 에이전트 스킬
`hooks/`	플러그인 루트	`hooks.json`의 이벤트 핸들러
`.mcp.json`	플러그인 루트	MCP 서버 설정
`.lsp.json`	플러그인 루트	코드 인텔리전스를 위한 LSP 서버 설정
`settings.json`	플러그인 루트	플러그인 활성화 시 적용되는 기본 설정

참고:

다음 단계: 더 많은 기능을 추가할 준비가 되셨나요? 더 복잡한 플러그인 개발로 이동하여 에이전트, 훅, MCP 서버, LSP 서버를 추가하세요. 모든 플러그인 컴포넌트의 전체 기술 사양은 플러그인 레퍼런스를 참조하세요.

더 복잡한 플러그인 개발

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

플러그인에 스킬 추가

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

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

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

각 SKILL.md에는 name과 description 필드가 있는 프론트매터와 지시사항이 필요합니다:

---
name: code-review
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

플러그인을 설치한 후 Claude Code를 재시작하여 스킬을 로드하세요. 점진적 공개 및 도구 제한을 포함한 전체 스킬 작성 가이드는 에이전트 스킬을 참조하세요.

플러그인에 LSP 서버 추가

팁:

TypeScript, Python, Rust와 같은 일반적인 언어의 경우 공식 마켓플레이스에서 사전 빌드된 LSP 플러그인을 설치하세요. 아직 지원되지 않는 언어에 대한 지원이 필요한 경우에만 커스텀 LSP 플러그인을 만드세요.

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

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

플러그인을 설치하는 사용자는 자신의 머신에 해당 언어 서버 바이너리가 설치되어 있어야 합니다.

전체 LSP 설정 옵션은 LSP 서버를 참조하세요.

플러그인에 기본 설정 포함

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

agent를 설정하면 플러그인의 커스텀 에이전트 중 하나가 메인 스레드로 활성화되어 시스템 프롬프트, 도구 제한, 모델이 적용됩니다. 이를 통해 플러그인이 활성화될 때 Claude Code의 기본 동작 방식을 변경할 수 있습니다.

{
  "agent": "security-reviewer"
}

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

복잡한 플러그인 구성

많은 컴포넌트가 있는 플러그인의 경우 기능별로 디렉토리 구조를 구성하세요. 전체 디렉토리 레이아웃과 구성 패턴은 플러그인 디렉토리 구조를 참조하세요.

플러그인 로컬 테스트

개발 중에 --plugin-dir 플래그를 사용하여 플러그인을 테스트하세요. 설치 없이 플러그인을 직접 로드합니다.

claude --plugin-dir ./my-plugin

플러그인을 변경할 때마다 Claude Code를 재시작하여 업데이트를 적용하세요. 플러그인 컴포넌트를 테스트합니다:

/plugin-name:skill-name으로 스킬을 사용해 보세요
/agents에서 에이전트가 표시되는지 확인하세요
훅이 예상대로 작동하는지 검증하세요

팁:

플래그를 여러 번 지정하여 여러 플러그인을 한 번에 로드할 수 있습니다:
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

플러그인 문제 디버깅

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

구조 확인: 디렉토리가 .claude-plugin/ 안이 아닌 플러그인 루트에 있는지 확인하세요
컴포넌트 개별 테스트: 각 명령, 에이전트, 훅을 별도로 확인하세요
검증 및 디버깅 도구 사용: CLI 명령어와 문제 해결 기법은 디버깅 및 개발 도구를 참조하세요

플러그인 공유

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

문서 추가: 설치 및 사용 방법이 포함된 README.md를 작성하세요
플러그인 버전 관리: plugin.json에서 시맨틱 버저닝을 사용하세요
마켓플레이스 생성 또는 사용: 플러그인 마켓플레이스를 통해 배포하세요
다른 사람과 테스트: 광범위한 배포 전에 팀원들이 플러그인을 테스트하도록 하세요

플러그인이 마켓플레이스에 등록되면 다른 사용자들이 플러그인 검색 및 설치의 안내에 따라 설치할 수 있습니다.

공식 마켓플레이스에 플러그인 제출

공식 Anthropic 마켓플레이스에 플러그인을 제출하려면 앱 내 제출 양식 중 하나를 사용하세요:

Claude.ai: claude.ai/settings/plugins/submit
Console: platform.claude.com/plugins/submit

참고:

전체 기술 사양, 디버깅 기법, 배포 전략은 플러그인 레퍼런스를 참조하세요.

기존 설정을 플러그인으로 변환

.claude/ 디렉토리에 이미 스킬이나 훅이 있다면 더 쉬운 공유와 배포를 위해 플러그인으로 변환할 수 있습니다.

마이그레이션 단계

Step 1: 플러그인 구조 생성

새 플러그인 디렉토리를 생성합니다:

mkdir -p my-plugin/.claude-plugin

my-plugin/.claude-plugin/plugin.json에 매니페스트 파일을 생성합니다:

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

Step 2: 기존 파일 복사

기존 설정을 플러그인 디렉토리로 복사합니다:

# Copy commands
cp -r .claude/commands my-plugin/

# Copy agents (if any)
cp -r .claude/agents my-plugin/

# Copy skills (if any)
cp -r .claude/skills my-plugin/

Step 3: 훅 마이그레이션

설정에 훅이 있는 경우 hooks 디렉토리를 생성합니다:

mkdir my-plugin/hooks

훅 설정으로 my-plugin/hooks/hooks.json을 생성합니다. .claude/settings.json 또는 settings.local.json에서 hooks 객체를 복사하세요. 형식이 동일합니다. 명령은 stdin으로 JSON 형태의 훅 입력을 받으므로 jq를 사용하여 파일 경로를 추출합니다:

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

Step 4: 마이그레이션된 플러그인 테스트

플러그인을 로드하여 모든 것이 작동하는지 확인합니다:

claude --plugin-dir ./my-plugin

각 컴포넌트를 테스트합니다: 명령을 실행하고, /agents에서 에이전트가 표시되는지 확인하고, 훅이 올바르게 트리거되는지 검증합니다.

마이그레이션 시 변경 사항

독립 실행형 (`.claude/`)	플러그인
하나의 프로젝트에서만 사용 가능	마켓플레이스를 통해 공유 가능
`.claude/commands/`에 파일 위치	`plugin-name/commands/`에 파일 위치
`settings.json`에 훅 정의	`hooks/hooks.json`에 훅 정의
공유하려면 수동으로 복사 필요	`/plugin install`로 설치

참고:

마이그레이션 후 중복을 피하기 위해 .claude/에서 원본 파일을 제거할 수 있습니다. 로드 시 플러그인 버전이 우선합니다.

다음 단계

이제 Claude Code의 플러그인 시스템을 이해했으므로 다양한 목표에 맞는 경로를 제안합니다:

플러그인 사용자를 위한 안내

플러그인 검색 및 설치: 마켓플레이스를 탐색하고 플러그인을 설치하세요
팀 마켓플레이스 설정: 팀을 위한 저장소 수준 플러그인을 설정하세요

플러그인 개발자를 위한 안내

마켓플레이스 생성 및 배포: 플러그인을 패키징하고 공유하세요
플러그인 레퍼런스: 전체 기술 사양
특정 플러그인 컴포넌트 심화 학습:
- 스킬: 스킬 개발 상세 정보
- 서브에이전트: 에이전트 설정 및 기능
- 훅: 이벤트 처리 및 자동화
- MCP: 외부 도구 통합

플러그인 만들기

스킬, 에이전트, 훅, MCP 서버를 활용하여 Claude Code를 확장하는 커스텀 플러그인을 만드세요.

기존 플러그인을 설치하려면 플러그인 검색 및 설치를 참조하세요. 전체 기술 사양은 플러그인 레퍼런스를 참조하세요.

플러그인 vs 독립 실행형 설정 사용 시점

Claude Code는 커스텀 스킬, 에이전트, 훅을 추가하는 두 가지 방법을 지원합니다:

접근 방식	스킬 이름	적합한 용도
독립 실행형 (`.claude/` 디렉토리)	`/hello`	개인 워크플로우, 프로젝트별 커스터마이징, 빠른 실험
플러그인 (`.claude-plugin/plugin.json`이 있는 디렉토리)	`/plugin-name:hello`	팀원과 공유, 커뮤니티 배포, 버전 관리된 릴리스, 프로젝트 간 재사용

독립 실행형 설정을 사용해야 하는 경우:

단일 프로젝트에 대해 Claude Code를 커스터마이징하는 경우
설정이 개인적이며 공유할 필요가 없는 경우
패키징하기 전에 스킬이나 훅을 실험하는 경우
/hello나 /review 같은 짧은 스킬 이름을 원하는 경우

플러그인을 사용해야 하는 경우:

팀이나 커뮤니티와 기능을 공유하고 싶은 경우
여러 프로젝트에서 동일한 스킬/에이전트가 필요한 경우
확장 기능에 대한 버전 관리와 간편한 업데이트를 원하는 경우
마켓플레이스를 통해 배포하는 경우
/my-plugin:hello와 같은 네임스페이스 스킬을 사용해도 괜찮은 경우 (네임스페이스는 플러그인 간 충돌을 방지합니다)

팁:

빠른 반복 작업을 위해 .claude/의 독립 실행형 설정으로 시작한 다음, 공유할 준비가 되면 플러그인으로 변환하세요.

빠른 시작

사전 요구 사항

Claude Code 설치 및 인증 완료
Claude Code 버전 1.0.33 이상 (claude --version으로 확인)

참고:

/plugin 명령어가 보이지 않으면 Claude Code를 최신 버전으로 업데이트하세요. 업그레이드 방법은 문제 해결을 참조하세요.

첫 번째 플러그인 만들기

Step 1: 플러그인 디렉토리 생성

모든 플러그인은 매니페스트와 스킬, 에이전트 또는 훅을 포함하는 자체 디렉토리에 위치합니다. 지금 하나 만들어 보세요:

mkdir my-first-plugin

Step 2: 플러그인 매니페스트 생성

플러그인 폴더 안에 .claude-plugin 디렉토리를 생성합니다:

mkdir my-first-plugin/.claude-plugin

그런 다음 다음 내용으로 my-first-plugin/.claude-plugin/plugin.json을 생성합니다:

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

필드	용도
`name`	고유 식별자이자 스킬 네임스페이스. 스킬에 이 이름이 접두사로 붙습니다 (예: `/my-first-plugin:hello`).
`description`	플러그인을 검색하거나 설치할 때 플러그인 관리자에 표시됩니다.
`version`	시맨틱 버저닝을 사용하여 릴리스를 추적합니다.
`author`	선택 사항. 저작자 표시에 유용합니다.

homepage, repository, license 등 추가 필드는 전체 매니페스트 스키마를 참조하세요.

Step 3: 스킬 추가

플러그인 폴더에 스킬 디렉토리를 생성합니다:

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

그런 다음 다음 내용으로 my-first-plugin/skills/hello/SKILL.md를 생성합니다:

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

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

Step 4: 플러그인 테스트

--plugin-dir 플래그를 사용하여 Claude Code에서 플러그인을 로드합니다:

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

Claude Code가 시작되면 새 스킬을 사용해 보세요:

/my-first-plugin:hello

Claude가 인사로 응답하는 것을 볼 수 있습니다. /help를 실행하면 플러그인 네임스페이스 아래에 스킬이 나열되는 것을 확인할 수 있습니다.

참고:

네임스페이스를 사용하는 이유는? 플러그인 스킬은 항상 네임스페이스가 지정되어 (예: /greet:hello) 여러 플러그인이 동일한 이름의 스킬을 가질 때 충돌을 방지합니다.

네임스페이스 접두사를 변경하려면 plugin.json의 name 필드를 수정하세요.

Step 5: 스킬 인자 추가

사용자 입력을 받아 스킬을 동적으로 만들 수 있습니다. $ARGUMENTS 플레이스홀더는 스킬 이름 뒤에 사용자가 제공하는 텍스트를 캡처합니다.

SKILL.md 파일을 업데이트합니다:

---
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.

변경 사항을 적용하려면 Claude Code를 재시작한 다음, 이름과 함께 스킬을 사용해 보세요:

/my-first-plugin:hello Alex

Claude가 이름을 불러 인사할 것입니다. 스킬에 인자를 전달하는 방법에 대한 자세한 내용은 스킬을 참조하세요.

플러그인을 성공적으로 만들고 테스트했습니다. 핵심 구성 요소는 다음과 같습니다:

플러그인 매니페스트 (.claude-plugin/plugin.json): 플러그인의 메타데이터를 정의합니다
스킬 디렉토리 (skills/): 커스텀 스킬을 포함합니다
스킬 인자 ($ARGUMENTS): 동적 동작을 위한 사용자 입력을 캡처합니다

팁:

--plugin-dir 플래그는 개발 및 테스트에 유용합니다. 다른 사람들과 플러그인을 공유할 준비가 되면 플러그인 마켓플레이스 생성 및 배포를 참조하세요.

플러그인 구조 개요

스킬이 포함된 플러그인을 만들었지만, 플러그인에는 커스텀 에이전트, 훅, MCP 서버, LSP 서버 등 훨씬 더 많은 것을 포함할 수 있습니다.

주의:

흔한 실수: commands/, agents/, skills/, hooks/를 .claude-plugin/ 디렉토리 안에 넣지 마세요. .claude-plugin/ 안에는 plugin.json만 들어갑니다. 다른 모든 디렉토리는 플러그인 루트 레벨에 있어야 합니다.

디렉토리	위치	용도
`.claude-plugin/`	플러그인 루트	`plugin.json` 매니페스트 포함 (컴포넌트가 기본 위치를 사용하면 선택 사항)
`commands/`	플러그인 루트	Markdown 파일 형태의 스킬
`agents/`	플러그인 루트	커스텀 에이전트 정의
`skills/`	플러그인 루트	`SKILL.md` 파일이 포함된 에이전트 스킬
`hooks/`	플러그인 루트	`hooks.json`의 이벤트 핸들러
`.mcp.json`	플러그인 루트	MCP 서버 설정
`.lsp.json`	플러그인 루트	코드 인텔리전스를 위한 LSP 서버 설정
`settings.json`	플러그인 루트	플러그인 활성화 시 적용되는 기본 설정

참고:

다음 단계: 더 많은 기능을 추가할 준비가 되셨나요? 더 복잡한 플러그인 개발로 이동하여 에이전트, 훅, MCP 서버, LSP 서버를 추가하세요. 모든 플러그인 컴포넌트의 전체 기술 사양은 플러그인 레퍼런스를 참조하세요.

더 복잡한 플러그인 개발

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

플러그인에 스킬 추가

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

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

각 SKILL.md에는 name과 description 필드가 있는 프론트매터와 지시사항이 필요합니다:

---
name: code-review
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

플러그인에 LSP 서버 추가

팁:

TypeScript, Python, Rust와 같은 일반적인 언어의 경우 공식 마켓플레이스에서 사전 빌드된 LSP 플러그인을 설치하세요. 아직 지원되지 않는 언어에 대한 지원이 필요한 경우에만 커스텀 LSP 플러그인을 만드세요.

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

플러그인을 설치하는 사용자는 자신의 머신에 해당 언어 서버 바이너리가 설치되어 있어야 합니다.

전체 LSP 설정 옵션은 LSP 서버를 참조하세요.

플러그인에 기본 설정 포함

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

{
  "agent": "security-reviewer"
}

복잡한 플러그인 구성

플러그인 로컬 테스트

개발 중에 --plugin-dir 플래그를 사용하여 플러그인을 테스트하세요. 설치 없이 플러그인을 직접 로드합니다.

claude --plugin-dir ./my-plugin

플러그인을 변경할 때마다 Claude Code를 재시작하여 업데이트를 적용하세요. 플러그인 컴포넌트를 테스트합니다:

/plugin-name:skill-name으로 스킬을 사용해 보세요
/agents에서 에이전트가 표시되는지 확인하세요
훅이 예상대로 작동하는지 검증하세요

팁:

플래그를 여러 번 지정하여 여러 플러그인을 한 번에 로드할 수 있습니다:
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

플러그인 문제 디버깅

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

구조 확인: 디렉토리가 .claude-plugin/ 안이 아닌 플러그인 루트에 있는지 확인하세요
컴포넌트 개별 테스트: 각 명령, 에이전트, 훅을 별도로 확인하세요
검증 및 디버깅 도구 사용: CLI 명령어와 문제 해결 기법은 디버깅 및 개발 도구를 참조하세요

플러그인 공유

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

문서 추가: 설치 및 사용 방법이 포함된 README.md를 작성하세요
플러그인 버전 관리: plugin.json에서 시맨틱 버저닝을 사용하세요
마켓플레이스 생성 또는 사용: 플러그인 마켓플레이스를 통해 배포하세요
다른 사람과 테스트: 광범위한 배포 전에 팀원들이 플러그인을 테스트하도록 하세요

플러그인이 마켓플레이스에 등록되면 다른 사용자들이 플러그인 검색 및 설치의 안내에 따라 설치할 수 있습니다.

공식 마켓플레이스에 플러그인 제출

공식 Anthropic 마켓플레이스에 플러그인을 제출하려면 앱 내 제출 양식 중 하나를 사용하세요:

Claude.ai: claude.ai/settings/plugins/submit
Console: platform.claude.com/plugins/submit

참고:

전체 기술 사양, 디버깅 기법, 배포 전략은 플러그인 레퍼런스를 참조하세요.

기존 설정을 플러그인으로 변환

.claude/ 디렉토리에 이미 스킬이나 훅이 있다면 더 쉬운 공유와 배포를 위해 플러그인으로 변환할 수 있습니다.

마이그레이션 단계

Step 1: 플러그인 구조 생성

새 플러그인 디렉토리를 생성합니다:

mkdir -p my-plugin/.claude-plugin

my-plugin/.claude-plugin/plugin.json에 매니페스트 파일을 생성합니다:

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

Step 2: 기존 파일 복사

기존 설정을 플러그인 디렉토리로 복사합니다:

# Copy commands
cp -r .claude/commands my-plugin/

# Copy agents (if any)
cp -r .claude/agents my-plugin/

# Copy skills (if any)
cp -r .claude/skills my-plugin/

Step 3: 훅 마이그레이션

설정에 훅이 있는 경우 hooks 디렉토리를 생성합니다:

mkdir my-plugin/hooks

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

Step 4: 마이그레이션된 플러그인 테스트

플러그인을 로드하여 모든 것이 작동하는지 확인합니다:

claude --plugin-dir ./my-plugin

각 컴포넌트를 테스트합니다: 명령을 실행하고, /agents에서 에이전트가 표시되는지 확인하고, 훅이 올바르게 트리거되는지 검증합니다.

마이그레이션 시 변경 사항

독립 실행형 (`.claude/`)	플러그인
하나의 프로젝트에서만 사용 가능	마켓플레이스를 통해 공유 가능
`.claude/commands/`에 파일 위치	`plugin-name/commands/`에 파일 위치
`settings.json`에 훅 정의	`hooks/hooks.json`에 훅 정의
공유하려면 수동으로 복사 필요	`/plugin install`로 설치

참고:

마이그레이션 후 중복을 피하기 위해 .claude/에서 원본 파일을 제거할 수 있습니다. 로드 시 플러그인 버전이 우선합니다.

다음 단계

이제 Claude Code의 플러그인 시스템을 이해했으므로 다양한 목표에 맞는 경로를 제안합니다:

플러그인 사용자를 위한 안내

플러그인 검색 및 설치: 마켓플레이스를 탐색하고 플러그인을 설치하세요
팀 마켓플레이스 설정: 팀을 위한 저장소 수준 플러그인을 설정하세요

플러그인 개발자를 위한 안내

마켓플레이스 생성 및 배포: 플러그인을 패키징하고 공유하세요
플러그인 레퍼런스: 전체 기술 사양
특정 플러그인 컴포넌트 심화 학습:
- 스킬: 스킬 개발 상세 정보
- 서브에이전트: 에이전트 설정 및 기능
- 훅: 이벤트 처리 및 자동화
- MCP: 외부 도구 통합

11. 플러그인 만들기

플러그인 만들기

플러그인 vs 독립 실행형 설정 사용 시점

빠른 시작

사전 요구 사항

첫 번째 플러그인 만들기

Step 1: 플러그인 디렉토리 생성

Step 2: 플러그인 매니페스트 생성

Step 3: 스킬 추가

Step 4: 플러그인 테스트

Step 5: 스킬 인자 추가

플러그인 구조 개요

더 복잡한 플러그인 개발

플러그인에 스킬 추가

플러그인에 LSP 서버 추가

플러그인에 기본 설정 포함

복잡한 플러그인 구성

플러그인 로컬 테스트

플러그인 문제 디버깅

플러그인 공유

공식 마켓플레이스에 플러그인 제출

기존 설정을 플러그인으로 변환

마이그레이션 단계

Step 1: 플러그인 구조 생성

Step 2: 기존 파일 복사

Step 3: 훅 마이그레이션

Step 4: 마이그레이션된 플러그인 테스트

마이그레이션 시 변경 사항

다음 단계

플러그인 사용자를 위한 안내

플러그인 개발자를 위한 안내

11. 플러그인 만들기

플러그인 만들기

플러그인 vs 독립 실행형 설정 사용 시점

빠른 시작

사전 요구 사항

첫 번째 플러그인 만들기

Step 1: 플러그인 디렉토리 생성

Step 2: 플러그인 매니페스트 생성

Step 3: 스킬 추가

Step 4: 플러그인 테스트

Step 5: 스킬 인자 추가

플러그인 구조 개요

더 복잡한 플러그인 개발

플러그인에 스킬 추가

플러그인에 LSP 서버 추가

플러그인에 기본 설정 포함

복잡한 플러그인 구성

플러그인 로컬 테스트

플러그인 문제 디버깅

플러그인 공유

공식 마켓플레이스에 플러그인 제출

기존 설정을 플러그인으로 변환

마이그레이션 단계

Step 1: 플러그인 구조 생성

Step 2: 기존 파일 복사

Step 3: 훅 마이그레이션

Step 4: 마이그레이션된 플러그인 테스트

마이그레이션 시 변경 사항

다음 단계

플러그인 사용자를 위한 안내

플러그인 개발자를 위한 안내