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

​

플러그인 디렉토리 탐색

• review skill과 about 명령
• security-review 서브에이전트
• Claude가 파일을 편집한 후 파일을 포맷하는 hook, 그리고 이를 호출하는 scripts/ 폴더
• 로그 모니터
• 출력 스타일과 색상 테마
• route-audit 워크플로우
• 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을 설정하면, 마지막 세그먼트를 대체하고 플러그인 접두사는 유지됩니다. skill이 명령 이름을 얻는 방법을 참조합니다
• 누가 호출하는가: Claude, 사용자, 또는 둘 다, frontmatter로 제어됩니다. skill 호출을 제어하는 사람을 참조합니다

• 추가 디렉토리: skills manifest 키에 나열합니다. 이들은 commands와 agents와 달리 기본 skills/ 스캔을 대체하지 않고 추가합니다
• 플러그인 루트의 단일 skill: skills/ 디렉토리가 없고 skills manifest 키가 없으면, 플러그인 루트의 SKILL.md는 하나의 skill로 로드됩니다. frontmatter에서 name을 설정합니다, 그렇지 않으면 마켓플레이스 설치가 플러그인 이름이 아닌 캐시 디렉토리 이름으로 skill을 이름 지정합니다

​

명령

​

manifest에서 명령 정의

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

​

agents의 서브폴더에서 agents 구성

• Frontmatter name: 파일 이름만 대체하므로, agents/review/security.md의 name: audit은 my-plugin:review:audit로 로드됩니다
• Manifest agents 필드: 거기에 나열한 파일은 서브폴더 이름 없이 로드되므로, "agents": "./custom/review/security.md"는 my-plugin:security로 로드됩니다

​

플러그인 agents의 Frontmatter 필드

• 지원되는 필드: name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, omitClaudeMd, isolation, color, 그리고 experimental의 cacheTtl 키. 유일한 유효한 isolation 값은 "worktree"입니다. 각각이 무엇을 하는지는 지원되는 frontmatter 필드를 참조합니다
• 무시되는 필드: permissionMode, hooks, mcpServers, initialPrompt. agent 파일은 자신의 hooks나 MCP 서버를 추가할 수 없으므로, 이들을 플러그인 hooks와 MCP 서버로 추가합니다
• 파싱되지 않는 Frontmatter: agent는 여전히 모든 필드가 무시된 상태로 로드됩니다. 파일 이름으로 이름 지정되고, 설명은 Agent from my-plugin plugin을 읽습니다. 셸에서 claude plugin validate를 실행하여 이러한 파일을 찾습니다

​

Hooks

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

​

플러그인 hooks가 발생할 때

​

환경, 인용, MCP 도구 일치

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

​

MCP 서버

{
  "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 hook에서 서버를 이름 지정할 때 동일한 형식을 사용합니다
• 도구 이름: mcp__plugin_<plugin>_<server>__<tool>, 따라서 해당 db 서버의 query 도구는 mcp__plugin_my-plugin_db__query입니다. 이것은 권한 규칙과 hook 매처에서 사용할 이름입니다
• 대체: ${CLAUDE_PLUGIN_ROOT}와 다른 경로 변수는 command, args, env에서 대체됩니다. args에서는 각 요소가 하나의 인수로 전달되므로 인용이 필요하지 않습니다
• 재로드: 사용자가 /reload-plugins를 실행하고 재로드가 적용되면, 구성이 변경되지 않은 서버는 연결을 유지합니다. 구성이 변경된 서버는 재연결되고, 제거한 서버는 연결을 끊습니다

​

패키지된 MCPB 서버 포함

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

​

LSP 서버

{
  "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를 표시합니다

​

실행 파일

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

​

기본 설정

{
  "agent": "security-reviewer"
}

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

​

테마 및 출력 스타일

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

​

채널

{
  "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
        }
      }
    }
  ]
}

​

모니터

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

• 대화형 세션만: 플러그인 모니터는 대화형 세션에서 시작되고 -p 플래그를 사용한 비대화형 모드에서는 시작되지 않습니다. 또한 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이 발생하지 않을 때 수행할 작업