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 서버 또는 규칙 파일

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

• 스킬(skill)은 작업 수행 시 Claude가 불러오는 단일 명령 단위입니다. 에이전트 스킬의 실제 의미를 참조하십시오.
• MCP 서버는 프로토콜을 통해 에이전트에 도구를 제공하는 별도의 프로세스이며, 대개 사용자가 직접 실행하는 네트워크 서비스입니다.
• CLAUDE.md과 같은 규칙 파일은 세션 시작 시 읽히며 모든 작업에 적용되는 프로젝트 컨텍스트입니다.
• 플러그인(plugin)은 스킬, 에이전트, 훅(hook), 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/

plugin.json만이 .claude-plugin/ 내부에 위치해야 합니다. 그 외의 모든 항목은 플러그인 루트에 위치합니다. 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 탭에 표시됩니다.

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

스크립트, 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를 검사합니다.

FAQ

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

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

플러그인의 실제 비용은 토큰이며, 토큰은 구독 사용량이나 API 청구서에서 실제로 측정하는 단위입니다. 이 비용은 세 가지 방식으로 발생하며, 각각 다르게 동작합니다.

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

호출 비용. 플러그인의 기술을 실행하면 해당 지침이 대화에 추가되므로, 기술 본문은 사용할 때만 비용을 지불합니다. 에이전트는 다릅니다. 서브 에이전트는 자체 시스템 프롬프트와 자체 캐시를 사용하여 별도의 대화를 실행하며, 캐시 적중 없이 시작합니다. 따라서 워크플로우가 에이전트를 생성하는 플러그인은 컨텍스트 추정치보다 훨씬 더 많은 비용이 발생합니다.

캐시 비용. 세션 중간에 플러그인을 활성화하거나 비활성화하면 다음 요청 시 전체 대화를 다시 처리해야 할 수 있습니다. 기술, 명령어, 에이전트, 훅, LSP 서버, 모니터 및 테마는 절대 이런 동작을 하지 않습니다. 이들이 추가하는 내용은 기존 기록 뒤에 덧붙여지므로, 다음 요청은 새로운 콘텐츠에 대해서만 비용을 지불하고 그 이전의 모든 내용은 캐시에서 읽어옵니다. 예외는 MCP 서버를 제공하는 플러그인입니다. 도구 검색을 통해 도구가 지연되면 캐시가 유지됩니다. 만약 프롬프트 접두사에 로드되면, 다음 요청은 전체 대화를 캐시되지 않은 입력으로 다시 읽습니다. 이것이 바로 /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에서 안전하게 실행하는 방법을 읽어보십시오. 또한 외부 서비스와 통신하는 플러그인을 설치하기 전에 에이전트가 자격 증명에 접근하지 못하도록 차단하는 방법을 확인하십시오.

일부 안전장치가 존재하므로 이를 숙지하는 것이 도움이 됩니다. 프로젝트 범위의 플러그인은 사용자가 아닌 저장소에서 제공되므로, 작업 공간을 신뢰한 후에만 로드됩니다. 또한 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 목록을 검토하십시오. 서버의 계정은 보통 탈취 가치가 있는 키와 토큰을 보유하고 있으므로 노트북보다 서버에서 더 엄격하게 관리하십시오.