Skip to main content
플러그인 매니페스트는 플러그인의 .claude-plugin/ 디렉토리에 있는 plugin.json 파일입니다. 플러그인의 메타데이터와 Claude Code가 사용자에게 요청하는 userConfig 값을 포함합니다. 또한 인라인으로 정의하거나 기본 위치 외부에 유지하는 모든 컴포넌트를 선언합니다. 이 참조는 플러그인 작성자와 플러그인 마켓플레이스 항목에 컴포넌트 필드를 추가하는 마켓플레이스 소유자를 위한 것입니다.
다음 경우는 다른 페이지에서 다룹니다:
찾고 있는 내용과 일치하는 섹션부터 시작하세요:
  • 필드: 필드 테이블에서 각 필드의 타입, 필수 여부, 기본값 및 허용되는 항목을 제공합니다. 경로 규칙은 모든 컴포넌트 경로에 대한 ./ 접두사 및 포함을 다룹니다
  • userConfig 옵션 또는 channels 항목: 사용자 구성 및 채널 스키마
  • ${CLAUDE_PLUGIN_ROOT} 또는 플러그인이 참조할 수 있는 다른 변수: 환경 변수
  • 각 컴포넌트의 파일이 위치하는 곳: 표준 레이아웃
  • claude plugin validate의 메시지: 문제 해결 페이지에서 각 메시지와 해결 방법, 이 페이지의 관련 섹션으로의 링크를 나열합니다

매니페스트 파일

매니페스트는 선택 사항입니다. 없으면 Claude Code는 표준 레이아웃에서 찾은 컴포넌트를 로드합니다. 그러면 플러그인 이름은 마켓플레이스 항목에서 오거나 --plugin-dir으로 플러그인을 로드할 때 디렉토리 이름에서 옵니다. 메타데이터, 기본 디렉토리 외부의 컴포넌트, userConfig 또는 인라인 컴포넌트 정의를 원할 때 매니페스트를 작성하세요. 매니페스트를 플러그인 루트 아래 .claude-plugin/plugin.json에 저장하세요. 다른 모든 플러그인 파일을 플러그인 루트에 배치하고 .claude-plugin/ 내부에는 배치하지 마세요. 여기에는 skills/, commands/ 및 hooks/가 포함됩니다. 다음 예제는 필드 테이블의 대부분의 키를 설정합니다. 각 참조된 경로를 포함하는 플러그인 디렉토리에서 유효성 검사를 통과합니다.

인식되지 않는 필드

인식되지 않는 최상위 키는 제거되고, userConfig 옵션, channels 항목, lspServers 구성 또는 monitors 항목 내의 인식되지 않는 키는 거부됩니다:
  • 최상위 필드: 필드가 제거되고 플러그인이 로드됩니다. claude plugin validate는 각 인식되지 않는 최상위 필드를 경고로 보고합니다
  • 엄격한 객체: userConfig 옵션, channels 항목, lspServers 구성 및 monitors 항목은 엄격합니다. 내부의 알 수 없는 키는 오류이며 플러그인이 로드되지 않습니다

매니페스트 유효성 검사

claude plugin validate는 매니페스트에 대한 권위 있는 검사입니다. 셸에서 플러그인 디렉토리에 대해 실행하세요:
명령은 다음 결과 중 하나를 보고합니다:
  • Validation passed: 매니페스트가 로드됩니다
  • Validation passed with warnings: 매니페스트가 로드되지만 유효성 검사기가 수정할 사항을 발견했습니다. 예를 들어 Claude Code가 제거하는 알 수 없는 최상위 필드, kebab-case가 아닌 name, 누락된 version, description 또는 author입니다. CI에서 경고를 실패로 바꾸려면 --strict를 전달하세요
  • Validation failed: 매니페스트에 타입 불일치, 누락되었거나 플러그인 루트를 벗어나는 경로, 또는 userConfig 옵션, channels 항목, lspServers 구성 또는 monitors 항목 내의 알 수 없는 키가 있습니다. Claude Code는 플러그인을 로드할 때 동일한 문제를 보고합니다

필드

테이블은 plugin.json의 최상위 키를 나열합니다. name은 유일한 필수 키입니다. 필드 이름이 링크인 경우 링크된 섹션에 전체 규칙이 있습니다. commands 및 hooks와 같은 컴포넌트 키의 경우 컴포넌트 경로 형식은 예제와 함께 허용되는 각 형식을 보여주며, 모든 경로는 ./ 접두사, 확장자 및 포함에 대한 경로 규칙을 따릅니다. Type 열에서 경로는 "./custom/commands"와 같이 플러그인 루트에 상대적인 문자열입니다.

name

플러그인 식별자. 공백, @, :, 경로 구분자, 제어 문자 또는 양방향 형식 문자가 없는 비어있지 않은 상태여야 합니다. kebab-case를 사용하세요. Claude Code는 모든 컴포넌트를 이 아래에 네임스페이스하므로 플러그인 deploy-tools의 에이전트 reviewer는 deploy-tools:reviewer로 나타납니다.

displayName

name 대신 UI에 표시되는 이름. 공백과 모든 대소문자를 포함할 수 있으며 네임스페이싱이나 조회에 사용되지 않습니다. 마켓플레이스에서 설치된 플러그인의 경우 마켓플레이스 항목의 displayName이 이 값보다 우선합니다.

version

semver에 대해 검사되지 않는 버전 문자열. 설정하면 변경할 때까지 플러그인을 해당 버전에 고정합니다. 버전 및 업데이트를 참조하세요. command 소스가 있는 플러그인, claude.ai에서 호스팅되는 마켓플레이스의 플러그인, 그리고 로컬 디렉토리로 추가된 마켓플레이스에서 제자리에 로드된 플러그인은 이 필드로 고정되지 않습니다.

metadata

카탈로그 또는 자격 필드와 같은 자신의 데이터를 위한 자유 형식 객체. Claude Code는 이를 읽지 않습니다. Claude Code v2.1.222 이상이 필요합니다.

defaultEnabled

사용자가 enabledPlugins에서 설정하지 않았을 때 플러그인이 활성화된 상태로 시작되는지 여부. 기본값은 true입니다. 활성화된 플러그인이 의존하는 플러그인은 관계없이 활성화된 상태로 시작됩니다. 마켓플레이스 항목의 동일한 필드가 이 필드를 재정의합니다. 사용자의 enabledPlugins 항목이 작성되면 플러그인 업데이트 전체에서 유지되므로 나중 릴리스에서 defaultEnabled를 변경해도 기존 사용자의 설정은 변경되지 않습니다.

dependencies

이 플러그인이 작동하기 위해 활성화되어야 하는 플러그인. 각 항목은 "name", "name@marketplace" 또는 { "name": "...", "marketplace": "...", "version": "..." }입니다. 베어 이름은 이 플러그인 자신의 마켓플레이스에 대해 해결됩니다. 의존성 제약을 참조하세요.

settings

플러그인이 활성화된 동안 Claude Code가 적용하는 설정. agent 및 subagentStatusLine만 적용됩니다. 다른 키는 로드 시 제거됩니다. 플러그인 루트의 settings.json이 이 키보다 우선합니다. 기본 설정을 참조하세요.

컴포넌트 경로 형식

모든 컴포넌트 키는 플러그인 루트에 상대적인 경로를 허용합니다. hooks, mcpServers, lspServers 및 experimental.monitors는 또한 인라인 구성을 허용하고, commands는 또한 객체 맵을 허용하며, mcpServers는 또한 MCP 번들 경로 및 URL을 허용합니다. 다음 예제는 허용되는 각 형식을 한 번씩 보여줍니다. 각 컴포넌트가 런타임에 수행하는 작업은 플러그인 컴포넌트를 참조하세요.

경로 전용 필드

agents, skills, outputStyles, workflows 및 experimental.themes는 하나의 경로 또는 경로 배열을 사용합니다. agents 항목은 .md 파일이어야 하고 skills 항목은 디렉토리여야 합니다. 다른 세 개는 디렉토리 또는 파일을 허용합니다.

commands

commands는 경로, 경로 배열 또는 객체 맵을 사용합니다. 경로는 평면 .md 명령 파일 또는 디렉토리를 지정합니다. 객체 맵에서 각 키는 플러그인 접두사 후 명령 이름이 됩니다. 예를 들어 플러그인 deploy-tools의 "about"은 /deploy-tools:about으로 실행됩니다. 각 값은 정확히 source 또는 content 중 하나를 설정하며, 둘 다 설정하거나 둘 다 설정하지 않는 항목은 유효성 검사에 실패합니다. 이 테이블의 다른 필드는 선택 사항입니다: 이 맵은 파일의 한 명령과 인라인 콘텐츠의 한 명령을 선언합니다:

hooks

hooks는 .json 파일 경로, settings.json의 hooks와 동일한 형식의 인라인 훅 객체, 또는 둘을 혼합하는 배열을 사용합니다. 훅 이벤트 및 핸들러 필드는 훅 참조를 참조하세요. Claude Code는 해당 파일이 존재할 때 hooks/hooks.json과 함께 선언한 모든 것을 병합합니다.

mcpServers

mcpServers는 .json 파일 경로, MCP 번들 경로 또는 URL, 인라인 맵, 또는 이들을 혼합하는 배열을 사용합니다. 서버 구성 필드는 플러그인 제공 MCP 서버를 참조하세요. Claude Code는 먼저 플러그인 루트의 .mcp.json을 로드한 다음 선언된 각 형식을 순서대로 로드합니다. 나중에 선언된 서버 이름은 이전 이름을 대체합니다. mcpServers 값은 다음 형식 중 하나를 사용합니다: 번들 경로 또는 URL은 .mcpb 또는 .dxt로 끝나야 합니다. 다른 확장자는 유효성 검사에 실패합니다.

lspServers

lspServers는 .json 파일 경로, 서버 이름을 구성에 매핑하는 인라인 맵, 또는 둘의 배열을 사용합니다. Claude Code는 먼저 플러그인 루트의 .lsp.json을 로드한 다음 선언된 각 구성을 순서대로 로드합니다. 나중에 선언된 서버 이름은 이전 이름을 대체합니다. 각 서버 구성은 다음 필드가 있는 엄격한 객체입니다. 알 수 없는 키는 유효성 검사에 실패합니다. 이 인라인 구성은 .go 파일에 대해 gopls를 실행합니다:
Anthropic이 플러그인으로 게시하는 언어 서버 및 서버가 런타임에 동작하는 방식은 코드 인텔리전스를 참조하세요.

monitors

experimental.monitors는 .json 파일 경로 또는 인라인 배열을 사용합니다. 키를 생략하면 Claude Code는 존재하는 경우 monitors/monitors.json을 로드합니다. 각 항목은 다음 필드가 있는 엄격한 객체입니다. 이 인라인 배열은 deploy 스킬이 처음 실행될 때 시작되는 하나의 모니터를 선언합니다:
모니터 command는 ${user_config.*}를 참조할 수 없습니다. 셸을 통해 실행되는 필드를 참조하세요.

경로 규칙

매니페스트의 모든 컴포넌트 경로는 플러그인 루트에 상대적이며 ./로 시작해야 합니다. commands/foo.md와 같은 경로는 유효성 검사에 실패합니다. skills 및 mcpServers는 각각 해당 규칙 외부의 한 형식을 허용합니다:
  • skills: 또한 "."를 허용합니다. "."와 "./"는 모두 플러그인 루트를 나타냅니다. v2.1.221 이전에는 "."가 매니페스트 유효성 검사에 실패했으므로 플러그인이 이전 버전에서 로드되어야 할 때 "./"를 사용하세요
  • mcpServers: 또한 https:// 번들 URL을 허용합니다

포함 및 존재

모든 컴포넌트 경로는 플러그인 루트 내부로 해결되어야 하며 존재해야 합니다. claude plugin validate는 outputStyles, lspServers, monitors 또는 themes 경로를 검사하지 않으므로 이러한 필드의 잘못된 경로는 플러그인이 로드될 때만 실패합니다:
  • 포함: 플러그인 루트 외부로 해결되는 경로는 로드되지 않으며 /plugin Errors 탭에 <component> path escapes plugin directory: <path>가 표시됩니다. ..를 포함하는 경로가 일반적인 경우이며 claude plugin validate는 이를 Path contains ".." which could be a path traversal attempt로 보고합니다
  • 존재: 존재하지 않는 경로는 로드되지 않으며 /plugin Errors 탭에 <component> path not found: <path>가 표시됩니다. claude plugin validate는 이를 Path not found로 보고합니다

각 키가 기본 위치와 결합되는 방식

각 컴포넌트 키는 기본 위치를 대체하거나, 추가하거나, 병합합니다:
  • 기본값 대체: commands, agents, outputStyles, workflows, experimental.themes, experimental.monitors. commands를 설정하면 기본 commands/ 디렉토리가 스캔되지 않습니다. 기본값을 유지하고 더 추가하려면 명시적으로 나열하세요: "commands": ["./commands/", "./extras/"]
  • 기본값에 추가: skills. skills/ 디렉토리는 여전히 스캔되며 나열된 디렉토리는 함께 로드됩니다
  • 병합: hooks, mcpServers, lspServers. 기본 파일이 먼저 로드되고 매니페스트가 선언한 것이 병합됩니다. 컴포넌트 경로 형식에서 설명한 대로
플러그인에 commands/와 같은 기본 폴더가 있고 이를 대체하는 매니페스트 키도 설정하면 Claude Code는 매니페스트 경로를 로드하고 폴더는 로드하지 않습니다. claude plugin list 및 /plugin 인터페이스는 경고 Default <folder>/ folder is ignored because the manifest sets "<key>"를 표시합니다. 경고를 피하려면 키를 해당 폴더 내의 경로로 설정하세요: "commands": ["./commands/deploy.md"]는 기본 폴더의 파일을 지정하고 경고를 생성하지 않습니다.

사용자 구성

userConfig는 플러그인이 활성화될 때 Claude Code가 사용자에게 요청하는 값을 선언하므로 사용자는 settings.json을 직접 편집하지 않습니다. 키는 문자, 숫자 및 밑줄로 만든 식별자이며 숫자로 시작할 수 없습니다. 각 값은 다음 필드가 있는 엄격한 객체입니다. 알 수 없는 키는 유효성 검사에 실패합니다. 각 활성화된 플러그인의 각 옵션은 /config 패널의 행으로도 나타나며, sensitive 옵션 및 multiple 목록은 제외됩니다. /config 행에는 Claude Code v2.1.269 이상이 필요합니다. 이 userConfig는 엔드포인트와 마스크된 토큰을 선언합니다:

필드를 고정 옵션으로 제한

userConfig 필드에 options를 설정하여 사용자가 고정 목록에서 값을 선택하도록 합니다. tone 필드를 세 가지 옵션으로 제한하려면 options에 나열하고 default를 그 중 하나로 설정하세요:
모든 필드에 options를 선언하면 Claude Code v2.1.271 이전 버전의 사용자는 플러그인을 로드할 수 없습니다. options는 multiple 또는 sensitive가 아닌 string 필드에 적용됩니다. default를 나열된 값 중 하나로 설정하거나 사용자가 하나를 선택하도록 required: true를 설정하세요. 각 옵션은 1~64자의 일반 레이블이며 셸에서 실행하는 claude plugin validate는 거부하는 다른 항목을 보고합니다. options가 이러한 규칙을 위반하는 플러그인은 로드되지 않습니다.

값이 저장되는 위치

민감하지 않은 값은 사용자의 settings.json의 pluginConfigs 아래에 저장됩니다. 민감한 값은 플랫폼의 보안 자격 증명 저장소로 이동합니다. 설정 페이지는 pluginConfigs가 읽혀지는 설정 파일을 나열합니다.

저장된 값 참조

플러그인이 필요한 곳에서 저장된 값을 참조하세요. 두 가지 형식 중 하나:
  • ${user_config.KEY}: MCP 서버 구성, LSP 서버 구성, exec-form 훅 args 및 스킬과 에이전트 콘텐츠에서 대체됩니다. 스킬과 에이전트 콘텐츠에서는 민감하지 않은 값만 대체되며 민감한 값은 자리 표시자가 됩니다
  • CLAUDE_PLUGIN_OPTION_<KEY>: 모든 옵션에 대해 훅 프로세스로 내보내집니다. <KEY>는 대문자입니다. 셸 형식 훅은 api_token에 대해 $CLAUDE_PLUGIN_OPTION_API_TOKEN을 읽습니다

셸을 통해 실행되는 필드

셸 형식 훅 명령, 모니터 명령 및 MCP headersHelper는 ${user_config.*}를 거부합니다. 이러한 필드 중 하나에서 이를 참조하는 컴포넌트는 실행되지 않고 오류로 실패합니다. 필드의 값이 대체된 값을 다시 구문 분석할 셸에 전달되기 때문입니다. 테이블은 값이 이러한 각 필드에 도달할 수 있는 방법을 보여줍니다.

채널

channels는 플러그인이 제공하는 메시지 채널(예: 채팅 앱으로의 브리지)을 선언합니다. 하나를 선언하면 Claude Code는 플러그인이 활성화될 때 채널의 구성을 요청할 수 있습니다. 서버가 메시지를 주입하는 방식은 채널 참조를 참조하세요. 각 항목은 플러그인의 MCP 서버 중 하나에 바인딩된 엄격한 객체이며 다음 필드가 있습니다: 이 매니페스트는 채널을 플러그인의 telegram MCP 서버에 바인딩하고 서버의 env로 대체되는 봇 토큰을 요청합니다:

환경 변수

Claude Code는 플러그인 컴포넌트에 세 가지 경로 변수를 제공합니다. 각 변수가 해결되는 위치에 나열된 필드에서 ${NAME}으로 참조하고 이를 받는 프로세스에서 환경 변수로 읽으세요. ${CLAUDE_PLUGIN_ROOT}는 플러그인이 업데이트될 때 변경되므로 상태를 거기에 쓰지 마세요. 루트가 이동하는 위치와 이전 디렉토리가 정리되는 시기는 로딩 페이지를 참조하세요. 마지막으로 플러그인을 설치한 곳에서 플러그인을 제거하면 --keep-data를 전달하지 않는 한 ${CLAUDE_PLUGIN_DATA} 디렉토리가 삭제됩니다.

각 변수가 해결되는 위치

각 플러그인 컴포넌트에서 ${...} 참조는 특정 필드에서 인라인으로 해결되며 일부 컴포넌트는 또한 프로세스 환경에서 변수를 받습니다: 변수는 Bash 도구를 통해 Claude가 실행하는 명령의 환경에 없으며, 주 세션이나 서브에이전트에도 없습니다. 스킬, 명령 및 에이전트 콘텐츠에서 Markdown 본문에 ${...} 참조를 작성하고 Claude Code는 콘텐츠를 로드할 때 경로를 인라인으로 대체합니다.

인용 및 경로 구분자

각 대체된 경로를 단일 인수로 유지하세요:
  • 훅 명령: exec form을 args와 함께 사용하여 각 경로가 인용 없이 하나의 인수가 되도록 합니다
  • 셸 형식 훅 및 모니터 명령: 변수를 큰따옴표로 감싸서 공백이 있는 경로가 한 단어로 유지되도록 합니다
이 셸 형식 훅은 플러그인과 함께 번들된 스크립트를 실행합니다:
Windows에서 대체된 경로는 앞으로 슬래시를 사용하므로 셸이 백슬래시를 이스케이프로 읽지 않습니다.

표준 레이아웃

각 컴포넌트 타입은 매니페스트가 다른 곳을 가리키지 않을 때 사용되는 플러그인 루트 아래의 기본 위치를 가집니다. 모든 기본 위치를 사용하는 플러그인과 훅이 호출하는 scripts/ 폴더는 다음과 같이 배치됩니다:
이 레이아웃을 클릭하고 각 파일이 수행하는 작업을 읽으려면 플러그인 탐색기를 열으세요. 플러그인 루트의 CLAUDE.md는 컨텍스트로 로드되지 않으며 claude plugin validate는 하나를 찾으면 경고합니다. Claude의 컨텍스트에 로드되는 지침을 포함하려면 스킬에 배치하세요.

마켓플레이스 항목 및 매니페스트

마켓플레이스 항목은 자신의 필드와 함께 이 페이지의 모든 필드를 허용합니다. strict 포함. strict 필드는 항목이 자신의 plugin.json을 가진 플러그인에 컴포넌트를 추가할 수 있는지 여부를 결정합니다. 기본값은 true입니다.

항목 필드가 plugin.json과 결합되는 방식

항목은 매니페스트로 제공되거나 컴포넌트를 추가하거나 충돌합니다:
  • plugin.json 없음: 항목은 strict에 관계없이 매니페스트입니다. 항목 hooks는 인라인 객체 형식으로만 로드됩니다. 파일 경로 또는 배열의 경우 /plugin Errors 탭에 not yet supported in a marketplace entry 오류가 표시됩니다
  • plugin.json 있음, strict 설정 안 됨 또는 true: Claude Code는 매니페스트를 로드하고 항목의 commands, agents, skills, outputStyles 및 themes를 추가합니다. hooks의 경우 항목의 이벤트 매처는 매니페스트의 동일한 이벤트 매처를 대체하고 매니페스트만 선언하는 이벤트는 자신의 것을 유지합니다
  • plugin.json 있음, strict: false: commands, agents, skills, hooks, outputStyles 또는 themes 중 하나를 선언하는 항목은 충돌이며 플러그인은 Plugin <name> has conflicting manifests로 로드되지 않습니다
source가 마켓플레이스 루트인 마켓플레이스 항목이 특정 skills 하위 디렉토리를 나열하면 해당 하위 디렉토리만 로드되고 플러그인의 기본 skills/ 디렉토리는 스캔되지 않습니다. 매니페스트의 skills 키는 대신 기본값에 추가합니다.

메타데이터 우선순위

일부 메타데이터 필드는 strict에 관계없이 고정 우선순위를 가집니다:
  • defaultEnabled 및 표시 필드: 항목의 defaultEnabled 및 표시 필드(displayName 등)는 매니페스트의 것을 재정의합니다
  • version: 매니페스트의 version은 항목의 것을 재정의합니다
  • name: 항목이 플러그인을 매니페스트와 다른 name으로 나열할 때 enabledPlugins는 항목 이름을 사용하고 컴포넌트는 매니페스트 이름 아래에 네임스페이스됩니다
전체 우선순위 테이블은 엄격한 모드를 참조하세요.

다음 단계