플러그인 로딩 레퍼런스

기준일: 2026-10-23
공식 기준: Plugin loading reference

개요

플러그인이 로드되지 않았거나, 예상과 다른 사본이 로드됐거나, 업데이트가 반영되지 않았을 때 어느 소스·settings scope·디스크 파일이 그렇게 결정했는지 추적하기 위한 페이지입니다. 세션이 시작될 때와 /reload-plugins를 실행할 때마다 Claude Code가 적용하는 규칙을 줍니다. Claude에게 이 페이지를 읽고 내 설정을 진단하게 할 수도 있습니다.

• 설치·활성화·비활성화·업데이트 단계: Install and manage plugins
• 특정 오류 메시지: 플러그인 문제 해결

증상별 바로가기: 끈 플러그인이 여전히 로드됨은 활성화된 곳 찾기, 업데이트가 아무것도 안 바꿈은 버전과 업데이트, ~/.claude/plugins/ 파일은 디스크의 플러그인 찾기, --plugin-dir 플러그인이 안 로드되거나 같은 이름의 다른 것이 로드됨은 이름 충돌, ~/.claude/skills/나 .claude/skills/의 플러그인이 오류 없이 로드되지 않음은 managed settings에 막힌 skills-directory 플러그인.

핵심 개념

개념	설명
세 단계	Declared(settings) → Fetched(~/.claude/plugins/ 디스크) → Loaded(실행 중 세션)
플러그인 id	<name>@<origin>. origin은 <marketplace>, inline, skills-dir, synced
enabledPlugins 소스 6개	낮은 우선순위부터 --add-dir, user, project, local, flag, managed
in-place / copied	일부는 제자리 로드, 나머지는 캐시 cache/<marketplace>/<plugin>/<version>/로 복사
계산된 버전	업데이트 감지 기준. 캐시 디렉터리 이름이기도 함
이름 충돌 순위	managed > --plugin-dir 등 > 설치 마켓 플러그인 > skills-dir > synced

상세

플러그인이 도달한 단계 확인

enabledPlugins 항목은 단계를 거쳐 쓸 수 있는 플러그인이 됩니다: settings가 선언하고, Claude Code가 디스크로 가져오고, 실행 중 세션이 로드합니다. 플러그인이 settings 파일이 시사하는 대로 동작하지 않으면 어느 단계에 도달했는지 확인하세요.

• Declared, in settings: enabledPlugins는 켜야 할 플러그인, extraKnownMarketplaces는 있어야 할 마켓을 말함. claude plugin marketplace add를 실행하면 Claude Code가 디스크뿐 아니라 사용자 settings의 extraKnownMarketplaces에도 마켓을 씀
• Fetched, on disk under ~/.claude/plugins/: Claude Code가 가져온 것의 기록과 파일
  • known_marketplaces.json: 가져온 각 마켓의 source, installLocation, lastUpdated, autoUpdate. 사용자당 하나라 한 프로젝트에서 추가한 마켓은 모든 프로젝트에서 사용 가능
  • installed_plugins.json: 각 설치의 scope, installPath, version
  • cache/: 플러그인 파일
• Loaded, in the running session: 시작 때나 마지막 /reload-plugins에서 Claude Code가 로드한 플러그인 집합. settings나 디스크 변경은 /reload-plugins를 실행하거나 새 세션을 시작하기 전에는 이 layer에 닿지 않음. 그래서 claude plugin update가 Restart to apply changes.로 끝나고 백그라운드 업데이트가 Run /reload-plugins to apply로 알림

세션 시작 시 디스크에 없는 플러그인과 마켓

플러그인은 세션 시작 시 네트워크 없이 installed_plugins.json과 캐시에서 로드됩니다. 세션이 시작된 뒤 Claude Code가 선언된 마켓을 백그라운드로 확인합니다.

• settings가 선언했지만 known_marketplaces.json에 없는 마켓: clone한 뒤 플러그인을 리로드하고 아직 캐시되지 않은 활성 플러그인을 다운로드
• settings에서 소스가 바뀐 선언된 마켓: 새 소스에서 다시 가져오고 Plugins changed. Run /reload-plugins to activate.를 표시

두 경로 어디도 가져오지 않았고 쓸 수 있는 캐시 디렉터리도 없는 활성 플러그인은 /plugin Errors 탭에 Plugin "<name>" not cached at <path>를 표시하고 claude plugin list는 같은 줄에 — run /plugin to refresh를 더합니다. 해결은 Plugin "<name>" not cached at <path>.

플러그인이 온 곳 찾기

모든 플러그인은 <name>@<origin> 형태의 id를 가지며 settings 파일과 claude plugin list --json에 보입니다. @ 뒤가 Claude Code가 플러그인을 찾은 곳입니다.

id 끝	플러그인이 온 방법	켜고 끄는 방법
@<marketplace>	추가한 마켓에서 설치	settings 파일 enabledPlugins 아래 "<name>@<marketplace>": true 또는 false
@inline	--plugin-dir/--plugin-url로 시작했거나, CLAUDE_CODE_PLUGIN_DIRS를 설정했거나, Agent SDK 앱이 plugins 옵션을 전달. 그 세션에서만 로드	매니페스트가 defaultEnabled: false를 설정하거나 settings 파일이 "<name>@inline": false를 설정하지 않는 한 세션 동안 켜짐
@skills-dir	.claude-plugin/plugin.json이 있는 플러그인 디렉터리를 ~/.claude/skills/ 또는 프로젝트 .claude/skills/에 저장	settings 파일이 "<name>@skills-dir"을 true/false로 설정하지 않는 한 매니페스트의 defaultEnabled
@synced	본인 또는 조직이 claude.ai 계정에 켰고 Claude Code가 다운로드	매니페스트가 defaultEnabled: false이거나 settings 파일이 "<name>@synced": false가 아니면 켜짐. 조직이 필수로 표시한 플러그인은 무관하게 로드

마켓 플러그인의 <name>은 marketplace.json의 항목 이름이고, @inline과 @skills-dir은 플러그인 매니페스트의 name입니다. 이 표의 origin 이름은 예약되어 어떤 마켓도 inline, skills-dir, synced로 명명할 수 없습니다.

항목 이름과 매니페스트 이름

마켓 플러그인은 서로 다를 수 있는 두 이름을 가집니다.

• marketplace.json의 항목 이름: 설치·활성화 키. enabledPlugins에 쓰는 것, 캐시 디렉터리 이름의 기준, claude plugin list가 보여 주는 것
• 매니페스트의 name: 플러그인 구성요소의 네임스페이스, 그리고 이름 충돌이 비교하는 것

저장소로 공유하는 플러그인

저장소로 플러그인을 공유하려면 .claude/settings.json의 enabledPlugins에 나열하거나 .claude/skills/ 아래에 둡니다. Claude Code는 프로젝트의 .claude/plugins/ 디렉터리를 스캔하지 않습니다. cloud 세션은 워크스페이스 신뢰 대화상자가 필요한데 cloud 세션은 이를 표시하지 않으므로 저장소가 extraKnownMarketplaces에 나열한 마켓을 추가하지 않습니다.

저장소 플러그인의 신뢰 검사와 구성요소 제한

project scope 플러그인은 저장소에 체크인되어 clone하는 모든 협업자에게 닿습니다. 그 내용은 내가 아닌 저장소에서 오므로 .claude/settings.json의 프로젝트 allow 규칙에 적용되는 것과 같은 신뢰 검사 뒤에만 로드됩니다. 상위 폴더를 신뢰하거나 -p로 실행하는 것으로는 충분하지 않습니다. 코드를 실행하는 구성요소는 더 제한됩니다.

• 선언한 MCP 서버는 프로젝트 .mcp.json과 같은 서버별 승인을 거침
• MCP bundle(.mcpb 또는 .dxt 파일)이나 플러그인 디렉터리 밖 파일로 선언한 MCP 서버는 건너뜀. 인라인이나 플러그인 디렉터리 안 .mcp.json에 선언
• 백그라운드 monitor는 로드되지 않음

신뢰 검사도 이 구성요소 제한도 본인 ~/.claude/skills/의 플러그인에는 적용되지 않습니다. --plugin-dir과 skills-directory 플러그인 작성법은 Create plugins.

저장소 플러그인이 로드되지 않은 이유 확인

저장소 .claude/skills/의 플러그인이 로드되지 않으면:

• 하위 디렉터리에 있음: 저장소 루트의 플러그인은 로드되지 않음. Claude Code는 세션의 primary working directory의 .claude/skills/를 읽고 일반 skill·command와 달리 플러그인은 상위 디렉터리를 검색하지 않음. 저장소 루트에서 시작하거나 v2.1.246 이상에서 /cd로 세션을 옮김
• 데스크톱 앱, worktree에서: worktree가 아니라 main checkout의 .claude/skills/에서 로드됨. What worktrees share with the main checkout
• 신뢰하지 않은 폴더: 그 폴더의 워크스페이스 신뢰 대화상자를 수락한 뒤에만 로드
• Claude Code를 관리하는 조직: managed settings에 막힌 skills-directory 플러그인

managed settings에 막힌 skills-directory 플러그인

~/.claude/skills/나 프로젝트 .claude/skills/의 플러그인 폴더가 오류 없이 로드되지 않았다면 관리자가 managed settings로 막았을 수 있습니다. 이 폴더는 마켓이 아니라 본인이나 저장소에서 오므로 관리자가 다음 제한 중 하나를 설정하면 Claude Code가 건너뜁니다.

• customization을 플러그인으로 잠금: strictPluginOnlyCustomization이 true 또는 잠글 customization 종류를 하나 이상 명시한 배열. mcp 같은 어느 한 종류가 잠기면 구성요소와 무관하게 플러그인 전체를 건너뜀
• 마켓 소스 제한: { "source": "skills-dir" } 항목이 없는 strictKnownMarketplaces allowlist, 또는 그것이 있는 blockedMarketplaces 목록

건너뛴 폴더는 /plugin과 claude plugin list에 플러그인도 오류도 보이지 않습니다. /<name>:<skill> command와 agent, hook, MCP 서버가 없습니다. skill이 잠긴 종류가 아니라면 폴더 루트의 SKILL.md는 일반 skill로 계속 로드되어 /<name>이 동작하고 /plugin Installed 탭이 Skills 아래 그 skill을 나열합니다.

• 원인 확인: 세션에서 /status. Setting sources 줄에 Enterprise managed settings가 있으면 이 설정 중 해당되는 것이 있는지 관리자에게 문의. 없으면 저장소 플러그인이 로드되지 않은 이유의 다른 원인
• 플러그인 전체 로드: 조직이 허용하는 마켓에 추가해 거기서 설치. 한 세션만이면 셸에서 --plugin-dir과 폴더 경로로 claude를 시작 (관리자가 그 플래그도 끄지 않은 경우)

claude.ai에서 sync된 플러그인

claude.ai 계정에 켠 플러그인은 마켓에서 설치한 플러그인과 함께 Claude Code에서도 로드됩니다. 조직이 구성원에게 켠 것도 포함합니다. 이런 플러그인은 마켓도 설치 기록도 없이 <name>@synced로 로드됩니다. 터미널 세션에서는 sync된 플러그인의 skill, agent, hook, MCP 서버, LSP 서버가 모두 설치한 마켓 플러그인과 같은 신뢰로 로드됩니다. Cowork가 로드하는 구성요소는 claude.com의 component support table. sync된 플러그인은 Cowork 세션과 claude.ai 계정으로 로그인한 터미널 세션에서 로드됩니다.

• Cowork: 세션 시작 때 Claude Code가 세션 자체 환경으로 다운로드
• 터미널 세션: Claude Code를 시작할 때마다 백그라운드로 한 번 sync하여 새·업데이트된 플러그인을 내려받고 본인이나 조직이 끈 것을 제거. 터미널 sync는 Claude Code v2.1.273 이상 필요

cloud Cowork 세션의 sync 시점

클라우드에서 도는 Cowork 세션 중 claude.ai 계정에서 플러그인을 켜거나 끄면 그 세션에서 계속 작업하세요. 몇 메시지 뒤에도 바뀐 것이 없으면 새 세션을 시작하세요.

터미널 세션의 sync 시점

터미널 sync는 백그라운드로 돌아 세션이 시작된 뒤 끝날 수 있습니다. 인터랙티브 세션에서 sync된 플러그인을 추가·업데이트·제거하면 Plugins changed. Run /reload-plugins to activate.가 보입니다. /reload-plugins로 그 세션에 반영하거나 다음 시작 때까지 둡니다. 터미널 세션 중 claude.ai 계정에서 플러그인을 켜거나 끄면 Claude Code를 다음에 시작할 때 다운로드하거나 제거합니다.

터미널 sync의 로그인 요건

터미널에서는 claude.ai 계정으로 로그인한 세션에서만 플러그인이 sync됩니다. /login으로 로그인한 뒤에도 다음 터미널 세션에서는 sync된 플러그인을 내려받지도 로드하지도 않습니다.

• ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, 또는 apiKeyHelper 스크립트가 그 로그인 대신 자격 증명을 공급하는 세션
• Anthropic에서 feature flag를 가져오지 않는 세션 (예: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC를 설정)
• bare mode 세션 또는 --safe-mode로 시작한 세션
• user를 뺀 --setting-sources 목록으로 시작한 세션

이전 버전 Claude Code에서 로그인했다면 Claude Code가 백그라운드로 갱신하기 전까지 그 로그인은 플러그인을 덮지 않습니다. 더 빨리 접근하려면 /login을 다시 실행하세요. 플러그인 sync는 다음에 Claude Code를 시작할 때 시작됩니다.

로드할 sync된 플러그인 제어

조직이 필수로 지정한 플러그인을 제외하고 sync된 플러그인을 하나씩 끄거나 기기의 sync된 플러그인을 모두 끌 수 있습니다.

• 플러그인 하나: 셸의 claude plugin disable <name>@synced와 세션의 /plugin Installed 탭이 모두 사용자 수준 enabledPlugins에 "<name>@synced": false를 저장. 모든 환경에서 프로젝트에 두지 않으려면 프로젝트의 커밋된 .claude/settings.json에 같은 키를 설정
• 기기의 모든 sync된 플러그인: 사용자 settings에서 syncClaudeAiPlugins를 false로, 또는 조직이 managed settings에서 설정. Claude Code가 다운로드를 멈추고 다음 시작 때 이미 sync한 플러그인을 ~/.claude/plugins/.trash/로 옮겨 더는 로드하지 않음. 조직이 claude.ai에서 Skills를 끄면 플러그인 sync도 중단
• 조직이 필수로 지정한 플러그인: claude.ai에서 필수로 표시된 플러그인은 이전에 비활성했어도 로드. claude plugin disable이 Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.로 거부하고 claude plugin list가 required by your org로 표시

claude.ai에서 플러그인 제거는 Manage installed plugins.

플러그인이 활성화된 곳 찾기

enabledPlugins 항목은 여섯 소스 어디에서나 설정할 수 있습니다. 낮은 우선순위부터 각 소스가 누구에게 적용되는지 나열합니다. settings 파일은 Settings files and who they affect.

소스	설정하는 곳	적용 대상
--add-dir	--add-dir로 전달한 디렉터리의 .claude/settings.json 또는 .claude/settings.local.json	이 세션만. true 값만 효과가 있고 다른 모든 소스가 덮어씀
user	~/.claude/settings.json	모든 프로젝트의 본인
project	.claude/settings.json	저장소를 clone하는 모든 사람
local	.claude/settings.local.json	이 저장소의 본인만
flag	시작 시 전달한 --settings 값	이 세션만
managed	Managed settings	정책이 덮는 모든 사용자. true는 강제 활성화, false는 차단이며 다른 소스가 덮어쓰지 못함

소스는 키 단위로 병합됩니다. 각 플러그인 id에 적용되는 값은 그 id를 언급한 가장 높은 우선순위 소스의 값입니다. 언급하지 않은 소스는 낮은 우선순위 소스의 값을 그대로 둡니다.

user settings에서 비활성했지만 여전히 로드

~/.claude/settings.json에서 플러그인을 false로 했는데 여전히 로드되면 더 높은 우선순위 소스의 true가 덮어쓰고 있습니다. claude plugin list와 /plugin의 행이 Disabled in ~/.claude/settings.json but still loads — project settings enable it, which overrides your user setting을 표시합니다. 메시지는 덮어쓴 소스를 명시합니다: project, .claude/settings.local.json은 project, gitignored, cli flag, managed. 프로젝트가 켠 플러그인을 내 기기에서 끄려면 프로젝트 파일보다 우선순위가 높은 .claude/settings.local.json에서 id를 false로 설정하세요.

project settings에서 활성이지만 설치되지 않음

플러그인의 유일한 true가 프로젝트 .claude/settings.json에 있으면, 마켓 항목이 상대 경로 소스를 쓰거나 seed 디렉터리가 이미 갖고 있지 않은 한 Claude Code는 설치되지 않은 기기에 그것을 가져오지 않습니다. 대신 /plugin Errors 탭이 Plugin "<name>" is enabled in project settings but isn't installed here를 보여 줍니다. 상대 경로 플러그인은 마켓 자체에서 로드되므로 설치 기록이 필요 없습니다. 외부 소스 플러그인은 다음 소스 중 하나가 true로 설정할 때만 가져옵니다.

• 사용자 settings
• git이 추적하지 않는 .claude/settings.local.json
• --settings 플래그
• Managed settings

디스크의 플러그인 찾기

Claude Code는 플러그인 파일과 상태 기록을 하나의 plugins root에 둡니다. CLAUDE_CODE_PLUGIN_CACHE_DIR을 설정하지 않으면 ~/.claude/plugins입니다. 표의 모든 경로는 이 root 기준 상대 경로입니다.

경로	담는 것
cache/<marketplace>/<plugin>/<version>/	마켓 플러그인의 설치된 버전마다 디렉터리 하나. <plugin>은 마켓 항목 이름, <version>은 해석된 버전. ${CLAUDE_PLUGIN_ROOT}가 이 디렉터리를 가리킴
data/<plugin-id>/	${CLAUDE_PLUGIN_DATA}로 노출되는 플러그인의 영구 디렉터리. <plugin-id> 형성은 Path variables and persistent data. 구성요소가 처음 쓸 때 생성되고 업데이트 사이 유지됨. 기본적으로 마지막 scope에서 제거하면 삭제. --keep-data와 남는 다른 경우는 plugin uninstall
marketplaces/<name>/	GitHub, 다른 Git 호스트, URL에서 추가한 마켓의 clone/다운로드. 로컬 file/directory 소스로 추가한 마켓은 여기 사본이 없고 known_marketplaces.json의 installLocation이 준 경로
synced/	claude.ai 계정에서 sync한 플러그인
.trash/	claude.ai sync가 제거한 플러그인 (claude.ai에서 끄거나 sync를 멈춘 경우 등)
installed_plugins.json, known_marketplaces.json	설치한 것과 가져온 마켓의 기록 (도달한 단계 확인). claude.ai에서 호스팅되는 마켓은 대신 known_marketplaces_claudeai.json에 기록
flagged-plugins.json	마켓이 delist해서 Claude Code가 제거한 플러그인. /plugin의 Flagged 섹션에 나타남. Host a marketplace
installed_plugins.set-aside.<date>.<hash>.json, installed_plugins.unreadable.<date>.<hash>.kept	어느 버전도 쓸 수 없는 설치 기록을 버리거나 읽을 수 없는 installed_plugins.json을 재구성하기 전 Claude Code가 보관하는 날짜별 사본. 복구 노트. cleanupPeriodDays 일정으로 사라짐

${CLAUDE_PLUGIN_ROOT}가 버전 디렉터리를 가리키므로 플러그인의 root 경로는 버전마다 바뀝니다. 지속되는 파일은 ${CLAUDE_PLUGIN_DATA}에 두세요.

In-place와 copied 플러그인

Claude Code는 origin에 따라 일부 플러그인은 보관된 곳에서 제자리 로드하고 나머지는 캐시로 복사합니다.

• --plugin-dir과 skills-directory 플러그인: 디렉터리가 제자리에서 로드되며 복사되지 않음. --plugin-url 아카이브나 --plugin-dir의 .zip은 먼저 세션 임시 디렉터리로 추출
• 로컬 경로로 추가한 마켓의 상대 경로 플러그인: 마켓 폴더 안 경로에서 제자리 로드. 소스 디렉터리 편집이 다음 세션 시작이나 /reload-plugins에 반영되며 버전을 올릴 필요 없음. 플러그인의 hook 프로세스와 MCP·LSP 서버는 소스 디렉터리를 가리키는 CLAUDE_PLUGIN_ROOT를 받음. Node.js 패키지 의존성은 의존성 설치가 실행되는 때
• link mode의 command 소스 플러그인: 명령이 출력한 디렉터리가 캐시 항목의 링크를 통해 제자리 로드
• 그 외 모든 마켓 플러그인: 설치 때 cache/<marketplace>/<plugin>/<version>/로 복사하고 그 사본을 로드. 플러그인 디렉터리 밖 파일은 복사되지 않아, 복사된 플러그인 안 스크립트가 ../shared 같은 플러그인 루트 위 경로를 읽으면 찾지 못함

플러그인 디렉터리를 벗어나는 경로

제자리든 캐시 사본이든 Claude Code는 플러그인이 자기 디렉터리 밖의 구성요소를 선언하지 못하게 합니다. plugin.json이나 마켓 항목에 선언한 구성요소 경로가 플러그인 루트 밖으로 해석되면 거부합니다.

• 쓴 그대로 플러그인 밖을 가리키는 경로: ../shared-utils 등
• 플러그인 밖으로 이어지는 symlink: 한 마켓 안 플러그인 간 링크는 제외
• macOS와 Linux에서 어디에든 백슬래시가 든 경로: 플러그인 안에 머물러도 거부. 백슬래시 경로로 선언한 구성요소는 Windows에서만 로드되므로 ./commands/deploy.md처럼 슬래시로 쓰세요

거부된 경로는 path escapes plugin directory 오류로 나타나고 플러그인은 그 구성요소 없이 로드됩니다.

이전 버전 정리

플러그인을 업데이트하거나 제거하면 Claude Code가 이전 버전 디렉터리에 .orphaned_at 마커를 쓰고 14일 뒤 백그라운드 정리로 그 디렉터리를 제거합니다. 이미 옛 버전을 로드한 세션이 계속 동작하게 하기 위함입니다. 정리는 installed_plugins.json이 설치를 하나 이상 기록하는 동안만 돕니다. 마지막 플러그인을 제거하면 다른 플러그인을 설치할 때까지 고아 디렉터리가 남습니다.

Node.js 패키지 의존성

Claude Code가 플러그인을 캐시로 복사할 때 플러그인의 Node.js 패키지 의존성도 거기 설치하므로 hook과 MCP 서버가 로드할 수 있습니다. 이 절은 플러그인이 자체 package.json에 선언한 npm·Bun 패키지를 다룹니다. 다른 플러그인에 의존하는 경우는 플러그인 의존성 버전 제약.

의존성 설치가 실행되는 때

Claude Code는 복사된 버전 디렉터리를 만들 때마다 거기에 의존성을 설치합니다.

• 플러그인을 설치할 때
• Claude Code가 플러그인을 새 버전으로 업데이트할 때
• 새 기기처럼 활성 플러그인이 아직 캐시되지 않은 세션 시작 때

로컬 경로로 추가한 마켓에서 제자리 로드되는 상대 경로 플러그인은 소스 디렉터리에 의존성을 설치하지 않습니다. 직접 거기에 설치하거나 hook에서 ${CLAUDE_PLUGIN_DATA}에 설치하세요. 설치는 플러그인 루트 디렉터리에 package.json과 지원되는 lockfile이 모두 있을 때만 실행됩니다. lockfile이 실행할 패키지 관리자를 정합니다.

Lockfile	패키지 관리자
bun.lock	Bun
npm-shrinkwrap.json 또는 package-lock.json	npm

lockfile이 둘 이상이면 bun.lock, npm-shrinkwrap.json, package-lock.json 순으로 첫 일치를 씁니다. 설치를 건너뛰는 lockfile 경우:

• bun.lockb: Bun의 바이너리 lockfile은 검사할 수 없음. 텍스트 bun.lock이나 npm lockfile을 배포
• yarn.lock 또는 pnpm-lock.yaml: npm lockfile로 교체
• Claude Code가 읽지 않는 형식의 lockfile: npm lockfile은 npm 7 이상이 쓰는 lockfileVersion 2 또는 3, bun.lock은 lockfileVersion 2 이하 필요

가장 많은 사용자에게 닿으려면 npm lockfile을 포함하세요. Claude Code는 일치한 lockfile의 패키지 관리자를 사용자 PATH에서 실행하며 그것이 없다고 다른 lockfile을 대신 시도하지 않습니다. npm 소스로 배포하는 플러그인은 npm이 게시 패키지에서 package-lock.json을 제외하므로 npm-shrinkwrap.json을 쓰세요.

의존성 설치의 제한

플러그인이나 패키지의 코드가 설치 중 실행되지 않도록 이 의존성 설치를 제약하고 실행 시간을 제한합니다.

• registry 패키지만: 모든 의존성이 lockfile에 정확한 버전으로 고정된 registry 패키지여야 함. git, GitHub, folder, workspace, linked 의존성이 있는 플러그인은 설치되지 않음
• https 다운로드: lockfile의 다운로드 링크는 설치하는 사용자 자신의 기본 npm registry를 가리키지 않는 한 https여야 함
• 별도 설치 폴더: 패키지 관리자가 검사한 의존성 목록 사본만 든 자체 폴더에서 실행되어 npm과 Bun이 플러그인의 .npmrc, .env, bunfig.toml을 읽지 않음. 설치가 성공하면 결과 node_modules를 플러그인으로 옮김
• 고정된 해석: lockfile이 고정한 버전을 그대로 쓰고, package.json과 lockfile이 같은 의존성을 나열하지 않으면 설치를 건너뜀
• lifecycle script 없음: --ignore-scripts로 preinstall, install, postinstall script가 실행되지 않으므로, 그 script에서 네이티브 모듈을 빌드하는 의존성은 다운로드만 되고 이 설치 중 컴파일되지 않음
• override·patch 없음: package.json이 npm overrides를 설정한 플러그인은 npm lockfile로 설치되지 않고, Bun patchedDependencies를 설정한 플러그인은 bun.lock으로 설치되지 않음
• 60초 타임아웃: 더 오래 걸리는 설치를 중단하고 실패로 취급

Claude Code는 이 의존성 설치 전에 npm 소스 플러그인을 가져오며 가져오는 중 패키지 자체의 설치 script는 실행되지 않습니다 (npm plugin source). 자동 설치는 끌 수 없으며 이를 비활성화하는 설정이나 환경 변수가 없습니다. 제한된 네트워크에서 허용할 호스트는 network access requirements.

의존성 설치가 실패하거나 건너뛰어질 때

설치가 실패하거나 건너뛰어져도 플러그인은 로드되지만 없는 패키지가 필요한 부분은 동작하지 않을 수 있습니다. 캐시 사본에 lockfile과 런타임 의존성을 나열한 package.json이 있는데 node_modules가 없는 활성 플러그인에 /plugin과 claude plugin list가 노트를 표시하며, 설치가 끝나지 않았는지 이 플러그인에는 실행할 수 없는지 알려 줍니다. 각각의 조치는 해당 트러블슈팅 항목. 자동 설치가 의존성을 제공할 수 없으면 hook에서 영구 데이터 디렉터리에 설치하세요. lifecycle script로 빌드해야 하는 패키지, Python 의존성, Yarn이나 pnpm으로 lock된 플러그인, git 의존성 같은 registry 패키지가 아닌 의존성이 해당합니다.

버전과 업데이트

플러그인 작성자가 새 commit을 push했는데 claude plugin update가 <name> is already at the latest version (<version>).를 출력하면, Claude Code가 계산한 플러그인 버전이 그대로이므로 디스크의 플러그인 파일이 바뀌지 않습니다. Claude Code는 설치하는 모든 플러그인의 버전을 계산하며 이 버전이 업데이트를 감지하는 기준입니다. claude plugin update와 백그라운드 auto-update는 버전을 다시 계산하고 installed_plugins.json에 기록된 것과 같으면 캐시 사본을 교체하지 않습니다. 내가 시작한 업데이트는 그 사본에서 끝나지 않은 의존성 설치를 재시도할 수 있습니다. 버전은 플러그인의 캐시 디렉터리 이름도 정합니다. "version"을 고정한 매니페스트는 commit이 바뀌어도 계산된 버전이 같게 유지되는 한 방법입니다. 해석 순서는 Claude Code가 버전을 계산하는 법. 로컬 경로로 추가한 마켓에서 제자리 로드되는 플러그인은 버전 문자열과 무관하게 매 세션 시작 때 현재 소스 파일을 로드합니다. claude.ai에서 호스팅되는 마켓의 플러그인은 claude.ai가 기록한 버전이 버전이며 매니페스트의 version은 읽지 않습니다.

Claude Code가 버전을 계산하는 법

소스로 추가한 마켓에서는 플러그인 마켓 항목의 source 타입에 따라 규칙을 고릅니다 (marketplace reference의 소스 타입). command를 제외한 모든 소스 타입:

1. 플러그인 매니페스트의 version 필드가 먼저
2. 그다음 플러그인 마켓 항목의 version 필드
3. 둘 다 없으면 소스 타입에서 버전 결정:

소스 타입	version 필드가 없을 때의 버전
github, url, git-subdir	소스 commit SHA를 12자로 줄인 것. git-subdir 버전은 하위 디렉터리 경로의 hash도 포함
archive	SHA-256 digest를 12자로 줄인 것: 마켓 항목의 sha256 고정, 고정이 없으면 내려받은 파일의 digest
Git 호스팅 마켓 안의 상대 경로	설치된 디렉터리의 commit SHA
플러그인 디렉터리도 마켓도 git 저장소가 아닌 로컬 디렉터리	unknown
npm	unknown

Claude Code는 설치 경로를 둘러싼 저장소(예: git으로 관리되는 ~/.claude)에서 버전을 가져오지 않습니다. command 소스는 항상 명령이 만든 것에서 버전을 도출합니다: hash 12자만, 또는 매니페스트가 설정했으면 <manifest version>-<hash>. 마켓 항목의 version은 command 소스에서 무시됩니다. hash가 덮는 범위는 Copy mode and link mode. 매니페스트가 먼저이므로 "version": "1.0.0"을 고정한 매니페스트는 작성자가 문자열을 바꾸기 전까지 commit을 몇 번 push해도 모든 사용자를 캐시 사본에 유지합니다. 사용자가 commit을 따라가게 하려면 매니페스트와 항목 모두에서 version을 빼세요. 어떤 선택이 어떤 릴리스 구성에 맞는지는 Host a marketplace.

설치 전 마켓을 새로고침하는 때

플러그인을 설치할 때 Claude Code는 마켓 카탈로그의 로컬 사본에서 조회합니다. 세션의 /plugin install이나 셸의 claude plugin install 모두, 마켓 이름을 붙이든 안 붙이든 해당합니다.

플러그인 이름	명령	Claude Code가 새로고침하는 것
name@marketplace	/plugin install 또는 claude plugin install	조회 전에 지정한 마켓
name만	/plugin install	auto-update가 켜진 마켓만, 조회가 빗나간 뒤에
name만	claude plugin install	없음. 새로고침 없이 캐시된 카탈로그를 읽음

name@marketplace 설치 전 새로고침은 마켓의 auto-update 설정이나 DISABLE_AUTOUPDATER와 무관합니다. 새로고침이 실패하면 설치는 캐시된 카탈로그로 진행되고 claude plugin install이 marketplace not refreshed를 보고합니다. name@marketplace 설치 전 새로고침을 건너뛰는 경우:

• 마켓이 로컬 file 또는 directory 소스로 추가됐거나 settings 소스로 settings에 인라인 정의됨
• seed 디렉터리가 마켓을 제공
• 최근 30초 안에 Claude Code가 마켓을 새로고침함
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC를 설정
• Managed settings가 마켓을 차단 (이 경우 Claude Code는 설치도 거부)

auto-update가 실행되는 때

인터랙티브 세션에서 첫 메시지를 보낸 뒤 Claude Code는 최대 10분의 임의 지연을 기다립니다. 그다음 auto-update가 켜진 모든 마켓을 새로고침하고 거기서 설치한 플러그인을 디스크에서 업데이트합니다. 실행 중 세션은 로드한 버전을 유지하고 Plugin updated: <name> · Run /reload-plugins to apply가 보입니다. 리로드 여부와 무관하게 새 버전은 다음 시작 때 로드됩니다.

어떤 마켓과 플러그인이 auto-update 되나

마켓의 auto-update 여부는 다음 중 먼저 설정된 것을 따릅니다.

1. settings 파일의 extraKnownMarketplaces 항목의 autoUpdate
2. known_marketplaces.json 항목의 autoUpdate: /plugin Marketplaces의 Enable auto-update 토글이 씀. settings 파일이 extraKnownMarketplaces에도 마켓을 선언했으면 토글이 그 settings 항목에도 autoUpdate를 씀
3. 기본값: claude-plugins-official 같은 Anthropic 공식 마켓은 켜짐, knowledge-work-plugins와 first-party-plugins는 꺼짐, claude.ai에서 추가한 마켓은 켜짐, 그 외 모든 마켓은 꺼짐

DISABLE_UPDATES=1, DISABLE_AUTOUPDATER=1, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1을 설정하면 전체 pass가 꺼지고 FORCE_AUTOUPDATE_PLUGINS=1도 설정하지 않는 한 Enable auto-update 토글이 숨겨집니다. 각 변수의 더 넓은 효과는 environment variables reference. auto-update는 마켓 항목이 headersHelper를 선언한 플러그인도 건너뜁니다. 그런 플러그인이 /plugin Errors 탭에 나타나는 때와 거기서 업데이트하는 법은 Installs and updates that refuse a command instead of asking. 복사된 플러그인이 세션 중 업데이트되면 hook 명령, monitor, MCP 서버, LSP 서버는 이전 버전 경로를 계속 씁니다. /reload-plugins로 hook, MCP 서버, LSP 서버를 새 경로로 전환합니다. monitor는 세션 재시작이 필요합니다.

command 소스가 다시 실행되는 때

command 소스 플러그인은 auto-update pass를 기다리지 않습니다. 출력된 디렉터리는 명령이 실행된 시점의 도구 상태를 반영하므로, Claude Code는 수락한 명령을 다음 시점에 다시 실행합니다.

• 플러그인을 설치하거나 업데이트할 때마다
• 활성화된 command 소스 플러그인마다 세션 시작 직후 백그라운드로 세션당 한 번. 이 실행은 마켓의 auto-update 설정이나 DISABLE_AUTOUPDATER와 무관
• 활성 플러그인의 설치된 버전이 플러그인 캐시에 없을 때 시작 시 또는 /reload-plugins 때

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC를 설정하면 두 백그라운드 실행을 건너뜁니다. 명시적 설치와 업데이트는 그 변수가 있어도 명령을 실행합니다. 명령의 hash된 출력이 바뀌면 결과를 새 버전으로 설치해 실행 중인 인터랙티브 세션에서 /reload-plugins가 전환하는 것과 같은 구성요소를 전환하며 리로드됐다는 알림이 보입니다. 제자리 리로드가 세션의 프롬프트 캐시를 무효화한다면 Claude Code는 대신 /reload-plugins를 실행하라는 프롬프트를 보이는데, 이는 캐시 비용을 경고하고 --force로 다시 실행하면 적용합니다.

이름 충돌

다른 origin의 활성 플러그인이 매니페스트 이름을 공유하면 다음 순서로 로드될 것이 정해집니다 (높은 우선순위부터).

1. managed settings enabledPlugins에 true 또는 false로 id가 나온 플러그인. 매니페스트 이름이 id의 name 부분과 같은 --plugin-dir 사본은 로드되지 않고 --plugin-dir copy of "<name>" ignored: plugin is locked by managed settings가 보임
2. 활성화된 --plugin-dir, --plugin-url, CLAUDE_CODE_PLUGIN_DIRS 플러그인. 같은 이름의 설치된 마켓 플러그인이나 skills-directory 플러그인을 대체:
   • 설치된 마켓 플러그인: 조용히 대체. claude plugin list는 그 행이 settings를 반영하므로 마켓 행을 여전히 활성으로 표시. --debug로 시작할 때 ~/.claude/debug/ 아래 로그에만 Plugin "<name>" from --plugin-dir overrides installed version 기록
   • skills-directory 플러그인: Not loaded — the name "<name>" is already taken by a session-only plugin (--plugin-dir / --plugin-url), which takes precedence라는 /plugin Errors 탭 행과 함께 대체
3. 설치된 마켓 플러그인. 같은 이름의 skills-directory 플러그인은 설치된 플러그인을 명시한 같은 Not loaded 행을 받음
4. skills-directory 플러그인. 둘 사이에서는 ~/.claude/skills/의 사본이 로드되고 프로젝트 .claude/skills/ 사본은 어느 경로가 가렸는지 말하는 행과 함께 버려짐
5. claude.ai에서 sync된 플러그인. 다른 origin의 활성 플러그인이 이름과 맞으면 Claude Code는 그 플러그인을 로드하고 sync된 사본을 로드되지 않음으로 보고. claude.ai 사본을 쓰려면 내 사본을 비활성화

순서는 매니페스트 이름을 비교하므로 매니페스트가 "name": "hello-plugin"이라고도 하는 --plugin-dir 플러그인 hello-plugin은 hello@example-marketplace를 대체합니다.

같은 이름의 활성 플러그인 둘일 때의 hook

서로 다른 마켓에서 같은 매니페스트 이름의 플러그인 둘을 설치·활성화하면 둘 다 /plugin에서 활성으로 보이지만 그중 하나의 hook은 빠집니다. 이름마다 한 플러그인이 hooks/hooks.json의 hook을 등록하고, 이름마다 한 플러그인이 hooks module을 로드합니다. 조직의 managed settings가 사본 하나를 켜면 그 사본이 이름을 차지합니다. 아니면 Claude Code가 먼저 로드하는 사본이 차지합니다. 어느 사본이 이름을 차지하는지는 세션에서 /plugin의 Errors 탭을 엽니다. hook이 빠진 사본에 대한 노트가 이름을 차지한 사본을 명시하며 빠진 사본의 상세에도 같은 노트가 있습니다. hooks/hooks.json hook이면 노트가 Its hooks.json hooks do not run으로, hooks module이면 Its hooks module does not load로 시작합니다. 이 노트는 Claude Code v2.1.296 이상이 필요합니다. 빠진 사본의 hook을 대신 실행하려면 이름을 차지한 사본을 비활성화하거나 제거하고 세션에서 /reload-plugins를 실행하세요. 리로드가 남은 사본의 hook을 등록하고 노트를 지웁니다. 이름을 차지한 사본이 managed settings가 켠 것이면 비활성화할 수 없으며 둘이 설치된 동안 다른 사본의 hook은 꺼진 채로 남습니다.

세션 전용 플러그인이 로드되지 않게 하기

--plugin-dir 플러그인이 아무것도 가리지 않게 하거나 부모 프로세스가 플래그를 대신 전달할 때 끄려면 아무 settings 파일에서 그 id를 false로 설정하세요. 매니페스트 이름이 hello-plugin인 플러그인은 "enabledPlugins": {"hello-plugin@inline": false}입니다. 비활성화된 세션 전용 플러그인은 가리지 않으므로 마켓이나 skills-directory 사본이 대신 로드됩니다.

체크리스트

• 플러그인이 Declared / Fetched / Loaded 중 어느 단계에 있는지 확인 (/reload-plugins)
• id의 @ 뒤 origin과 enabledPlugins 소스 6개 중 어느 것이 덮는지 확인
• 업데이트가 안 되면 매니페스트 version 고정 여부 확인
• 캐시 사본 안에서 플러그인 밖 경로를 참조하지 않음
• 의존성은 npm lockfile (package-lock.json / npm-shrinkwrap.json), registry 패키지, lifecycle script 없이
• 이름 충돌은 managed > --plugin-dir > 마켓 > skills-dir > synced 순서로 확인

함께 보기

• Install and manage plugins
• 플러그인 문제 해결
• Plugin commands reference
• Manage plugins for your organization

기준일

• 문서 작성·동기화 기준일: 2026-10-23 (v2.1.309 반영)
• 원문: https://code.claude.com/docs/en/plugins/loading