Claude Code 플러그인: 무엇을 묶어 오고, 설치 전에 무엇을 봐야 하나

스킬 하나와 훅 하나를 묶은 예제 플러그인을 설치하고 claude plugin details로 들여다봤습니다. 스킬은 이름까지 나오는데, 훅은 PostToolUse (harness-only — no model context cost) 한 줄이 전부더라고요.

무슨 명령을 실행하는지는 어디에도 없었습니다. 그건 플러그인 안의 hooks/hooks.json을 직접 열어야 보여요.

컨텍스트 비용이 0이라는 건 무해하다는 뜻이 아닙니다. 플러그인 설치는 스킬 하나를 받는 일이 아니라 스킬·에이전트·훅·MCP 서버를 한꺼번에 켜는 일이거든요. 그래서 저는 설치 전에 상세 창의 Will install 목록과 Context cost를 보고, 범위는 기본값인 user로 두고, 훅이 들어 있으면 hooks/hooks.json을 열어 무엇을 실행하는지 확인하길 권합니다.

2026년 9월 25일 Windows 11 · Claude Code 2.1.281 테스트 환경에서 직접 확인했고, 공식 문서는 같은 날과 9월 29일에 다시 확인했습니다. 남이 만든 플러그인을 설치하는 쪽만 다루고, 직접 만들어 배포하는 법은 다루지 않습니다.

설치 한 줄에 들어오는 것들

/plugin install 한 줄이면 설치가 끝나지만, 그 한 줄로 들어오는 것은 생각보다 많습니다. 플러그인은 스킬, 에이전트, 훅, MCP 서버, LSP 서버, 모니터를 담은 폴더이고, 출력 스타일·테마·워크플로 스크립트와 bin/ 실행 파일도 들어갈 수 있어요.

설치하는 쪽에서는 이걸 “비용인가, 권한인가”로 나눠 보면 판단이 쉽습니다. 모델이 읽는 것(스킬·에이전트)은 토큰 비용이고, 사용자 권한으로 실행되는 것(훅·MCP·LSP 서버·실행 파일)은 실행 권한입니다.

구성 요소	하는 일	볼 것
스킬(skills/, 옛 commands/)·에이전트(agents/)	설명이 매 세션 컨텍스트에 실림	늘 붙는 토큰 비용
훅(hooks/hooks.json)	이벤트마다 명령 실행	무슨 명령을 언제
MCP·LSP 서버(.mcp.json, .lsp.json)	별도 프로세스로 실행	어디에 접속하나
실행 파일(bin/)	켜져 있는 동안 Bash PATH에 추가	같은 이름 명령을 가리나

도입에서 본 harness-only — no model context cost 표시가 바로 이 표의 둘째 줄입니다. 훅은 토큰 비용이 0이어도 실행돼요.

그리고 플러그인 루트에 CLAUDE.md가 있어도 프로젝트 지시로 읽히지 않습니다. 플러그인에 지시를 담으려면 스킬로 써야 하고, claude plugin validate도 이 파일에 경고를 냅니다.

스킬 하나 쓰려는 거라면 그냥 ~/.claude/skills에 넣는 게 낫지 않느냐고 물을 수 있는데, 맞습니다. 나만 쓰는 스킬 하나라면 그게 더 가볍습니다.

플러그인은 여러 구성 요소를 한 이름으로 묶어 버전을 붙이고, 마켓플레이스로 배포하고, 범위를 골라 설치·제거하는 단위예요. 플러그인의 스킬은 /플러그인이름:스킬이름으로 부릅니다.

스킬 자체를 만드는 법은 SKILL.md로 반복 작업을 묶는 스킬 가이드에 있습니다.

마켓플레이스를 먼저 추가하고, 그다음 설치

마켓플레이스는 누군가 만들어 공유한 플러그인 목록입니다. 마켓플레이스를 추가하면 목록만 등록되고 아직 설치된 것은 없어요. 그다음 /plugin install 플러그인@마켓플레이스로 설치하는데, 세션 안에서는 바로 설치하지 않고 상세 창을 열어 내용을 보고 범위를 고르게 합니다.

마켓플레이스	추가 방법	성격
공식 claude-plugins-official	대화형 세션 첫 실행 때 자동	Anthropic·파트너·다른 작성자 플러그인
커뮤니티 claude-community	/plugin marketplace add anthropics/claude-plugins-community	작성자가 제출한 제3자 플러그인
데모 claude-code-plugins	/plugin marketplace add anthropics/claude-code	무엇을 담을 수 있는지 보여 주는 예제
그 밖의 출처	GitHub owner/repo, git URL, 로컬 경로, URL	Anthropic 검토 없음

커뮤니티 카탈로그는 거의 모든 항목을 특정 커밋에 고정해 두고, 고정된 항목은 다른 커밋을 설치하지 않습니다. 직접 추가하는 제3자 마켓플레이스는 커밋 고정 여부가 그 목록을 만든 사람에게 달려 있어요.

헷갈리기 쉬운 건 공식 마켓플레이스라고 다 Anthropic이 만든 건 아니라는 점입니다. 대부분은 파트너와 다른 작성자가 올린 것이고, Anthropic이 직접 관리하는 것은 commit-commands, code-review, feature-dev, 언어 서버(LSP) 플러그인 같은 일부입니다.

마켓플레이스 이름이 알려 주는 건 목록을 누가 펴내는지이지, 그 안의 플러그인이 무엇을 하는지가 아니에요.

그래서 저는 공식 마켓플레이스도 출발점일 뿐이라고 봅니다. 훅과 서버가 들어 있다면 무엇을 실행하는지 직접 확인하세요.

LSP 플러그인은 어떤 명령으로 언어 서버를 띄울지만 담고 있어서, pyright-langserver나 typescript-language-server 같은 실행 파일은 따로 설치해야 합니다.

설치 전에 볼 것

1. Will install로 무엇이 들어오는지

/plugin의 Discover 탭에서 플러그인을 고르면 상세 창이 뜨고, Will install 목록에 더해지는 명령·에이전트·스킬·훅·MCP·LSP 서버가 나옵니다. 훅이나 MCP 서버가 있으면 플러그인 저장소에서 무엇을 실행하는지 확인하세요.

이 목록에 구성 요소가 제대로 안 나오는 경우도 있습니다.

Anthropic이 구성 요소 정보를 갖고 있지 않으면 마켓플레이스 항목이 선언한 내용만 보이거나, Components will be discovered at installation(마켓플레이스 안의 플러그인) 또는 Component summary not available for remote plugin(다른 곳에서 받아 오는 플러그인)만 보입니다.

그때는 플러그인 저장소를 받아 claude --plugin-dir <플러그인 폴더> plugin details <플러그인 이름>으로 설치 전에 보거나, 설치 뒤 claude plugin details로 봅니다.

Windows 11 · Claude Code 2.1.296의 Discover 탭에서 frontend-design을 열어 보니 실제로 그랬습니다. Will install에는 Component summary not available for remote plugin 한 줄뿐이었어요. 아래 2번의 Context cost는 Discover에서 연 창이라 원래 나오지 않습니다.

대신 Installs exactly commit f359d43, the commit the Anthropic Directory lists처럼 설치할 커밋이 적혀 있었습니다. 이런 플러그인은 설치 전에 View repository로 그 저장소의 hooks/와 .mcp.json부터 열어 보세요.

2. Context cost로 늘 붙는 비용

공식 마켓플레이스 플러그인은 상세 창에 Context cost가 보입니다. 매 메시지에 붙는 Every turn과 스킬·에이전트가 불렸을 때 붙는 When invoked 두 값이에요. Discover 목록에서 연 창에는 나오지 않고, /plugin install 플러그인@마켓플레이스로 열거나 Marketplaces 탭에서 열어야 보입니다.

설치 뒤 claude plugin details에서는 Always-on(쓰지 않아도 매 세션 붙는 비용)과 On-invoke(불렸을 때 비용)로 나뉩니다. 플러그인을 여럿 깔면 Always-on이 쌓여, 쓰지 않는 플러그인이 컨텍스트를 조금씩 차지하게 되죠. 컨텍스트가 차면 생기는 일은 컨텍스트 관리 글에 있습니다.

3. 범위

claude plugin install을 옵션 없이 실행하면 user 범위입니다.

범위	기록되는 파일	적용 대상
user	~/.claude/settings.json	나, 모든 프로젝트
project	.claude/settings.json	저장소를 받는 모두
local	.claude/settings.local.json	나, 이 저장소만
managed	관리형 설정	읽기 전용

project 범위는 공유 파일에 기록돼 다른 사람의 세션에도 영향을 줍니다. 다만 커밋한 .claude/settings.json은 팀원에게 플러그인을 켜 줄 뿐 내려받아 주지는 않아요. 마켓플레이스 안에 상대 경로로 든 플러그인 같은 예외가 아니라면, 설치되지 않은 기기에서는 /plugin의 Errors 탭에 안내가 뜨고 팀원 각자가 claude plugin install <이름>@<마켓플레이스> --scope project를 한 번 실행해야 합니다.

팀 전체에 같은 플러그인을 쓰게 하고 싶다면, 저장소의 .claude/settings.json에 extraKnownMarketplaces로 마켓플레이스를 등록하고 플러그인을 project 범위로 설치하세요.

팀원이 그 폴더를 신뢰하면 마켓플레이스가 등록되지만, 이때도 플러그인 설치는 팀원 각자가 위 명령을 한 번 실행해야 합니다. 같은 키가 여러 파일에 있을 때 무엇이 이기는지는 설정 파일 네 개와 우선순위에 있습니다.

4. 나중에 누가 내용을 바꿀 수 있는지

이 항목은 플러그인 보안 문서의 첫 문장으로 충분합니다. “A Claude Code plugin you install can execute arbitrary code on your machine with your user privileges.” 설치 전 상세 창에도 어느 마켓플레이스든 같은 경고가 뜨고, Anthropic은 플러그인 안의 MCP 서버·파일·소프트웨어를 통제하지 않으며 의도대로 동작할지, 나중에 바뀌지 않을지도 검증할 수 없습니다.

설치는 한 번이지만 내용은 업데이트로 바뀝니다. 자동 업데이트가 켜진 마켓플레이스라면 검토한 파일이 디스크에서 바뀔 수 있어요.

마켓플레이스	자동 업데이트 기본값
claude-plugins-official, 다른 공식 이름, claude.ai에서 추가한 것	켜짐
knowledge-work-plugins, first-party-plugins	꺼짐
커뮤니티·제3자·로컬 개발 마켓플레이스	꺼짐

자동 업데이트는 대화형 세션에서 첫 메시지를 보낸 뒤 최대 10분 사이 무작위 시점에 돌고, 끝나면 /reload-plugins로 반영하라는 알림이 뜹니다. 다시 불러오지 않아도 다음 실행 때는 새 버전이 로드돼요. 설치할 때 본 내용과 나중에 실행되는 내용이 다를 수 있으니, 업데이트 뒤에도 claude plugin details로 다시 보세요.

빈 설정 폴더에서 설치부터 제거까지 해 본 기록

처음 보는 플러그인은 빈 설정 폴더에서 먼저 시험해 볼 수 있습니다. CLAUDE_CONFIG_DIR을 바꾸면 설정·세션 기록·플러그인이 모두 그 폴더에 저장되기 때문이에요.

스킬 하나(summarize-diff)와 편집 후 echo edited를 실행하는 훅 하나를 묶은 예제 플러그인 tidy-notes와 이를 담은 로컬 마켓플레이스 demo-market으로 직접 실행했습니다. 명령은 Git Bash 기준이고, PowerShell이라면 첫 줄을 $env:CLAUDE_CONFIG_DIR = "$PWD\cfg"로 바꾸면 됩니다.

1. 형식 검사

export CLAUDE_CONFIG_DIR="$PWD/cfg"
claude plugin validate ./demo-market/plugins/tidy-notes

  ❯ author: No author information provided. Consider adding author details for plugin attribution

✔ Validation passed with warnings

종료 코드는 0이었습니다. validate는 형식과 스키마만 보므로, 통과했다고 훅이 안전하다는 뜻은 아닙니다.

2. 마켓플레이스 추가와 설치

claude plugin marketplace add ./demo-market
claude plugin install tidy-notes@demo-market

Adding marketplace…✔ Successfully added marketplace: demo-market (declared in user settings)
Installing plugin "tidy-notes@demo-market"...✔ Successfully installed plugin: tidy-notes@demo-market (scope: user)

설치 전에 claude plugin details tidy-notes@demo-market를 실행하면 Plugin "tidy-notes@demo-market" not found.가 나옵니다. 셸의 details는 이미 설치한 플러그인만 대상으로 하니, 설치 전 미리보기는 /plugin 상세 창이나 --plugin-dir로 하세요.

3. 설치 뒤 구성 요소 확인

claude plugin details tidy-notes@demo-market

Component inventory
  Skills (1)  summarize-diff
  Agents (0)
  Hooks (1)  PostToolUse  (harness-only — no model context cost)
  …
Projected token cost
  Always-on:   ~14 tok   added to every session

도입에서 말한 화면입니다. 훅은 PostToolUse라는 이벤트 이름으로만 표시되고, 무슨 명령을 실행하는지는 나오지 않습니다.

4. project 범위로 한 번 더 설치하고 지우기

같은 플러그인을 빈 프로젝트 폴더에서 --scope project로 설치하자 .claude/settings.json에 이 내용이 생겼고, claude plugin list에는 같은 플러그인이 Scope: user와 Scope: project로 따로 두 번 나왔습니다.

{
  "enabledPlugins": {
    "tidy-notes@demo-market": true
  }
}

한 범위에서 지워도 다른 범위의 설치는 남더라고요. project 범위를 지우자 파일에는 "enabledPlugins": {}만 남았고, user 범위까지 지우자 No plugins installed.가 나왔습니다.

지운 뒤에도 plugins/cache/demo-market/tidy-notes/0.1.0/ 아래 파일은 남아 있었고 .orphaned_at 파일이 새로 생겼습니다. 업데이트나 제거로 이전 버전이 된 폴더는 이렇게 표시만 해 두었다가 약 14일 뒤 백그라운드에서 지웁니다. 그 청소는 플러그인이 하나라도 설치돼 있을 때만 돌아서, 마지막 플러그인을 지우면 다시 설치할 때까지 남아요.

설치한 뒤: 끄기, 지우기, 안 쓰는 것 정리

/plugin의 Installed 탭이나 셸의 claude plugin disable·enable·uninstall을 씁니다. 끄기는 설치를 남긴 채 동작만 멈추고, 제거는 설치를 없앱니다. 프로젝트 공유 설정이 켜 둔 플러그인을 지우려 하면, 나만 끌지(.claude/settings.local.json에 기록) 모두에게서 지울지 묻습니다.

직접 설치했는데 최소 2주, 최소 10개 세션 동안 안 쓴 마켓플레이스 플러그인은 Not used recently 아래에 모입니다. 테마·출력 스타일처럼 호출 없이 동작하는 것은 여기에 올라가지 않아요.

바꾼 내용은 /reload-plugins로 지금 세션에 반영합니다. 메뉴를 닫을 때 자동으로 돌지만, 다시 불러오면 프롬프트 캐시가 무효화될 수 있어 경고만 하고 미루기도 합니다.

MCP 서버가 든 플러그인은 도구 검색으로 지연되지 않는 한 캐시를 무효화해, 다음 요청이 대화 전체를 다시 읽습니다. 비용 영향은 프롬프트 캐싱이 비용을 줄이는 조건에 있습니다.

주의: 마켓플레이스를 지우면 거기서 설치한 플러그인이 모두 제거되고 설정 파일의 enabledPlugins 항목도 지워집니다. Marketplaces 탭은 확인을 묻기 전에 지워질 플러그인을 보여 줍니다.

막혔을 때

Marketplace "claude-plugins-official" not found

공식 마켓플레이스는 대화형 세션을 처음 시작할 때 자동으로 추가되는데, 정책이 막았거나 CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL이 설정됐거나 이전 시도가 실패해 재시도를 기다리는 중이면 추가되지 않습니다. 셸의 claude plugin 명령은 이 등록을 해 주지 않아요.

빈 설정 폴더로 셸 명령만 쓴 위 시험에서도 claude plugin marketplace list의 첫 출력은 No marketplaces configured였습니다. /plugin marketplace add anthropics/claude-plugins-official로 직접 추가하고 다시 설치하세요.

Executable not found in $PATH

LSP 플러그인은 언어 서버 설정만 담고 실행 파일은 설치해 주지 않습니다. 그 플러그인에 필요한 실행 파일을 설치하고 PATH에 있는지 확인하세요. 큰 프로젝트에서 rust-analyzer나 pyright가 메모리를 많이 쓰면 플러그인을 끄고 기본 검색 도구를 쓰는 편이 낫습니다.

설치했는데 플러그인 스킬이 안 보일 때

셸에서 claude plugin install로 설치하면 이미 열린 세션에는 반영되지 않고, 다음 시작이나 /reload-plugins 때 로드됩니다. 먼저 /reload-plugins를 실행해 보세요.

그래도 안 보이면 캐시 문제일 수 있으니, 캐시를 지우고 다시 시작한 뒤 재설치합니다. macOS·Linux는 rm -rf ~/.claude/plugins/cache, PowerShell은 Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\plugins\cache"입니다.

/plugin을 모르는 명령이라고 할 때

버전이 오래됐거나 터미널 CLI가 아닌 환경입니다. claude --version으로 확인하고 업데이트한 뒤 터미널을 다시 여세요. 데스크톱 앱이나 VS Code 확장이라면 각 앱의 플러그인 관리 화면을 씁니다.

다른 사람들이 겪은 문제

설치한 뒤 내용이 바뀌는 문제는 공개 이슈에서도 반복해서 나옵니다. 아래는 공개된 GitHub 이슈에서 확인한 내용입니다.

• glen-84(2026-07-03, #73914): 마켓플레이스가 갱신되면 훅·MCP 서버 정의·bin/ 실행 파일도 처음 설치할 때의 동의만으로 로드되고, 다시 묻거나 바뀐 내용을 보여 주는 단계가 없다고 지적했습니다. 보고자 환경(VS Code 확장 2.1.199, Ubuntu)에서는 공식 플러그인의 커밋이 버전 번호는 그대로인 채 앞으로 나갔다고 합니다. 기능 요청으로 열려 있습니다.
• RubenARNAUD(2026-09-15, #94516): Claude Code 2.1.236 · Windows 11에서 마켓플레이스 새로 고침이 네트워크 문제로 실패했는데 claude plugin update가 종료 코드 0으로 already at the latest version을 출력했다고 보고했습니다. 복제본이 기본 브랜치가 아닌 곳에 있으면 푸시한 적 없는 로컬 커밋이 설치 내용에 섞였다는 재현도 적었습니다.
• sumitjfra-art(2026-09-15, #94525): Windows에서 공식 security-guidance 플러그인을 enabledPlugins: {}로 껐는데도 훅이 계속 돌며 오류를 냈다고 보고했습니다. 보고자는 다른 세션 폴더에 남은 훅 설정이 따로 로드되기 때문이라고 분석하고 hooks.json을 직접 비우는 우회를 적었습니다. 확인한 페이지에는 공식 답변이 없습니다.

세 건을 겹쳐 보면, 설치할 때 확인한 것과 지금 실행되는 것이 같다는 보장이 사용자 쪽에 없습니다. 업데이트 알림이 뜬 뒤나 동작이 이상할 때 claude plugin details와 hooks/hooks.json을 다시 여는 습관이 필요해요. 에이전트가 무엇을 실행할 수 있는지라는 같은 질문은 프롬프트 인젝션 방어 글에서도 다뤘습니다.

마치며

직접 설치해 보니 claude plugin details는 훅이 있다는 것까지만 알려 주고, 무엇을 실행하는지는 알려 주지 않았습니다. 플러그인에서 제일 신경 써야 할 게 바로 그 부분인데 말이죠. 그래서 저는 플러그인을 “설치할 때 한 번 보는 것”이 아니라 “업데이트될 때마다 다시 보는 것”으로 다루길 권합니다.

손대기 좋은 출발점은 claude plugin list로 설치된 플러그인을 보고, 훅이 든 것마다 hooks/hooks.json을 한 번 열어 보는 것입니다. 플러그인이 MCP 서버를 들여온다면 그 서버가 어떤 범위로 등록되는지는 MCP 서버 연결: stdio·HTTP 설정과 범위 우선순위에서 이어서 볼 수 있습니다.