Claude Code를 쓰다 보면 스킬, 서브에이전트, 훅, MCP 서버를 하나씩 직접 설정하게 됩니다. 쓸 만한 구성이 쌓일수록 같은 설정을 다른 프로젝트에 옮기거나 팀원과 나누는 일이 번거로워집니다.
**플러그인(Plugin)**은 이런 구성요소를 하나의 단위로 묶어서 설치하고 업데이트하는 방식입니다. 공식 문서 기준으로 플러그인은 skills, agents, hooks, MCP servers 같은 구성요소를 담은 디렉터리이고, 보통 **마켓플레이스(Marketplace)**라는 카탈로그에서 이름으로 설치합니다.
이 글에서는 플러그인이 무엇인지, 어떻게 설치하고 관리하는지, 어떤 플러그인이 있고 어떤 상황에서 쓰면 좋은지를 정리합니다. 명령어와 동작은 Claude Code 공식 문서를 확인한 내용입니다.
1. 플러그인의 구성
플러그인은 구성요소를 담은 디렉터리입니다. 대부분 .claude-plugin/plugin.json 매니페스트로 이름과 버전, 설명을 정의합니다.
플러그인이 담을 수 있는 구성요소는 다음과 같습니다.
- Skills: Claude가 관련 상황에서 불러오는
SKILL.md지침입니다./플러그인명:스킬명형태의 명령으로도 실행합니다. - Agents: Claude가 작업을 위임할 수 있는 서브에이전트 정의입니다.
- Hooks: 편집 직후처럼 Claude Code의 특정 시점에 실행되는 명령입니다.
- MCP servers: 플러그인이 켜져 있는 동안 Claude Code가 연결하는 도구 서버입니다.
- LSP servers: 언어 서버를 연결해 진단과 정의 이동 같은 코드 인텔리전스를 제공합니다.
스킬 이름에는 플러그인 이름이 접두사로 붙습니다. commit-commands 플러그인의 스킬은 /commit-commands:commit으로 실행합니다.
2. 단독 설정과 플러그인의 차이
스킬, 서브에이전트, 훅, MCP 서버는 플러그인 없이도 각각 동작합니다. ~/.claude/skills/에 저장한 스킬은 이 컴퓨터의 모든 프로젝트에서 쓸 수 있습니다.
| 구분 | 단독 설정 | 플러그인 |
|---|---|---|
| 단위 | 스킬, 훅, MCP 서버를 각각 설정 | 여러 구성요소를 하나로 묶음 |
| 설치 | 파일을 직접 만들거나 복사 | /plugin install 한 줄 |
| 업데이트 | 직접 관리 | 마켓플레이스에서 갱신 |
| 공유 | 파일을 전달 | 마켓플레이스 등록 후 이름으로 설치 |
| 적합한 경우 | 내 프로젝트에서만 쓰는 구성 | 여러 프로젝트나 팀에 같은 구성을 배포할 때 |
이 블로그의 tech-blog-writer는 이 프로젝트에서만 쓰는 스킬이라 .claude/skills/에 단독으로 두었습니다. 같은 구성을 여러 저장소에 배포해야 하는 시점이 오면 플러그인으로 묶는 것이 맞습니다.
3. 마켓플레이스
마켓플레이스는 .claude-plugin/marketplace.json 파일이 플러그인 목록과 가져올 위치를 적어 둔 카탈로그입니다. 상점이 아니라 목록이며, 보통 GitHub 저장소 하나가 마켓플레이스가 됩니다. 한 번 추가해 두면 이름으로 설치합니다. (commit-commands@claude-plugins-official)
Anthropic은 세 가지 마켓플레이스를 운영합니다.
| 구분 | 공식 | 커뮤니티 | 데모 |
|---|---|---|---|
| 마켓플레이스 이름 | claude-plugins-official | claude-community | claude-code-plugins |
| 저장소 | anthropics/claude-plugins-official | anthropics/claude-plugins-community | anthropics/claude-code |
| 내용 | Anthropic이 관리하는 플러그인과 파트너 플러그인 | 작성자가 Anthropic에 제출한 서드파티 플러그인 | 플러그인이 무엇을 담을 수 있는지 보여 주는 예제 |
| 추가 방법 | 첫 대화형 세션에서 자동 추가 | /plugin marketplace add anthropics/claude-plugins-community | /plugin marketplace add anthropics/claude-code |
이 세 곳에 없는 인기 플러그인도 많습니다. 작성자가 자기 저장소에 marketplace.json을 두고 직접 배포하며, 이런 서드파티 마켓플레이스는 Anthropic이 검토하지 않습니다.
4. 설치 방법
4-1. 세션 안에서 설치
공식 마켓플레이스의 commit-commands를 예로 듭니다.
- Claude Code에서
/plugin install commit-commands@claude-plugins-official을 실행합니다. 바로 설치되지 않고 플러그인 상세 화면이 열립니다. 이름 없이/plugin만 실행하면 Discover 탭에서 검색할 수 있습니다. - Will install에서 플러그인이 추가하는 명령, 에이전트, 스킬, 훅, MCP·LSP 서버를 확인합니다.
- 설치 범위(scope)를 고릅니다.
- 설치 요약의 마지막 문장을 확인합니다.
Plugin is now active.이면 바로 쓸 수 있고,Run /reload-plugins to apply.이면 재로드가 필요합니다. /를 입력해/commit-commands:commit이 목록에 나오는지 확인합니다.
4-2. 설치 범위
범위는 플러그인을 누구에게 켤지를 정하며, 켜진 상태는 범위에 맞는 설정 파일의 enabledPlugins에 기록됩니다.
| 범위 | 대상 | 기록 위치 |
|---|---|---|
| User | 이 컴퓨터의 모든 프로젝트, 나만 | ~/.claude/settings.json |
| Project | 이 저장소의 모든 협업자 | .claude/settings.json (커밋 대상) |
| Local | 이 저장소, 나만 | .claude/settings.local.json |
같은 플러그인이 여러 범위에 설정되면 Local이 Project를, Project가 User를 덮어씁니다.
Project 범위의 주의점
.claude/settings.json을 커밋하면 협업자에게 플러그인이 켜지지만 협업자의 컴퓨터에 설치되지는 않습니다. 각자claude plugin install <name>@<marketplace> --scope project를 한 번 실행해야 합니다.
4-3. 서드파티 플러그인 설치
공식 목록에 없는 플러그인은 마켓플레이스를 먼저 추가합니다. Obsidian 창시자 Steph Ango(kepano)의 obsidian-skills는 README 기준으로 다음과 같이 설치합니다.
/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills마켓플레이스 추가와 설치를 한 번에 하는 방법도 있습니다. 세션에서는 /plugin install deploy-helper --marketplace your-org/plugins(Claude Code v2.1.275 이상), 셸에서는 claude plugin install deploy-helper --marketplace your-org/plugins(v2.1.292 이상)입니다.
4-4. 셸에서 설치
세션을 열지 않고 스크립트로 설치할 수도 있습니다. 기본 범위는 User이고, 설치한 플러그인은 다음 실행 때나 /reload-plugins로 로드됩니다.
claude plugin install formatter@your-org --scope project4-5. 팀 설정 파일로 배포
저장소의 .claude/settings.json에 마켓플레이스와 활성화할 플러그인을 적어 두면 팀이 같은 구성을 쓰게 할 수 있습니다.
{
"extraKnownMarketplaces": {
"obsidian-skills": {
"source": { "source": "github", "repo": "kepano/obsidian-skills" }
}
},
"enabledPlugins": {
"obsidian@obsidian-skills": true
}
}5. 설치 후 관리
/plugin의 Installed 탭에서 플러그인을 켜고 끄거나 업데이트, 제거합니다. 셸에서는 같은 일을 명령으로 합니다.
- 비활성화·활성화:
claude plugin disable <name>@<marketplace>,claude plugin enable <name>@<marketplace> - 제거:
claude plugin uninstall <name>@<marketplace> --scope project - 업데이트:
claude plugin update <plugin>@<marketplace>.claude-plugins-official을 비롯한 공식 이름의 마켓플레이스(일부 예외 있음)와 claude.ai에서 추가한 마켓플레이스는 자동 업데이트가 기본이고, 커뮤니티·서드파티·로컬 마켓플레이스는 기본이 꺼져 있습니다. - 마켓플레이스 관리:
claude plugin marketplace list,update <name>,remove <name>. 마켓플레이스를 제거하면 거기서 설치한 플러그인도 모두 제거됩니다. - 세션 반영: 설정을 바꾼 뒤에는
/reload-plugins를 실행합니다.
컨텍스트 비용
켜진 플러그인은 쓰지 않는 세션에서도 비용을 만듭니다. Claude가 스스로 호출할 수 있는 스킬·에이전트·명령의 이름과 설명이 매 턴 컨텍스트에 들어가기 때문입니다. 스킬 본문은 실제로 쓸 때만 로드됩니다. 비용은 이렇게 확인합니다.
- 설치 전:
/plugin install <name>@claude-plugins-official로 연 상세 화면이나 Marketplaces 탭에서 공식 마켓플레이스 플러그인의 Context cost를 봅니다. Discover 목록에서 연 상세 화면에는 나오지 않습니다. - 설치 후: 셸에서
claude plugin details <name>을 실행하면Always-on줄에 매 세션 추가되는 토큰 수가 나옵니다. - 정리: Installed 탭의 Not used recently 그룹이 쓰지 않는 플러그인을 알려 줍니다.
6. 주요 플러그인
공식 마켓플레이스의 목록은 자주 바뀌므로 /plugin의 Discover 탭이나 Claude Marketplace에서 최신 목록을 확인하세요. 아래는 공식 문서와 저장소 README에서 확인한 대표 플러그인입니다.
6-1. Anthropic 제공 플러그인
| 플러그인 | 하는 일 | 명령어 |
|---|---|---|
| commit-commands | 커밋, 푸시, PR 생성 Git 워크플로 자동화 | /commit, /commit-push-pr, /clean_gone |
| code-review | 여러 전문 에이전트와 신뢰도 점수로 오탐을 거르는 자동 PR 코드 리뷰 | /code-review |
| pr-review-toolkit | 주석, 테스트, 에러 처리, 타입 설계, 코드 품질을 나눠 보는 PR 리뷰 에이전트 모음 | /pr-review-toolkit:review-pr |
| feature-dev | 7단계로 진행하는 기능 개발 워크플로 | /feature-dev |
| security-guidance | 파일을 편집할 때 잠재적 보안 문제를 경고하는 훅 | 없음 (훅으로 동작) |
| frontend-design | 프론트엔드 작업에서 자동으로 호출되는 인터페이스 디자인 스킬 | 없음 (스킬로 동작) |
| hookify | 대화에서 원치 않는 동작을 분석해 커스텀 훅을 쉽게 생성 | /hookify |
| plugin-dev | 플러그인을 만들기 위한 툴킷 | /plugin-dev:create-plugin |
위 설명은 anthropics/claude-code의 플러그인 README 기준입니다. 이 중 상당수는 공식 마켓플레이스에도 같은 이름으로 있으므로, 중복 설치를 피하려면 @claude-plugins-official로 설치합니다.
6-2. 코드 인텔리전스(LSP) 플러그인
언어 서버를 연결해 Claude가 편집 직후 타입 오류와 누락된 import를 진단받고, 텍스트 검색 대신 심볼 단위로 정의와 참조를 찾게 합니다. 플러그인에는 언어 서버가 포함되어 있지 않으므로 바이너리를 먼저 설치해야 합니다.
| 언어 | 플러그인 | 필요한 바이너리 |
|---|---|---|
| TypeScript·JavaScript | typescript-lsp | typescript-language-server |
| Python | pyright-lsp | pyright-langserver |
| Go | gopls-lsp | gopls |
| Rust | rust-analyzer-lsp | rust-analyzer |
| Java | jdtls-lsp | jdtls |
| C# | csharp-lsp | csharp-ls |
TypeScript라면 순서는 다음과 같습니다.
npm install -g typescript-language-server typescript/plugin install typescript-lsp@claude-plugins-official설치 후 Claude가 해당 언어 파일을 편집하면 Found N new diagnostic issues in M files 줄이 나타납니다. 나타나지 않으면 /plugin의 Errors 탭에서 Executable not found in $PATH 같은 메시지를 확인합니다. LSP 플러그인은 터미널 세션에서 동작하고 클라우드 세션에서는 동작하지 않습니다.
6-3. 서드파티 플러그인
- superpowers: 코딩 에이전트가 바로 코드를 쓰지 않고 요구사항 정리, 설계 합의, 계획 수립, 테스트 기반 구현, 리뷰 순서를 따르게 하는 스킬 모음입니다. brainstorming, writing-plans, test-driven-development, systematic-debugging 등이 있고 관련 상황에서 자동 활성화됩니다. README는
/plugin install superpowers@claude-plugins-official을 안내합니다. - obsidian (
obsidian-skills): Obsidian 볼트 작업용 스킬 6개입니다. obsidian-markdown(위키링크, 콜아웃, 속성 문법), obsidian-bases, json-canvas, obsidian-cli, defuddle(웹 페이지를 깨끗한 마크다운으로 추출), knap(데이터를 템플릿에 렌더링)이 들어 있습니다.
7. 상황별 활용
| 상황 | 쓸 플러그인 | 이유 |
|---|---|---|
| 변경 사항을 커밋하고 PR을 올릴 때 | commit-commands | 커밋, 푸시, PR 생성을 /commit-push-pr 하나로 처리 |
| PR을 리뷰할 때 | code-review, pr-review-toolkit | 전문 에이전트가 관점별로 검토하고 오탐을 줄임 |
| 새 기능을 구조적으로 만들 때 | feature-dev | 7단계 워크플로를 따라 설계부터 구현까지 진행 |
| 타입 오류를 편집 직후 잡고 싶을 때 | 언어별 *-lsp | 빌드 전에 진단을 받고 심볼 단위로 탐색 |
| 요구사항이 모호한 큰 작업을 시작할 때 | superpowers | 질문과 설계 합의를 거친 뒤 계획과 테스트 기반으로 진행 |
| 편집 중 보안 실수를 막고 싶을 때 | security-guidance | 파일 편집 시 보안 경고 훅 실행 |
| Obsidian 볼트의 노트를 다룰 때 | obsidian | 위키링크와 속성 문법을 정확히 작성하고 웹 문서를 마크다운으로 변환 |
| 같은 설정을 팀에 배포할 때 | 직접 만든 플러그인 + 사내 마켓플레이스 | 설정 파일에 마켓플레이스를 등록해 같은 구성을 설치 |
플러그인을 많이 켜는 것이 목표가 아닙니다. 켜진 플러그인은 모든 세션의 컨텍스트를 차지하므로, 현재 하는 일에 필요한 것만 켜 두고 나머지는 비활성화하는 편이 좋습니다.
8. 설치 전 보안 확인
플러그인은 내 권한으로 코드를 실행합니다
설치한 플러그인은 사용자 권한으로 임의의 코드를 실행할 수 있습니다. 훅은 셸 명령으로 실행되고, MCP·LSP 서버는 내 컴퓨터에서 프로세스로 시작됩니다. 권한 규칙과 샌드박스는 Claude의 도구 호출에만 적용되며 훅과 서버 프로세스는 포함하지 않습니다.
설치하기 전에 다음 순서로 확인합니다.
claude plugin marketplace list로 마켓플레이스의 출처를 확인합니다./plugin상세 화면의 Will install에서 훅과 MCP·LSP 서버가 있는지 봅니다.- 플러그인의
hooks/hooks.json,.mcp.json,bin/디렉터리를 직접 읽습니다. 상세 화면은 훅이 있다는 사실만 보여 주고 무엇을 실행하는지는 알려 주지 않습니다. - 마켓플레이스에 자동 업데이트가 켜져 있으면 검토한 파일이 나중에 바뀔 수 있다는 점을 감안합니다.
이름이 claude-plugins-official이나 claude-community인 마켓플레이스는 github.com/anthropics/ 저장소에서 온 것만 허용되므로, 서드파티가 Anthropic 마켓플레이스를 사칭할 수 없습니다. 다만 공식 마켓플레이스에도 파트너 플러그인이 많아서 마켓플레이스 이름이 곧 플러그인의 안전을 보증하지는 않습니다.
9. 이 블로그의 플러그인 구성
이 블로그를 만들고 글을 쓰는 환경에는 superpowers와 obsidian(obsidian-skills)이 켜져 있습니다. CLAUDE.md의 문법 규칙이 obsidian-markdown 스킬을 가리키는 것도 이 때문입니다. 반대로 글쓰기 절차와 문체 규칙은 tech-blog-writer라는 단독 스킬로 두었습니다. 이 프로젝트에서만 쓰는 구성은 단독으로, 여러 곳에 배포할 구성은 플러그인으로 나누는 기준을 따른 것입니다.
함께 읽으면 좋은 글
- Obsidian + Quartz v5 + Cloudflare Pages로 온톨로지 블로그 구축기: 이 글에서 다룬
obsidian-skills와CLAUDE.md규칙을 실제로 적용한 과정