플러그인

플러그인 (Plugins)

플러그인은 Claude Code의 기능(명령·도구·훅·에이전트·MCP 서버 등)을 하나의 확장 팩으로 패키징해 팀과 공유하거나 마켓플레이스로 배포할 수 있게 합니다. 스킬(skills)이 저장소 안의 지식을 온디맨드로 로드하는 것이라면, 플러그인은 코드·명령·도구를 담을 수 있는 더 넓은 확장 단위입니다. 이 페이지는 플러그인 찾기·설치·만들기·게시를 다룹니다.

출처: 공식문서

본문

플러그인은 무엇인가

플러그인은 홈 디렉토리의 플러그인 디렉토리(~/.claude/plugins/ 또는 CLAUDE_CONFIG_DIR 기준)에 설치되는 디렉토리로, plugin.json 매니페스트와 선택적 자원(commands, tools, agents, hooks, MCP 서버, slash commands, statusline)을 담습니다. 조직·마켓플레이스를 통해 공유할 수 있습니다.

플러그인 찾기·설치

  • /plugin 메뉴: Claude Code 안에서 +를 눌러 플러그인 설치. 이름으로 검색하거나 공식 Claude Code 마켓플레이스에서 찾을 수 있습니다.
  • 마켓플레이스 등록: extraKnownMarketplaces 설정에 마켓플레이스를 추가합니다. 팀 설정(.claude/settings.json)에 넣어 모두가 공유할 수 있습니다:
{
  "extraKnownMarketplaces": {
    "my-marketplace": {
      "source": {
        "source": "github",
        "repo": "my-org/claude-plugins"
      }
    }
  }
}
  • hx CLI: claude plugin marketplace add, claude plugin install <plugin> 등 claude plugin 하위명령으로 명령줄에서 관리합니다.
  • 운영 정책: strictKnownMarketplaces(관리), enabledPlugins(개별 플러그인 활성화)로 조직이 제한할 수 있습니다.

플러그인 만들기

플러그인은 최상위에 은닉 .claude-plugin/plugin.json을 가진 표준 디렉토리입니다:

my-plugin/
└── .claude-plugin/
    └── plugin.json

{
  "name": "my-plugin",
  "description": "A short description of my plugin",
  "version": "1.0.0",
  "author": {
    "name": "My Name"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/myorg/my-plugin"
  }
}

plugin.json 필드: name(필수, 소문자·하이픈), description, version, author, repository, 그리고 내부적으로 license, keywords, readme 등을 지원합니다.

플러그인 구성 요소

플러그인이 담을 수 있는 자원과 그 배치:

  • Commands(슬래시 커맨드): 마켓플레이스의 명령(commands)은 claude plugin install <marketplace> 후 사전 등록됩니다. 플러그인 저장소 안에서 /command 정의는 commands/ 디렉토리 아래 *.md로 둡니다(각 파일의 이름이 명령어, frontmatter에 description, 본문에 프롬프트). 사용 포맷: /plugin-command, /plugin-command arg1 arg2. env vars로 $ARG1 등 인자 참조.
  • Tools: 플러그인의 tools는 /plugin → detail에서 활성화하면 Claude가 사용할 수 있습니다. farm에서 tools/ 디렉토리의 구성으로 정의됩니다.
  • Agents(서브에이전트): .claude/agents/에 마크다운 정의 — YAML frontmatter(이름·description·tools)로.
  • Hooks: .claude/hooks/에 훅 정의.
  • MCP servers: .mcp.json 또는 mcpServers 구성으로 플러그인 안에 번들.
  • Slash commands: 어디서든 정의.
  • Statusline: 사용자 설정과 관계없이.

플러그인 상세

설치된 플러그인은 /plugin UI에서 표시되고, 사용자가 세션별로 활성화할 수 있습니다. 플러그인에서 온 훅·MCP·도구·에이전트·명령은 활성화 시 로드됩니다.

게시

플러그인을 GitHub 저장소에 밀고 마켓플레이스에 추가합니다. plugin.json의 repository 필드가 마켓플레이스 인덱스에서 플러그인을 위치시키는 기준이 됩니다. 공식 마켓플레이스에 추가하려면 저장소에 .claude-plugin/plugin.json이 있어야 합니다.

더 알아보기