Claude Code 플러그인 개념 및 비용 상세 정리

Claude Code 플러그인이란 무엇인가

Claude Code 플러그인은 Claude Code가 하나의 단위로 로드하고 관리하는 구성 요소들의 디렉터리입니다. 이러한 구성 요소에는 스킬, 에이전트, 훅, MCP 서버, LSP 서버, 백그라운드 모니터가 포함됩니다. 플러그인을 설치하면 모든 구성 요소가 한 번에 하나의 이름으로 추가되며, 비활성화하면 동일한 방식으로 모두 제거됩니다.

플러그인은 에이전트에게 기존에 없던 새로운 능력을 부여하지 않습니다. 플러그인 내부의 모든 요소는 사용자가 직접 .claude/ 디렉터리에 작성할 수 있는 것들입니다. 플러그인은 패키징 계층으로서, 이러한 요소들의 버전을 관리하고, 여러 사람에게 배포하며, 파일을 일일이 복사하도록 요청할 필요 없이 나중에 업데이트할 수 있는 수단입니다. 이것이 핵심 개념이며, 플러그인에 대한 대부분의 혼란은 이를 새로운 종류의 기능으로 오해하는 데서 비롯됩니다.

.claude-plugin/plugin.json에 위치한 선택적 매니페스트는 플러그인의 이름을 지정하며, 이 이름은 네임스페이스가 됩니다. commit-commands이라는 플러그인 내의 스킬은 /commit-commands:commit로 호출되므로, 두 플러그인이 각각 commit라는 이름의 스킬을 제공하더라도 서로 충돌하지 않습니다. 플러그인 에이전트 또한 @-mention 목록에서 plugin-name:agent-name과 같이 동일한 방식으로 범위가 지정됩니다.

플러그인, 스킬, MCP 서버, 규칙 파일

이 네 가지 용어는 마치 서로 경쟁하는 것처럼 사용되곤 합니다. 하지만 실제로는 그렇지 않으며, 그 경계를 한 번 명확히 정의할 필요가 있습니다.

• 스킬은 작업이 요구될 때 Claude가 불러오는 단일 명령 단위입니다. 에이전트 스킬의 실제 정의를 참조하십시오.
• MCP 서버는 프로토콜을 통해 에이전트에 도구를 노출하는 별도의 프로세스로, 주로 사용자가 직접 실행하는 네트워크 서비스입니다.
• CLAUDE.md과 같은 규칙 파일은 세션 시작 시 읽히며 모든 항목에 적용되는 프로젝트 컨텍스트입니다.
• 플러그인은 스킬, 에이전트, 훅, MCP 서버 정의를 하나로 묶고, 여기에 버전 번호와 배포 채널을 포함할 수 있는 컨테이너입니다.

따라서 플러그인이 답하는 질문은 "에이전트가 무엇을 할 수 있는가"가 아닙니다. 그 질문은 "어떻게 팀에 배포하고 다음 달에 업데이트할 것인가"입니다. 앞의 세 가지 중 무엇을 선택할지 고민 중이라면 스킬, MCP 서버, 규칙 파일 비교에서 해당 결정 사항을 자세히 다룹니다. MCP 부분에 관심이 있다면 VPS에서 직접 MCP 서버 실행하기에서 호스팅 측면을 다룹니다.

플러그인의 저장 위치와 내부 구조

마켓플레이스에서 설치한 플러그인은 복제된 원본 경로에서 직접 실행되지 않고 ~/.claude/plugins/cache의 로컬 캐시로 복사됩니다. 설치된 각 버전은 고유한 디렉터리를 가집니다. 업데이트하거나 제거할 때 이전 버전의 디렉터리는 고아(orphaned) 상태로 표시되었다가 약 2주 뒤에 삭제됩니다. 따라서 이미 이전 버전을 불러온 세션은 작업 도중 실패하지 않고 계속 정상적으로 작동합니다.

업데이트할 때마다 경로가 변경되므로 플러그인은 자신의 위치를 절대 경로로 하드코딩해서는 안 됩니다. 플러그인 내부의 훅(hook)과 MCP 설정은 ${CLAUDE_PLUGIN_ROOT}을 사용하며, 이는 현재 설치된 디렉터리로 해석됩니다. 업데이트 후에도 유지되어야 하는 상태 정보는 ${CLAUDE_PLUGIN_DATA}에 저장해야 하며, 이는 ~/.claude/plugins/data/ 하위의 안정적인 디렉터리로 해석됩니다.

플러그인 자체 디렉터리만 캐시로 복사되기 때문에 사용자가 뒤늦게 문제를 겪는 경우가 있습니다. ../shared-utils과 같이 플러그인 루트 외부를 가리키는 경로는 로컬 경로로 개발할 때는 작동하지만, 설치 후에는 해당 파일들이 복사되지 않아 작동하지 않게 됩니다.

구조는 다음과 같습니다.

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
├── .mcp.json
└── bin/

.claude-plugin/ 내부에는 plugin.json만 위치해야 합니다. 그 외의 모든 항목은 플러그인 루트에 있어야 합니다. skills/나 hooks/을 .claude-plugin/ 내부에 넣는 것은 플러그인이 설치는 잘 되는데 아무런 동작도 하지 않는 가장 흔한 원인입니다. Claude Code는 루트에서 해당 디렉터리를 찾는데, 발견하지 못하면 구성 요소가 없는 플러그인으로 간주하고 불러오기 때문입니다.

매니페스트 자체는 간단합니다.

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0"
}

Claude Code 플러그인 설치 방법

설치 과정은 두 단계로 나뉘며, 첫 번째 단계에서는 실제로 아무것도 설치되지 않습니다. 먼저 플러그인 목록인 마켓플레이스를 추가한 다음, 해당 마켓플레이스에서 개별 플러그인을 설치합니다. Anthropic의 공식 마켓플레이스인 claude-plugins-official는 Claude Code를 처음 대화형으로 시작할 때 자동으로 등록됩니다. 다른 마켓플레이스는 직접 추가해야 합니다.

/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@claude-code-plugins

저장소는 anthropics/claude-code이지만 마켓플레이스의 이름은 claude-code-plugins라는 점에 유의하십시오. 이름은 저장소 경로가 아니라 저장소 내부의 카탈로그 파일에서 가져옵니다. 따라서 설치 명령을 입력하기 전에 /plugin의 Marketplaces 탭에서 마켓플레이스 이름을 확인하십시오.

설치 후 요약 줄을 확인하십시오. Plugin is now active.은 구성 요소가 현재 세션에 로드되었음을 의미합니다. Run /reload-plugins to activate.은 로드되지 않았음을 의미하며, 해당 명령을 실행해야 합니다. /reload-plugins가 대화를 다시 읽어야 한다는 경고를 표시하면 /reload-plugins --force으로 다시 실행하십시오. 그 후 플러그인이 정상적으로 설치되었는지 확인하십시오. /plugin은 Installed 탭 아래에 플러그인을 표시하고, /help은 Custom commands 아래에 해당 플러그인의 기능을 나열합니다. 로드에 실패한 항목은 이유와 함께 Errors 탭에 표시됩니다.

설치 시 범위를 지정해야 하며, 이 범위에 따라 플러그인 사용자가 결정됩니다. 사용자(User) 범위는 모든 프로젝트에서 본인에게 적용됩니다. 프로젝트(Project) 범위는 플러그인을 저장소의 .claude/settings.json 내 enabledPlugins에 기록하므로, 저장소를 복제하는 모든 사용자에게 플러그인이 제공됩니다. 로컬(Local) 범위는 현재 저장소에서 본인에게만 적용됩니다.

스크립트, Dockerfile 또는 대화형 패널을 사용할 수 없는 세션에서는 셸 형식을 사용하십시오. --scope을 전달하지 않으면 사용자 범위로 설치됩니다.

claude plugin install commit-commands@claude-code-plugins --scope project
claude plugin list

claude plugin install는 세션 외부에서 실행되므로, 이미 열려 있는 세션에서는 /reload-plugins을 실행하거나 새 세션을 시작하기 전까지 새 플러그인을 인식하지 못합니다.

설치된 플러그인 관리는 두 환경 모두 동일한 패턴을 따릅니다. /plugin list은 설치된 항목을 출력하며 --enabled 또는 --disabled 옵션을 허용합니다. /plugin disable name@marketplace는 플러그인을 삭제하지 않고 비활성화하며, /plugin enable는 다시 활성화하고, /plugin uninstall은 플러그인을 제거합니다. 슬래시 명령 형식은 변경 사항을 적용하기 위해 플러그인 패널을 열기 때문에, 스크립트에서는 claude plugin ... 셸 명령어를 사용하는 것이 좋습니다.

전체 팀에 마켓플레이스를 제공하려면 프로젝트의 .claude/settings.json에 추가하십시오. 팀원들이 저장소 폴더를 신뢰하면 설치하라는 메시지가 표시됩니다.

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

직접 플러그인을 개발하는 동안에는 마켓플레이스를 완전히 건너뛰어도 됩니다. claude --plugin-dir ./my-plugin는 해당 세션에 디렉터리를 로드하고, /reload-plugins은 재시작 없이 수정 사항을 반영하며, claude plugin validate ./my-plugin은 다른 사람이 보기 전에 매니페스트, 기능 및 에이전트 프런트매터, 그리고 hooks/hooks.json를 검사합니다.

Claude Code 플러그인의 비용은 얼마입니까?

메커니즘 자체는 무료입니다. 2026년 8월 기준으로 마켓플레이스를 추가하거나, 플러그인을 설치하거나, 플러그인을 활성화된 상태로 유지하는 데 드는 비용은 없습니다. 공식 및 커뮤니티 마켓플레이스는 공개 git 저장소이며, 플러그인은 텍스트 파일로 구성된 디렉터리입니다.

플러그인의 비용은 토큰으로 발생하며, 토큰은 구독 사용량이나 API 청구서에서 실제로 측정하는 단위입니다. 플러그인이 이 둘 중 어디에서 차감되는지는 도구에 대한 결제 방식에 따라 다르며, 플랜별 Claude Code 비용에서 구독 티어와 토큰당 API 가격을 확인할 수 있습니다. 비용은 다음 세 가지 방식으로 발생하며, 각각 다르게 작동합니다.

상주 컨텍스트 비용. 플러그인이 기여하는 내용은 컨텍스트에 상주하며 세션의 모든 턴마다 다시 읽힙니다. 설치 전 /plugin 상세 보기에서 Context cost 토큰 추정치와 Will install 섹션을 통해 추가하려는 명령어, 기술, 에이전트, 훅, MCP 및 LSP 서버 목록을 확인할 수 있습니다. 두 항목 모두 확인하십시오. 로컬 또는 사용자 지정 마켓플레이스의 플러그인은 해당 데이터를 제공하지 않을 수 있으며, 이 경우 직접 추정해야 합니다. MCP 서버를 포함하는 플러그인은 도구 정의가 크기 때문에 일반적으로 가장 무겁습니다. 단, MCP 도구 검색을 지원하는 모델에서는 도구가 필요할 때까지 해당 정의가 지연됩니다.

호출 비용. 플러그인의 기술을 실행하면 해당 지침이 대화에 추가되므로, 기술 본문은 사용할 때만 비용을 지불합니다. 하지만 본문은 저렴한 편이며, 기술이 에이전트에게 수행하도록 지시하는 내용이 반드시 저렴한 것은 아닙니다. unlazy 기술의 Depth Tree 방식은 에이전트가 작업을 완료했다고 판단하기 전에 강제로 수행하는 추가 패스(pass)에 대부분의 토큰을 소비하며, 설치한 파일 자체에 소비하는 것은 아닙니다. 에이전트는 다릅니다. 서브 에이전트는 자체 시스템 프롬프트와 자체 캐시를 사용하여 별도의 대화를 실행하며, 캐시 적중 없이 시작합니다. 따라서 워크플로우가 에이전트를 생성하는 플러그인은 컨텍스트 추정치보다 훨씬 많은 비용이 듭니다.

캐시 비용. 세션 도중에 플러그인을 활성화하거나 비활성화하면 다음 요청 시 전체 대화를 다시 처리해야 할 수 있습니다. 기술, 명령어, 에이전트, 훅, LSP 서버, 모니터 및 테마는 이러한 작업을 수행하지 않습니다. 이들이 추가하는 내용은 기존 기록 뒤에 덧붙여지므로, 다음 요청은 새로운 콘텐츠에 대해서만 비용을 지불하고 이전 내용은 캐시에서 읽어옵니다. 예외는 MCP 서버를 제공하는 플러그인입니다. 도구 검색을 통해 도구가 지연되면 캐시가 유지됩니다. 하지만 프롬프트 접두사(prefix)로 로드되면 다음 요청 시 전체 대화를 캐시되지 않은 입력으로 다시 읽습니다. 이것이 바로 /reload-plugins이 해당 경우에 경고를 표시하고 --force을 통과하기 전까지 거부하는 이유입니다.

추측하지 말고 직접 확인하십시오. 모든 API 응답은 cache_read_input_tokens 및 cache_creation_input_tokens를 보고하며, 실시간 토큰 사용량을 보여주는 사용자 지정 상태 표시줄을 통해 두 수치를 모두 확인할 수 있습니다. 정상적인 세션은 생성하는 양보다 읽는 양이 훨씬 많습니다. 매 턴마다 생성량이 높게 유지된다면 접두사 내의 무언가가 매 턴마다 변경되고 있는 것입니다. 창을 채우는 요소에 대한 더 자세한 내용은 Claude Code 컨텍스트 창 관리 방법 및 토큰 수의 실제 의미를 참조하십시오.

한 가지 관리 작업은 비용을 절감해 줍니다. Installed 탭은 최소 2주 동안 사용하지 않은 플러그인을 Not used recently 헤더 아래에 그룹화하며, 상세 보기에서 Last used 라인을 제공합니다. 해당 플러그인은 매 세션마다 시작 시간과 컨텍스트 비용을 발생시킵니다. 비활성화하거나 제거하십시오.

플러그인은 사용자의 권한으로 실행됩니다

Anthropic의 공식 문서에서는 이 점을 명확히 밝히고 있습니다. 플러그인과 마켓플레이스는 매우 신뢰할 수 있는 구성 요소이며, 사용자의 권한으로 시스템에서 임의의 코드를 실행할 수 있습니다. 이는 가설이 아닙니다. 플러그인의 훅(hook)은 도구 호출 전후를 포함한 세션 이벤트 발생 시 셸 명령을 실행합니다. 플러그인이 활성화되어 있는 동안 해당 플러그인의 bin/ 디렉터리는 Bash 도구의 PATH에 추가됩니다. 플러그인이 시작하는 MCP 서버 역시 별도의 프로세스로 동작합니다. 이 과정에서 사용자 계정과 격리된 샌드박스는 존재하지 않습니다.

노트북 환경에서는 이러한 위험이 데스크톱 사용자가 접근할 수 있는 범위로 제한됩니다. 하지만 서버 환경에서는 대개 그렇지 않습니다. 에이전트를 실행하는 계정은 종종 SSH 키, 배포 토큰, 클라우드 CLI 세션, Docker 소켓에 대한 접근 권한을 가지고 있으므로, "사용자 권한으로 실행되는 임의의 코드"는 곧 해당 서버 전체에 대한 제어권을 의미합니다. Claude Code를 VPS에서 실행 중이라면, 무언가를 설치하기 전에 Claude Code를 VPS에서 안전하게 실행하는 방법을 읽어보십시오. 또한 외부 서비스와 통신하는 플러그인을 설치하기 전에 에이전트가 자격 증명에 접근하지 못하도록 보호하는 방법을 확인하십시오. 다른 하네스(harness) 도구들도 동일한 서버 환경에서 같은 제약에 직면합니다. 이것이 바로 설치할 가치가 있는 DeepSeek Harness 플러그인들이 새로운 기능을 추가하기보다는 주로 지출 한도 설정, 도구 권한 규칙, 주입(injection) 스캔 등에 집중하는 이유입니다.

몇 가지 안전장치가 존재하며, 이를 이해하는 것이 도움이 됩니다. 프로젝트 범위의 플러그인은 사용자가 아닌 리포지토리에서 제공되므로, 작업 공간을 신뢰한 후에만 로드됩니다. 또한 MCP 서버는 서버별로 승인이 필요하며, LSP 서버는 신뢰가 확인될 때까지 대기하고, 백그라운드 모니터는 아예 로드되지 않습니다. 플러그인과 함께 제공되는 에이전트는 훅, MCP 서버 또는 권한 모드를 선언할 수 없습니다. 마켓플레이스 플러그인은 캐시로 복사될 때 마켓플레이스 외부를 가리키는 심볼릭 링크는 건너뛰므로, 플러그인이 임의의 호스트 파일을 가져올 수 없습니다.

이러한 장치들이 설치하는 소프트웨어를 직접 검토하는 과정을 대신할 수는 없습니다. Will install 목록을 확인하고, 소스 코드를 열어 읽을 수 있는 플러그인을 우선적으로 선택하십시오. 팀의 플러그인은 직접 관리하는 마켓플레이스 리포지토리에 보관하고, 직접 작성한 코드에는 claude plugin validate을 실행하십시오.

FAQ

Claude Code 플러그인 사용 시 추가 비용이 발생합니까?

아니요. 플러그인 시스템 사용, 마켓플레이스 추가, 플러그인 설치에는 별도의 비용이 없습니다. 비용은 토큰 사용량에 따라 발생하며, 다른 컨텍스트와 마찬가지로 귀하의 플랜 또는 API 사용량에 합산되어 청구됩니다. 플러그인은 매 턴마다 상주 컨텍스트를 추가하고, 기능이나 에이전트가 호출될 때 컨텍스트를 더하며, MCP 서버의 도구가 프롬프트 접두사에 로드되는 경우 비용이 발생하는 캐시되지 않은 턴을 강제할 수 있습니다. /plugin 상세 보기에서 설치 전 Context cost 예상치를 확인할 수 있습니다.

플러그인과 스킬의 차이점은 무엇입니까?

스킬은 단일 명령 단위입니다. 플러그인은 스킬, 에이전트, 훅, MCP 서버, LSP 서버, 모니터를 포함할 수 있는 패키지이며, 이름, 버전, 설치를 위한 마켓플레이스를 가집니다. 귀하와 현재 프로젝트만을 위한 것이라면 .claude/에 독립형 스킬을 작성하십시오. Ponytail, 에이전트가 작동하는 가장 작은 변경 사항을 적용하도록 유도함과 같은 단일 목적 스킬이 가장 명확한 예입니다. 이는 팀원들도 필요로 하기 전까지는 하나의 규칙이 담긴 하나의 파일로 충분합니다. 다른 사람들이 필요로 하고 시간이 지남에 따라 업데이트가 필요해지면 플러그인으로 전환하십시오. 플러그인 스킬은 네임스페이스가 지정되므로, 플러그인 내부의 스킬은 /skill-name이 아닌 /plugin-name:skill-name으로 호출됩니다.

플러그인을 설치했는데 스킬이 나타나지 않습니다. 무엇이 문제입니까?

먼저 설치 요약을 확인하십시오. Run /reload-plugins to activate.라고 표시되었다면 구성 요소가 아직 로드되지 않은 것이며, 다시 로드 시 대화 내용을 다시 읽는다는 경고가 나타나면 /reload-plugins --force으로 다시 실행하십시오. 로드는 되었으나 아무것도 표시되지 않는다면 /plugin를 열고 Errors 탭을 읽어보십시오. 가장 흔한 구조적 실수는 skills/, agents/ 또는 hooks/을 Claude Code가 검색하지 않는 .claude-plugin/ 내부에 배치하는 것입니다. 플러그인 스킬은 네임스페이스가 지정되어 있으므로 /help의 Custom commands 탭에서 /plugin-name:skill-name을 찾아야 한다는 점을 기억하십시오. 마지막 수단으로 rm -rf ~/.claude/plugins/cache을 실행하고, 재시작한 뒤 다시 설치하십시오.

대화형 패널 없이 플러그인을 설치할 수 있습니까?

네. 셸 명령 claude plugin install name@marketplace를 사용하십시오. --scope project 또는 --scope local을 전달하지 않으면 사용자 범위에 설치됩니다. 이 명령은 /plugin 패널을 사용할 수 없는 스크립트, 이미지 및 비대화형 환경에서 작동합니다. 세션 외부에서 실행되므로 이미 열려 있는 세션은 플러그인이 적용되기 전에 /reload-plugins이 필요합니다.

GitHub에서 찾은 마켓플레이스의 플러그인을 설치해도 안전합니까?

해당 저장소의 설치 스크립트를 직접 실행하는 것과 동일하게 취급하십시오. 플러그인은 훅을 통해 셸 명령을 실행하고, Bash 도구의 PATH에 실행 파일을 추가하며, MCP 서버를 시작할 수 있는데, 이 모든 과정은 귀하의 사용자 권한으로 수행됩니다. Anthropic은 타사 플러그인 콘텐츠를 제어하거나 검증하지 않습니다. 읽을 수 있는 소스에서만 설치하고, 확인 전 Will install 목록을 검토하십시오. 서버의 계정은 보통 탈취 가치가 있는 키와 토큰을 보유하고 있으므로 노트북보다 서버에서 더 엄격하게 관리하십시오.