플러그인

플러그인이란

플러그인은 설치 가능한 하나의 단위입니다. 그렇지 않으면 수작업으로 공유해야 할 모든 것, 즉 Skills, 서브에이전트, 훅, MCP 서버 설정은 물론 언어 서버 프로토콜 서버, 백그라운드 모니터, 테마, settings.json의 일부와 같은 더 긴 꼬리의 항목들까지 묶어 놓습니다. 하나의 버전, 하나의 설치입니다.

플러그인이 어디에 있는지에 따라 설치 방법이 결정됩니다. 세션 내에서는 이름으로 직접 하나를 설치할 수 있습니다:

이 명령은 먼저 플러그인의 세부 정보를 열어주므로, 검토한 후 범위를 선택할 수 있습니다. 그런 다음 Claude Code가 이를 설치하고 간단한 요약을 출력합니다. 플러그인이 이미 이 세션에서 활성화되어 있다고 표시되거나, /reload-plugins를 언급하며 Claude Code가 해당 재로드를 대신 실행합니다. 재로드가 다음 메시지에서 전체 대화를 다시 읽게 된다고 경고하는 경우에만 직접 개입하면 됩니다: 그래도 플러그인을 활성화하려면 /reload-plugins --force를 실행하세요.

팀을 위한 마켓플레이스 추가하기

팀의 경우, 더 나은 방법은 프라이빗 마켓플레이스를 한 번 추가하는 것입니다. 마켓플레이스는 플러그인이 참조하는 공유 소스입니다:

원하는 이름으로 지정하면 됩니다. 추가되고 나면, 이후의 모든 설치는 이를 통해 참조됩니다. 모든 사람의 노트북에 흩어져 있는 대신, 중앙화된 검색, 버전 추적, 업데이트를 한곳에서 얻을 수 있습니다.

Discover 탭에서 사용 가능한 항목을 둘러볼 수 있습니다. 여기에는 여러분의 마켓플레이스에 있는 플러그인이 나열되어 있어 검색하고 선택할 수 있습니다.

설치하기 전에 읽어보세요

여기가 가장 중요한 부분입니다. 플러그인은 여러분의 권한으로 여러분의 기기에서 코드를 실행합니다. 플러그인의 훅은 일치하는 모든 도구 호출에서 실행됩니다. 따라서 Skills 때문에 플러그인을 설치하더라도, 읽었든 읽지 않았든 해당 플러그인의 PreToolUse 및 Stop 훅도 함께 얻게 됩니다.

이것이 무엇을 의미하는지 생각해 보세요. 커뮤니티 플러그인이 매번 네트워크 엔드포인트를 호출하는 Stop 훅을 포함할 수 있으며, 여러분의 설정에는 이를 경고하는 내용이 전혀 없을 수 있습니다. 그렇다고 플러그인을 피해야 한다는 뜻은 아닙니다. 먼저 살펴봐야 한다는 뜻입니다.

설치하기 전에 플러그인의 세부 정보를 확인하세요. Claude Code는 설치될 내용을 보여주고 컨텍스트 비용을 추정하며, Anthropic이 타사 플러그인 내부를 통제하지 않는다는 명확한 경고도 함께 제공합니다.

플러그인의 출처에 대해 알아둘 만한 두 가지가 있습니다:

• 플러그인이 커뮤니티 마켓플레이스에 올라가는 것은 작성자가 Anthropic에 제출했기 때문입니다.
• 공식 마켓플레이스는 별도의 독립된 트랙에서 큐레이션됩니다.

하지만 등록되어 있다고 해서 신뢰할 수 있다는 뜻은 아닙니다. 그러므로 원칙은 변하지 않습니다: 진정으로 신뢰하는 출처에서만 플러그인을 설치하고 마켓플레이스를 추가하며, 활성화하기 전에 플러그인이 실제로 무엇을 하는지 확인하세요.

구성 요소는 여러분의 것과 함께 실행됩니다

플러그인은 여러분의 설정을 덮어쓰지 않습니다. 플러그인의 구성 요소는 여러분 자신의 것과 함께 실행됩니다. 이는 대체로 좋은 일이지만, 이해해야 할 결과가 있습니다.

훅은 누적됩니다. 플러그인의 PreToolUse 훅과 여러분 자신의 PreToolUse 훅은 모든 도구 호출에서 둘 다 실행됩니다. 어느 쪽도 다른 쪽을 대체하지 않습니다. 이것이 바로 세부 정보를 먼저 읽어야 하는 이유입니다.

Skills, 에이전트, 명령어는 플러그인 이름 아래에 네임스페이스로 지정되므로 여러분의 것과 절대 충돌하지 않습니다. 플러그인은 settings.json 파일도 포함할 수 있지만, 매우 제한된 범위만 가능합니다. Claude Code는 여기서 단 두 개의 키, 즉 에이전트와 서브에이전트 상태 표시줄 키만 인정합니다.

그 에이전트 키는 잠시 짚고 넘어갈 가치가 있습니다. 이를 설정하면 플러그인의 서브에이전트 중 하나가 시스템 프롬프트, 도구 제한, 모델과 함께 메인 스레드로 승격됩니다. 다시 말해, 플러그인을 활성화하면 Claude Code의 기본 동작 방식이 바뀔 수 있습니다. 이것이 바로 활성화하기 전에 먼저 살펴봐야 하는 주된 이유 중 하나입니다.

플러그인이 설치되면 플러그인 패널에서 추가된 모든 항목을 확인하고, 관리하고, 제거할 수 있습니다.

자신의 플러그인 패키징하기

이제 다른 측면입니다. 잘 작동하는 .claude 디렉터리를 만들었다면, 팀원들이 이를 여러 기기에 복사해서 붙여넣게 하지 마세요. 대신 패키징하세요.

좋은 소식은 아무것도 재구성할 필요가 없다는 것입니다. 플러그인은 여러분이 이미 사용하고 있는 것과 동일한 .claude 구조를 사용합니다:

• Skill당 하나의 폴더.
• agents 아래 서브에이전트당 하나의 마크다운 파일.
• 플러그인 루트에 있는 hooks/hooks.json과 .mcp.json.

디렉터리 구조가 대부분의 작업을 처리합니다. Claude Code는 규칙에 따라 구성 요소를 발견합니다.

매니페스트

그 위에 선택적인 매니페스트가 있습니다. 이는 .claude-plugin/plugin.json에 위치하며 이름, 버전, 설명, 작성자를 담고 있습니다:

{
  "name": "svg-splitter-review",
  "version": "0.1.0",
  "description": "Reviews the SVG Splitter repo",
  "author": {
    "name": "Lewis Menelaws"
  }
}

매니페스트는 선택 사항입니다. 생략해도 Claude Code는 여전히 디렉터리 규칙에 따라 구성 요소를 발견합니다. 하지만 알아둘 만한 몇 가지 세부 사항이 있습니다:

• 이름은 유일한 필수 필드입니다. 이는 여러분의 Skills를 /plugin-name:skill-name으로 네임스페이스화하므로, 이 플러그인의 Skill은 /svg-splitter-review:<skill-name>으로 실행됩니다. 이는 여러분의 Skills가 다른 사람의 것과 충돌하지 않도록 해줍니다.
• 다른 의존성과 마찬가지로 버전을 지정하세요. 이것이 팀 전체에서 업데이트와 버전 추적이 작동하게 만드는 요소입니다.

핵심 정리

이 내용의 대부분은 두 가지 간단한 규칙으로 요약됩니다:

• 플러그인을 사용할 때는 설치하기 전에 읽으세요. 플러그인은 여러분의 권한으로 코드를 실행하므로, 먼저 훅, 에이전트, MCP 서버를 살펴보세요.
• 플러그인을 만들 때는 작동하는 순간 .claude를 패키징하세요. 하나의 매니페스트, 하나의 설치입니다.

이것이 핵심입니다. 하나의 설치 가능한 단위로, 여러분이 신뢰하는 설정이 팀 전체에 도달합니다.