플러그인

정의#

Claude Code 확장 기능의 포장 층이다. 스킬, 훅, 서브에이전트, MCP 서버(용어 사전)를 설치 가능한 단위 하나로 묶는다. Claude Code 확장 기능 개요

블로그 글(2026-06-18)은 몇 가지가 잘 돌아가면 스킬, 서브에이전트, 훅, 출력 스타일 여럿을 플러그인으로 묶어 팀원이나 여러 프로젝트에 일관된 셋업을 나눌 수 있다고 말한다. Steering Claude Code 공식 스킬 문서도 플러그인 안의 hooks/, .mcp.json, agents/, output-styles/ 변경은 /reload-plugins를 해야 반영된다고 적어, 플러그인이 출력 스타일을 담을 수 있음을 확인한다(2026-10-18 기준). Claude Code 스킬 공식 출력 스타일 문서(2026-10-18 기준)는 플러그인이 output-styles/ 디렉터리로 스타일을 담는다고 직접 적고, 플러그인 스타일 frontmatter에 force-for-plugin: true를 두면 플러그인이 켜져 있을 때 사용자가 고르지 않아도 그 스타일이 적용돼 사용자의 outputStyle 설정을 덮어쓴다고 한다. 여러 플러그인이 이를 설정하면 먼저 로드된 것을 쓴다. Claude Code 출력 스타일 → Claude Code 출력 스타일 설정·만들기

마켓플레이스(marketplace)는 플러그인 모음을 호스팅하고 배포하는 곳이다. Claude Code 확장 기능 개요

Anthropic의 직무별 플러그인 저장소 README(2026-10-18 수집)는 플러그인을 Claude를 특정 역할·팀·회사의 전문가로 만드는 것으로 설명한다. 플러그인 하나가 특정 직무에 필요한 스킬, 커넥터, 슬래시 명령, 서브에이전트를 묶고, 일하는 방식, 쓸 도구·데이터, 중요한 워크플로 처리법, 노출할 슬래시 명령을 Claude에게 알려 준다. 이 저장소의 플러그인은 Claude Cowork용으로 만들었고 Claude Code와도 호환된다. Knowledge Work Plugins 저장소 → Knowledge Work Plugins Cowork와 채팅을 합친 Claude의 Help Center 문서(수정일 2026-09-16)도 플러그인을 역할별로 스킬과 커넥터를 묶는 것으로 소개한다. Claude Cowork와 채팅 통합 도움말

구조 (2026-10-18 기준)#

Knowledge Work Plugins 저장소 README는 그 저장소의 모든 플러그인이 같은 구조를 따른다고 말한다.

plugin-name/
├── .claude-plugin/plugin.json   # 매니페스트
├── .mcp.json                    # 도구 연결
├── commands/                    # 직접 부르는 슬래시 명령
└── skills/                      # Claude가 자동으로 꺼내 쓰는 도메인 지식

원본은 모든 구성 요소가 마크다운과 JSON 파일이고 코드·인프라·빌드 단계가 없다고 말한다. README 첫머리는 플러그인이 서브에이전트도 묶는다고 하지만, 위 구조도에는 서브에이전트 폴더가 없다. Knowledge Work Plugins 저장소 스킬 폴더 하나를 플러그인으로 로드할 때 함께 묶는 hooks/, agents/, output-styles/는 아래 "플러그인으로 스킬 나누기"에 있다. Claude Code 스킬

플러그인 속 훅 (2026-10-18 기준): 공식 훅 가이드는 플러그인의 훅 위치를 hooks/hooks.json으로 적는다. 플러그인이 켜져 있을 때 유효하고 플러그인에 묶여 공유된다. 이 훅도 settings 파일의 훅처럼 제한을 더할 수는 있지만 권한 규칙이 허용하는 범위 너머로 풀 수는 없다. 원본은 별도 모델 검토를 돌려 결과를 세션에 되돌려 주는 훅의 운영 예로 security-guidance 플러그인을 링크한다. Claude Code 훅 가이드 → 훅 공식 훅 레퍼런스(2026-10-18 기준)는 hooks/hooks.json에 선택적인 최상위 description을 둘 수 있고, 플러그인이 켜지면 그 훅이 사용자·프로젝트 훅과 합쳐진다고 적는다. 스크립트는 ${CLAUDE_PLUGIN_ROOT}(설치 디렉터리)와 ${CLAUDE_PLUGIN_DATA}(업데이트 뒤에도 남는 데이터 디렉터리)로 가리키고, 사용자 설정값 ${user_config.*}는 exec form(args가 있는 command 훅)에서만 치환된다. shell form에서는 오류가 나므로 $CLAUDE_PLUGIN_OPTION_<KEY> 환경 변수를 읽는다. 플러그인이 JavaScript 함수로 등록하는 훅(mod)은 별도 문서가 다룬다. Claude Code 훅 레퍼런스 → 훅 입출력 규칙

언제 쓰는가#

• 특정 직무(영업, 재무, 법무, 고객지원 등)의 일을 맡길 때 그 직무용 플러그인을 설치해 출발점으로 쓰고, 회사의 도구·용어·프로세스에 맞게 고친다. 원본은 고치지 않은 플러그인을 범용 출발점이라 부른다. Knowledge Work Plugins 저장소 → 업무 플러그인 설치·맞춤화
• 같은 셋업을 여러 저장소에서 다시 쓰고 싶을 때, 또는 마켓플레이스로 다른 사람에게 배포하고 싶을 때. Claude Code 확장 기능 개요
• 셋업 계기: 두 번째 저장소에 같은 셋업이 필요해지면 플러그인으로 묶는다. Claude Code 확장 기능 개요 → Claude Code 셋업 점진적으로 키우기
• 언어 서버 연동(Code intelligence)도 언어별 플러그인으로 설치한다. 설치 전까지 LSP 도구는 비활성이다. Claude Code 확장 기능 개요
• (2026-10-21 기준) 팀 공유: 플러그인은 커밋한 .claude/settings.json으로 팀에 나눌 수 있지만, 파일이 선언한 extraKnownMarketplaces는 팀원 각자가 폴더를 신뢰한 뒤에만 적용돼 그 전에는 그 마켓플레이스의 플러그인을 받지 않는다. 클라우드 세션에서는 Anthropic 호스팅 환경의 저장소 여럿인 세션이 각 저장소의 enabledPlugins·extraKnownMarketplaces만 읽지만, 그 두 키가 선언한 마켓플레이스·플러그인은 클라우드 세션에서 로드되지 않는다. Claude Code 설정 파일과 우선순위 → Claude Code 설정 파일

이름 충돌을 피하는 방식#

• 플러그인 스킬은 /my-plugin:review처럼 네임스페이스가 붙어 여러 플러그인이 함께 있을 수 있다. Claude Code 확장 기능 개요 공식 스킬 문서도 같은 규칙을 확인한다. 플러그인 스킬은 /plugin-name:skill-name으로 네임스페이스가 붙어 다른 위치의 같은 이름 스킬과 함께 로드되고, frontmatter name은 마지막 부분만 바꾼다(my-plugin/skills/review/SKILL.md에 name: fancy면 /my-plugin:fancy). 다른 명령이 쓰지 않으면 맨 이름(/fancy)으로도 부를 수 있다. Claude Code 스킬
• 서브에이전트는 이름이 겹칠 때 plugin 레벨이 우선순위 맨 아래다(managed > CLI 플래그 > project > user > plugin). Claude Code 확장 기능 개요
• (2026-10-18 기준) 공식 서브에이전트 문서: 플러그인 agents/는 재귀로 훑고 하위 폴더가 범위 이름에 들어간다(my-plugin의 agents/review/security.md는 my-plugin:review:security). @-mention 목록에는 범위 이름으로 보이고, claude --agent에는 이름만 줘도 찾되 여러 플러그인이 겹치면 범위 이름을 쓴다. 보안상 플러그인 서브에이전트는 hooks·mcpServers·permissionMode를 무시하므로, 플러그인 작성자는 훅을 hooks/hooks.json, MCP 서버를 .mcp.json에 둔다(이들은 서브에이전트 안에서만이 아니라 플러그인이 켜진 동안 늘 적용). 플러그인 서브에이전트의 위임 안정성은 claude plugin eval로 잰다. Claude Code 서브에이전트 → 서브에이전트 정의 파일 레퍼런스
• 플러그인에서 온 훅은 다른 곳의 훅과 합쳐져 모두 실행된다. Claude Code 확장 기능 개요

조직이 플러그인·마켓플레이스를 통제하는 법 (2026-10-18 기준)#

공식 managed settings 배포 문서가 드는 managed 전용 키다. 키별 전체 동작은 settings reference(2026-10-21 수집, 아래 마지막 항목과 Claude Code 설정 키 레퍼런스)와 플러그인 조직 문서에 있다. Claude Code managed settings 배포 → managed settings

• strictKnownMarketplaces: 사용자가 추가하고 플러그인을 설치할 수 있는 마켓플레이스 출처를 정한다. 잘못 쓰면 빈 허용 목록으로 강제돼 어떤 마켓플레이스 출처도 들어오지 못한다(v2.1.277 이상. 그 전 버전은 키 전체를 버린다).
• blockedMarketplaces: 차단 목록. 차단된 출처는 다운로드 전에 검사돼 파일 시스템에 닿지 않는다.
• strictPluginOnlyCustomization: user·project 출처의 스킬·에이전트·훅·MCP 서버를 막는다. true는 넷 다, 배열은 지정한 것만.
• disableSideloadFlags: 시작 때 --plugin-dir, --plugin-url, --agents, --mcp-config를 거부한다(v2.1.193 이상).
• disableCommandPluginSources: true면 command 플러그인 출처를 막아 마켓플레이스가 선언한 명령이 실행되지 않는다(v2.1.229 이상). 설정하지 않으면 allowManagedHooksOnly를 따른다.
• pluginTrustMessage(설치 전 신뢰 경고에 덧붙일 문구), pluginSuggestionMarketplaces(Claude Code가 플러그인을 제안할 수 있는 마켓플레이스).
• Cowork: claude.ai의 git 저장소나 Cowork 탭의 Customize에서 마켓플레이스를 추가할 때, claude.ai가 관리 콘솔의 strictKnownMarketplaces·blockedMarketplaces를 직접 적용한다(세션이 어디서 돌든).
• (2026-10-21 기준) settings reference가 키 항목에 더하는 것: strictKnownMarketplaces를 빈 배열로 두면 공식 Anthropic 마켓플레이스까지 모든 출처를 막는 완전 잠금이다. 이 키는 추가·설치·업데이트·새로고침·자동 업데이트 때 네트워크·파일 작업 전에 검사하지만 마켓플레이스를 등록하지는 않으므로, 막으면서 미리 등록하려면 같은 managed 파일에 extraKnownMarketplaces를 함께 둔다. 허용 목록이 있으면(빈 목록 포함) ~/.claude/skills/의 @skills-dir 플러그인 로드도 멈추고, {"source": "skills-dir"} 항목을 넣어야 유지된다. enabledPlugins에서 managed가 false로 둔 플러그인은 모든 범위에서 설치가 막히고 마켓플레이스에서 숨겨진다. 범위끼리는 project가 user보다 우선해, 프로젝트가 켠 플러그인을 내 기기에서만 끄려면 .claude/settings.local.json에 false를 둔다(managed가 강제로 켠 것은 끌 수 없다). project에서 외부 출처 플러그인을 켜도 팀원 기기에 설치되지는 않고 각자 설치해야 한다. extraKnownMarketplaces에 같은 이름이 여러 파일에 있으면 가장 높은 파일의 항목을 통째로 쓴다(v2.1.228 이상, 그 전에는 필드별로 합쳐 다른 파일의 headers를 물려받을 수 있었다). Claude Code 설정 키 전체 레퍼런스

플러그인으로 스킬 나누기 (2026-10-18 기준)#

• 스킬 공유 범위는 셋이다. 프로젝트는 .claude/skills/ 커밋, 여러 곳은 플러그인의 skills/ 디렉터리, 조직 전체는 managed settings. Claude Code 스킬 → 업무 절차를 스킬로 만들기
• 스킬 폴더에 .claude-plugin/plugin.json을 더하면 그 폴더가 <name>@skills-dir라는 플러그인으로 로드돼 에이전트, 훅, MCP 서버를 함께 묶을 수 있다. 프로젝트 .claude/skills/에서는 작업 공간 신뢰 대화상자를 먼저 수락해야 한다. 이 폴더의 hooks/, .mcp.json, agents/, output-styles/ 변경은 /reload-plugins가 필요하다. Claude Code 스킬
• 플러그인 스킬은 skillOverrides의 영향을 받지 않는다. /plugin으로 관리하고, 끄려면 플러그인을 비활성화하거나 /plugin uninstall <plugin-name>@<marketplace-name>으로 제거한다. Claude Code 스킬
• 평가: claude plugin eval이 프롬프트마다 플러그인 있이·없이 격리 세션에서 돌려 채점하고, 기준 아래면 0이 아닌 코드로 끝나 CI 관문으로 쓸 수 있다. claude plugin validate <디렉터리>는 frontmatter가 파싱되지 않는 SKILL.md를 찾는다(v2.1.233 이상). Claude Code 스킬 → 스킬 문제 해결
• 다른 마켓플레이스 예: Anthropic의 직무별 플러그인은 claude plugin marketplace add anthropics/knowledge-work-plugins로 마켓플레이스를 추가한 뒤 claude plugin install sales@knowledge-work-plugins처럼 설치한다. Cowork에서는 claude.com/plugins에서 설치한다. Knowledge Work Plugins 저장소 → 업무 플러그인 설치·맞춤화
• 공식 마켓플레이스 예: skill-creator 플러그인은 /plugin install skill-creator@claude-plugins-official로 설치한다. 마켓플레이스를 못 찾으면 /plugin marketplace add anthropics/claude-plugins-official, 목록이 낡았으면 /plugin marketplace update claude-plugins-official 뒤 다시 설치한다. Claude Code 스킬

직무별 플러그인 모음 (2026-10-18 기준)#

Anthropic은 직무별 플러그인을 GitHub에 오픈소스로 공개했다. README 표는 11개(productivity, sales, customer-support, product-management, marketing, legal, finance, data, enterprise-search, bio-research, cowork-plugin-management)이고, 같은 날 저장소 디렉터리 목록에는 22개가 있으며, marketplace.json에는 외부 저장소 플러그인 101개가 이름만 올라 있다. Knowledge Work Plugins 저장소 부서별 하는 일과 커넥터는 Knowledge Work Plugins에 정리했다.

회사에 맞게 고치는 방법은 넷이다: .mcp.json으로 커넥터 바꾸기, 스킬 파일에 회사 용어·조직 구조·프로세스 넣기, 스킬 지시를 팀의 실제 방식에 맞추기, cowork-plugin-management 플러그인이나 같은 구조로 새 플러그인 만들기. Knowledge Work Plugins 저장소 → 업무 플러그인 설치·맞춤화