Skip to main content

플러그인 시스템

플러그인은 Skills, Agents, Hooks, MCP/LSP 서버를 하나의 패키지로 묶어 프로젝트와 팀 간에 공유할 수 있게 합니다. 네임스페이스로 충돌을 방지하고, 마켓플레이스를 통해 배포할 수 있습니다.

플러그인 vs 단독 설정​

접근 방식Skill 이름적합한 경우
단독 (.claude/)/hello개인 워크플로우, 프로젝트 전용, 빠른 실험
플러그인 (.claude-plugin/)/plugin-name:hello팀 공유, 커뮤니티 배포, 버전 관리, 프로젝트 간 재사용

플러그인 구조​

my-plugin/
├── .claude-plugin/
│   └── plugin.json           # 매니페스트 (플러그인 정보)
├── skills/                   # Skills (SKILL.md 파일)
├── agents/                   # 커스텀 서브에이전트
├── commands/                 # Skills (마크다운 파일)
├── hooks/
│   └── hooks.json            # Hook 이벤트 핸들러
├── .mcp.json                 # MCP 서버 설정
├── .lsp.json                 # LSP 서버 설정
└── settings.json             # 플러그인 활성화 시 기본 설정
디렉토리 규칙

plugin.json만 .claude-plugin/ 안에 넣습니다. 나머지 모든 디렉토리(skills/, agents/, hooks/ 등)는 플러그인 루트 레벨에 배치합니다.

매니페스트 (plugin.json)​

{
  "name": "my-awesome-plugin",
  "description": "코드 품질 자동화 도구 모음",
  "version": "1.0.0",
  "author": "Team Awesome",
  "homepage": "https://github.com/team/my-plugin",
  "repository": "https://github.com/team/my-plugin",
  "license": "MIT"
}
필드필수설명
nameO고유 식별자이자 Skill 네임스페이스
descriptionO플러그인 매니저에 표시
versionO시맨틱 버저닝
author-저자 정보
homepage-홈페이지 URL
repository-소스 코드 리포지토리
license-라이선스

Skills 패키징​

skills/ 디렉토리에 SKILL.md 파일을 넣습니다. 폴더 이름이 Skill 이름이 되고, 플러그인 네임스페이스가 접두사로 붙습니다:

skills/
└── code-review/
    └── SKILL.md

이 Skill은 /my-awesome-plugin:code-review로 호출됩니다.

---
name: code-review
description: 코드 변경을 모범 사례와 보안 관점에서 리뷰합니다
---

코드를 리뷰할 때 확인할 사항:
1. 코드 구조와 조직
2. 에러 핸들링
3. 보안 이슈

인수 전달​

$ARGUMENTS 플레이스홀더로 사용자 입력을 받습니다:

---
description: 사용자를 인사하는 Skill
---

$ARGUMENTS 사용자를 반갑게 맞이하고 도움이 필요한지 물어보세요.

사용: /my-awesome-plugin:hello Alex

Agents 패키징​

agents/ 디렉토리에 커스텀 서브에이전트 마크다운 파일을 넣습니다:

---
name: security-reviewer
description: 보안 감사 전문 에이전트
tools: Read, Grep, Glob
model: sonnet
---

OWASP Top 10 기준으로 보안 취약점을 검사하세요.

Hooks 패키징​

hooks/hooks.json에 이벤트 핸들러를 정의합니다:

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

MCP/LSP 서버 패키징​

MCP 서버 (.mcp.json)​

플러그인 루트에 .mcp.json 파일로 MCP 서버를 정의합니다.

LSP 서버 (.lsp.json)​

LSP 서버는 실시간 코드 인텔리전스를 제공합니다:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}
LSP 요구사항

사용자 시스템에 언어 서버 바이너리가 설치되어 있어야 합니다.

기본 설정 (settings.json)​

플러그인 활성화 시 적용될 기본 설정:

{
  "agent": "security-reviewer"
}

agents/ 디렉토리의 커스텀 에이전트를 메인 스레드로 활성화할 수 있습니다.

네임스페이스 규칙​

  • 플러그인 Skill은 항상 네임스페이스가 붙어 충돌 방지
  • 형식: /plugin-name:skill-name
  • 네임스페이스는 plugin.json의 name 필드로 결정
  • 단독 Skill은 /skill-name으로 짧은 이름 사용

설치와 관리​

로컬 테스트​

# 개발 중 플러그인 직접 로드
claude --plugin-dir ./my-plugin

# 여러 플러그인 동시 로드
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

변경 후에는 Claude Code를 재시작해야 적용됩니다.

플러그인 관리 커맨드​

# 플러그인 관리 인터페이스
/plugin

# 설치/제거/목록
/plugin install
/plugin remove
/plugin list

# 사용 가능한 Skill 확인 (플러그인 포함)
/help

검증​

  • /plugin-name:skill-name으로 Skill 호출 확인
  • /agents에서 에이전트 표시 확인
  • Hook이 예상대로 동작하는지 확인

배포​

마켓플레이스 제출​

  1. README.md 문서화
  2. 시맨틱 버저닝으로 버전 관리
  3. 다른 사용자와 테스트
  4. 마켓플레이스에 제출:
    • Claude.ai: claude.ai/settings/plugins/submit
    • Console: platform.claude.com/plugins/submit

단독 → 플러그인 마이그레이션​

기존 .claude/ 파일을 플러그인 구조로 변환:

  1. .claude-plugin/plugin.json 매니페스트 생성
  2. .claude/skills/ → 플러그인 루트의 skills/로 복사
  3. .claude/agents/ → agents/로 복사
  4. Hook 설정 → hooks/hooks.json으로 이동
  5. MCP 설정 → .mcp.json으로 이동

다음 챕터: Worktree 모드 →

Last updated on