플러그인에 컴포넌트 추가하기

​

플러그인 디렉토리 탐색

• 검토 스킬과 about 명령
• 보안 검토 서브에이전트
• Claude가 파일을 편집한 후 파일을 포맷하는 훅과 이를 호출하는 scripts/ 폴더
• 로그 모니터
• 출력 스타일과 색상 테마
• 경로 감사 워크플로우
• hello-plugin 실행 파일
• 기본 설정
• 로컬 MCP 서버와 Go 언어 서버

​

각 유형의 구성 요소 추가하기

​

Skills

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

---
description: Reviews a pull request for style and test coverage. Use when asked to review code.
---

Review the changed files. Report style problems first, then missing tests.

• 명령 이름: /<plugin>:<directory> 형식이므로 my-plugin의 skills/review/SKILL.md는 /my-plugin:review가 됩니다. frontmatter에서 name을 설정하면 마지막 세그먼트가 대체되고 플러그인 접두사는 유지됩니다. 스킬의 명령 이름이 정해지는 방식을 참조하십시오
• 호출 주체: Claude, 사용자 또는 둘 다이며, frontmatter로 제어합니다. 스킬 호출 주체 제어하기를 참조하십시오

• 추가 디렉터리: skills 매니페스트 키에 나열합니다. commands 및 agents와 달리, 기본 skills/ 스캔을 대체하지 않고 여기에 추가됩니다
• 플러그인 루트의 단일 스킬: skills/ 디렉터리와 skills 매니페스트 키가 모두 없으면 플러그인 루트의 SKILL.md가 하나의 스킬로 로드됩니다. frontmatter에 name을 설정하십시오. 그렇지 않으면 마켓플레이스 설치 시 스킬 이름이 플러그인이 아닌 캐시 디렉터리 이름을 따르게 됩니다

​

Commands

​

매니페스트에서 명령 정의하기

{
  "name": "my-plugin",
  "commands": {
    "about": {
      "content": "Summarize what this repository does in three sentences.",
      "description": "Summarize the repository"
    }
  }
}

​

Agents

---
name: security-reviewer
description: Reviews code changes for security issues. Use after edits to authentication or input handling.
model: sonnet
---

You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

​

하위 폴더로 에이전트 정리하기

• Frontmatter name: 파일 이름만 대체하므로 agents/review/security.md의 name: audit는 my-plugin:review:audit로 로드됩니다
• 매니페스트 agents 필드: 여기에 나열한 파일은 하위 폴더 이름 없이 로드되므로 "agents": "./custom/review/security.md"는 my-plugin:security로 로드됩니다

​

플러그인 에이전트의 frontmatter 필드

• 지원되는 필드: name, description, model, effort, maxTurns, autoCompactWindow, tools, disallowedTools, skills, memory, background, omitClaudeMd, isolation, color, 그리고 experimental의 cacheTtl 키입니다. 유효한 isolation 값은 "worktree"뿐입니다. 각 필드의 역할은 지원되는 frontmatter 필드를 참조하십시오
• 무시되는 필드: permissionMode, hooks, mcpServers, initialPrompt입니다. 에이전트 파일은 자체적으로 훅이나 MCP 서버를 추가할 수 없으므로, 대신 플러그인 훅과 MCP 서버로 추가하십시오
• 파싱되지 않는 frontmatter: 에이전트는 모든 필드가 무시된 채로 로드됩니다. 이름은 파일 이름을 따르며, 설명은 Agent from my-plugin plugin으로 표시됩니다. 이러한 파일을 찾으려면 셸에서 claude plugin validate를 실행하십시오

​

Hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""
          }
        ]
      }
    ]
  }
}

​

플러그인 훅이 실행되는 시점

​

환경, 따옴표 처리 및 MCP 도구 매칭

• 환경: 모든 훅 프로세스는 환경 변수로 CLAUDE_PLUGIN_ROOT와 CLAUDE_PLUGIN_DATA를 받으며, 각 사용자 구성 값에 대해 CLAUDE_PLUGIN_OPTION_<KEY>도 받으므로 스크립트에서 이를 읽을 수 있습니다
• 따옴표 처리: command에 args가 없으면 셸을 통해 실행되므로, Hooks의 hooks/hooks.json 예시처럼 ${CLAUDE_PLUGIN_ROOT} 경로를 큰따옴표로 감싸 확장된 경로가 하나의 셸 단어로 유지되도록 하십시오. 대신 args를 전달하면 각 요소가 셸 없이 하나의 인수로 전달되므로 따옴표가 필요하지 않습니다. exec 형식과 셸 형식을 참조하십시오
• 플러그인 자체 MCP 도구 매칭: 이 플러그인이 선언한 MCP 서버의 도구 이름은 mcp__plugin_<plugin>_<server>__<tool>이므로, matcher에 이 전체 이름을 작성하십시오. 서버 이름만으로 된 matcher는 절대 실행되지 않습니다. MCP 도구 매칭을 참조하십시오

​

MCP servers

{
  "mcpServers": {
    "db": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

​

claude.ai 및 Cowork 사용자에게 제공하기

​

서버 이름, 도구 이름 및 다시 로드

• 서버 이름: plugin:<plugin>:<server> 형식이므로 my-plugin의 db 서버는 /mcp에서 plugin:my-plugin:db로 표시됩니다. mcp_tool 훅에서 서버를 지정할 때도 같은 형식을 사용합니다
• 도구 이름: mcp__plugin_<plugin>_<server>__<tool> 형식이므로 해당 db 서버의 query 도구는 mcp__plugin_my-plugin_db__query입니다. 권한 규칙과 훅 matcher에서는 이 이름을 사용합니다
• 치환: ${CLAUDE_PLUGIN_ROOT}와 기타 경로 변수는 command, args, env에서 치환됩니다. args에서는 각 요소가 하나의 인수로 전달되므로 따옴표가 필요하지 않습니다
• 다시 로드: 사용자가 /reload-plugins를 실행하고 다시 로드가 적용되면, 구성이 변경되지 않은 서버는 연결을 유지합니다. 구성이 변경된 서버는 다시 연결되고, 제거한 서버는 연결이 해제됩니다

​

패키징된 MCPB 서버 포함하기

{
  "name": "my-plugin",
  "mcpServers": "./servers/db.mcpb"
}

• /plugin에서: Installed 탭에서 플러그인을 선택하고 Configure를 선택합니다
• 설치 시 셸에서: claude plugin install에 --config <server>.<key>=<value>를 전달합니다. Claude Code v2.1.285 이상이 필요하며, 플러그인 내부에 패키징된 번들에서만 작동합니다.

​

LSP servers

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

• 바이너리 누락: Claude Code는 사용자의 PATH에서 이름으로 command를 시작합니다. 바이너리가 없으면 서버 시작에 실패하고 claude --debug가 LSP server <name> failed to start를 로그에 기록합니다
• 확장자 충돌: 활성화된 두 서버가 같은 확장자를 지정하면, 서버가 한 플러그인에서 왔든 두 플러그인에서 왔든 먼저 등록된 서버가 해당 파일을 처리하고 다른 서버는 해당 파일에 사용되지 않습니다. /plugin Errors 탭에 LSP server "<name>" is not used for <ext> files 경고가 표시됩니다

​

Executables

#!/bin/bash
echo "hello from my-plugin"

​

Default settings

{
  "agent": "security-reviewer"
}

• 매니페스트보다 파일 우선: 둘 다 존재하고 settings.json이 지원되는 키를 하나 이상 설정하면 settings.json이 적용되고 매니페스트의 settings는 무시됩니다
• 플러그인 기본값보다 사용자 설정 우선: 설정 소스 전체에서 플러그인 기본값이 가장 낮은 계층이므로, 사용자가 ~/.claude/settings.json에 설정한 agent가 플러그인의 값을 재정의합니다
• 두 플러그인이 같은 키를 설정하는 경우: 마지막으로 로드된 플러그인의 값이 적용되며, claude --debug가 overrides setting을 로그에 기록합니다

​

Themes and output styles

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555"
  }
}

​

Channels

{
  "name": "my-plugin",
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": { "BOT_TOKEN": "${user_config.bot_token}" }
    }
  },
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Telegram bot token",
          "sensitive": true
        }
      }
    }
  ]
}

​

Monitors

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

• 대화형 세션 전용: 플러그인 모니터는 대화형 세션에서 시작되며, -p 플래그를 사용하는 비대화형 모드에서는 절대 시작되지 않습니다. API 제공자 또는 텔레메트리 설정으로 인해 Monitor 도구를 사용할 수 없는 세션에서도 시작되지 않습니다
• 사용자 구성 사용 불가: command는 경로 변수와 환경의 ${ENV_VAR}를 받지만 ${user_config.*}는 절대 받지 않습니다. 이를 참조하는 모니터는 시작되지 않으며, 모니터 프로세스는 CLAUDE_PLUGIN_OPTION_<KEY>도 받지 않습니다
• 세션 중 비활성화: 세션 도중 플러그인을 비활성화해도 Claude Code는 이미 실행 중인 모니터를 중지하지 않습니다. 모니터는 세션이 종료될 때 중지됩니다

​

사용자에게 구성 값을 요청합니다

{
  "name": "my-plugin",
  "userConfig": {
    "api_url": {
      "type": "string",
      "title": "API URL",
      "description": "Base URL of your team's API"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token for your team's API",
      "sensitive": true
    }
  }
}

​

구성 대화 상자가 나타날 때

• /plugin에서 플러그인을 설치합니다
• 세션 내에서 /plugin install <plugin>@<marketplace>를 실행합니다
• /plugin의 Installed 탭에서 플러그인을 활성화합니다

​

플러그인 경로 참조 및 데이터 저장

• ${CLAUDE_PLUGIN_ROOT}: 플러그인의 설치 디렉토리. 각 버전은 자신의 캐시 디렉토리를 가지므로, 플러그인이 업데이트될 때 경로가 변경됩니다. 거기에 상태를 작성하지 마십시오
• ${CLAUDE_PLUGIN_DATA}: 업데이트를 생존하는 디렉토리, node_modules, 가상 환경, 캐시용. ~/.claude/plugins/data/<id>/로 해석되고 처음 참조될 때 생성됩니다
• ${CLAUDE_PROJECT_DIR}: 프로젝트 루트, hooks가 받는 동일한 값

​

데이터 디렉토리에 종속성 설치

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

​

다음 단계

• 플러그인 manifest 참조: plugin.json 필드, 경로 규칙, 표준 레이아웃
• evals로 플러그인 테스트: 추가한 컴포넌트가 Claude의 동작을 의도한 방식으로 변경하는지 확인합니다
• 플러그인 게시 및 배포: 플러그인을 버전 지정하고 마켓플레이스에 넣습니다
• 플러그인 문제 해결: 컴포넌트가 로드되지 않거나 hook이 발생하지 않을 때 수행할 작업