플러그인은 스킬, 서브에이전트, 훅, MCP 서버를 한 묶음으로 설치하는 방식입니다. /plugin 명령으로 마켓플레이스에서 골라 설치하고, 설치할 때 적용 범위를 정합니다. 공식 문서 기준으로 설치 순서와 주의점을 정리했습니다.
직접 써보니
이 사이트를 개편할 때 superpowers, frontend-design, playwright 플러그인을 설치한 Claude Code로 작업했습니다. superpowers는 세션 시작 때 SessionStart 훅으로 스킬 사용 규칙 안내문을 대화에 자동으로 넣었고, 그래서 첫 요청에서 바로 brainstorming 스킬이 실행됐습니다. 플러그인 하나가 스킬과 훅을 함께 가져온다는 점이 이때 체감됐습니다.
플러그인이 하는 일
플러그인은 스킬, 에이전트, 훅, MCP 서버 같은 구성 요소를 디렉터리 하나로 묶어 한 번에 설치하는 단위입니다. 이름과 버전은 .claude-plugin/plugin.json에 적습니다.
스킬, 서브에이전트, 훅, MCP 서버는 플러그인 없이도 각자 설정해서 쓸 수 있습니다. 플러그인은 그것들을 묶어서 남이 만든 설정을 명령 하나로 받거나, 내 설정을 팀에 나눠줄 때 씁니다.
플러그인 안의 스킬은 /플러그인이름:스킬이름 형태로 나타납니다. 예를 들어 commit-commands 플러그인의 commit 스킬은 /commit-commands:commit입니다.
설치하는 순서
Claude Code는 터미널에서 처음 대화형 세션을 시작할 때 Anthropic 공식 마켓플레이스(claude-plugins-official)를 자동으로 등록합니다. 공식 플러그인은 마켓플레이스를 따로 추가하지 않아도 됩니다.
세션 안에서 /plugin install을 실행하면 바로 설치되지 않고, 해당 플러그인의 상세 화면이 열립니다. 무엇이 추가되는지 확인하고 범위를 고른 뒤 설치합니다.
/plugin install commit-commands@claude-plugins-official
설치 범위 고르기
- user: 이 컴퓨터의 모든 프로젝트에서 나만 씁니다. ~/.claude/settings.json에 기록됩니다.
- project: 이 저장소 작업자 모두에게 켜집니다. .claude/settings.json에 기록되며 커밋합니다. 다만 팀원도 자기 컴퓨터에서 한 번 설치해야 합니다.
- local: 이 저장소에서 나만 씁니다. .claude/settings.local.json에 기록됩니다.
- 같은 플러그인이 여러 범위에 있으면 local이 project를, project가 user를 이깁니다.
관리와 확인
/plugin을 실행하고 Tab으로 Installed 탭에 가면 켜기, 끄기, 업데이트, 제거를 할 수 있습니다. 셸에서는 claude plugin list, claude plugin disable 이름, claude plugin uninstall 이름으로도 됩니다.
설치 결과가 바로 안 보이면 /reload-plugins를 실행합니다. 공식 마켓플레이스 플러그인은 자동 업데이트가 기본으로 켜져 있지만, 실행 중인 세션에는 다음 세션부터 반영됩니다. 그 밖의 마켓플레이스는 기본으로 꺼져 있습니다.
플러그인이 맞지 않을 때, 그리고 비용
- 설정 하나만 필요하면 플러그인 없이 ~/.claude/skills/ 같은 폴더에 직접 두는 편이 단순합니다.
- 켜 둔 플러그인은 쓰지 않는 세션에서도 스킬 이름과 설명이 매 턴 컨텍스트에 들어갑니다. 안 쓰는 건 끄는 게 좋습니다.
- 플러그인은 훅과 MCP 서버를 통해 내 권한으로 코드를 실행할 수 있습니다. 모르는 마켓플레이스의 것은 상세 화면의 구성 목록을 읽고 설치하세요.
- /plugin은 claude -p 같은 비대화형 실행에서는 동작하지 않습니다. 그럴 땐 셸의 claude plugin install을 씁니다.
실제 예시
공식 마켓플레이스의 플러그인을 나 혼자 모든 프로젝트에서 쓰고 싶을 때
/plugin install commit-commands@claude-plugins-official
상세 화면이 열리고, 구성 요소를 확인한 뒤 user 범위(Install for you)를 선택하면 설치됩니다. 요약의 마지막 문장이 "Plugin is now active."이면 바로 쓸 수 있고, 리로드 안내가 나오면 /reload-plugins를 실행합니다. 이후 / 를 입력하면 /commit-commands:commit이 목록에 보입니다.
동료가 만든 비공식 마켓플레이스의 플러그인을 쓸 때
/plugin marketplace add your-org/plugins /plugin install deploy-helper@your-org
먼저 GitHub 저장소를 마켓플레이스로 등록하고, 그다음 이름@마켓플레이스 형태로 설치합니다. your-org와 deploy-helper는 예시 이름입니다. 공식 문서에는 한 줄로 합치는 /plugin install 이름 --marketplace 저장소 형식도 있으며, v2.1.275 이상이 필요합니다.
흔한 실수와 쓰지 말아야 할 때
- 프로젝트 범위로 설치하고 .claude/settings.json만 커밋하면 팀원 컴퓨터에는 설치되지 않습니다. 팀원이 claude plugin install 이름@마켓플레이스 --scope project를 한 번 실행해야 합니다.
- 마켓플레이스 주소를 https:// 없이 쓰면 GitHub owner/repo 약식으로 읽혀 실패합니다. 일반 git 주소는 https:// 를 붙이세요.
- 이름@마켓플레이스에서 @ 뒤는 마켓플레이스의 등록 이름입니다. 저장소 주소가 아닙니다.
- 마켓플레이스를 제거하면 거기서 설치한 플러그인이 모두 함께 제거됩니다.
- 플러그인을 많이 켜 두면 매 턴 컨텍스트와 사용량이 늘어납니다. Installed 탭의 "Not used recently" 목록으로 정리하세요.
자주 묻는 질문
플러그인과 스킬은 뭐가 다른가요?
스킬은 SKILL.md 하나로 된 지시문 단위이고, 플러그인은 스킬, 에이전트, 훅, MCP 서버를 묶어 설치하는 포장 단위입니다. 플러그인 안의 스킬은 /플러그인:스킬 이름으로 호출합니다.
플러그인을 잠깐 꺼두려면요?
/plugin의 Installed 탭에서 Space로 끄거나, 셸에서 claude plugin disable 이름을 실행합니다. 제거하지 않고 비활성화만 됩니다.
공식 마켓플레이스가 목록에 없습니다.
대화형 터미널 세션을 처음 시작할 때 자동 등록됩니다. 새 컴퓨터에서 스크립트로 먼저 설치한다면 claude plugin marketplace add anthropics/claude-plugins-official을 먼저 실행하세요.
2026-10-30 공식 문서와 대조함. 출처: Claude Code 문서: Install and manage plugins, Claude Code 문서: Plugins overview, anthropics/claude-plugins-official. 작성 원칙