Claude Code 공식 플러그인 설치와 자체 제작 가이드 (2026)

Claude Code 공식 플러그인 설치와 자체 제작 가이드 (2026)

Anthropic이 2026년 5월 중순 anthropics/claude-plugins-official 리포를 공개하면서, Claude Code 사용자가 슬래시 명령·외부 도구·워크플로 자동화를 모듈 단위로 끼워 넣을 길이 열렸다. 한국어 문서가 거의 없어 무작정 클론했다가 settings.json 경로에서 막히는 사례가 많다.

이 글은 Windows 11 + WSL2 Ubuntu, macOS 두 환경에서 공식 플러그인을 설치하고 자체 플러그인을 등록하는 워크플로를 명령어·디렉터리 트리·settings.json 예시로 정리한다. anthropics/skills와의 차이도 비교 박스로 분리한다.

 

📌 핵심 3줄 요약

• Claude Code 공식 플러그인은 ~/.claude/plugins/에 배치하고 settings.json의 plugins 키로 활성화한다.
• 플러그인은 명령·MCP 서버·훅을 묶은 배포 패키지, 스킬은 단일 디렉터리의 모델 행동 지침으로 역할이 다르다.
• 자체 플러그인은 plugin.json과 commands/, agents/ 폴더만 갖추면 5분 안에 로컬 등록할 수 있다.

 

1. anthropics/claude-plugins-official이란?

공식 리포의 발표 맥락

Anthropic이 Claude Code 1.x와 함께 공개한 플러그인 마켓플레이스의 레퍼런스 구현이다. 리포 최상위는 Anthropic이 직접 관리하는 plugins/와 외부 기여를 모은 external_plugins/로 나뉘며, 각 플러그인은 .claude-plugin/plugin.json을 매니페스트로 두고 슬래시 명령·서브에이전트·MCP 서버 정의를 묶는다. 마켓플레이스로 등록해 두면 CLI에서 한 줄로 설치할 수 있다.

왜 지금 챙겨야 하나

이전에는 .claude/commands/에 슬래시 명령 파일을 흩뿌리는 방식이었다. 플러그인 도입으로 여러 명령·서브에이전트·훅을 한 패키지로 묶어 팀 단위 배포가 가능해졌고, 마켓플레이스로 타인 플러그인을 한 줄로 가져올 수 있다.

 

2. 플러그인 vs 스킬: 무엇이 다른가

2026-05-17 글의 anthropics/skills와 이름이 비슷해 혼동하기 쉽다. 역할과 적재 위치가 완전히 다르다.

항목	플러그인 (claude-plugins-official)	스킬 (anthropics/skills)
역할	명령·에이전트·MCP 서버 묶음 배포	단일 작업용 모델 행동 지침
기본 경로	~/.claude/plugins/	~/.claude/skills/ 또는 프로젝트 .claude/skills/
매니페스트	.claude-plugin/plugin.json (이름·버전·components)	SKILL.md 프론트매터
호출 방식	슬래시 명령·자동 훅·MCP 연결	모델이 트리거 문구 매칭 시 자동 로드
배포 단위	마켓플레이스 패키지	개별 디렉터리

💡 핵심 포인트

• 플러그인 안에 스킬을 동봉할 수는 있지만, 스킬 단독으로 슬래시 명령을 노출하지는 못한다.
• 팀 표준 워크플로 배포는 플러그인, 모델 톤·도메인 지침은 스킬이 적합하다.

 

3. 공식 플러그인 설치 절차

3-1. 환경 준비

Claude Code CLI v1.6 이상에서 플러그인 매니페스트가 인식된다. Windows는 WSL2 Ubuntu 22.04를 권장한다. PowerShell도 동작하지만 심볼릭 링크 권한 문제가 있다.

3-2. 마켓플레이스 등록과 설치

공식 리포는 마켓플레이스로 한 번 등록한 뒤 슬래시 명령으로 개별 플러그인을 설치하는 흐름을 권장한다. macOS·WSL2 동일.

{
  "model": "claude-sonnet-4-7",
  "marketplaces": [
    {
      "name": "claude-plugins-official",
      "source": "github:anthropics/claude-plugins-official"
    }
  ]
}

~/.claude/settings.json에 위 블록을 추가하고 셸을 재시작한 뒤, Claude Code 안에서 슬래시 명령으로 플러그인을 설치한다.

claude
# Claude Code 안에서
> /plugin install hello-world@claude-plugins-official
> /plugin list

설치된 플러그인은 ~/.claude/plugins/ 아래에 캐시되고, .claude-plugin/plugin.json 매니페스트가 자동 로드된다. 리포 구조를 직접 살펴보고 싶다면 별도 위치에 클론해 둔다.

mkdir -p ~/src
cd ~/src
git clone https://github.com/anthropics/claude-plugins-official.git
ls claude-plugins-official
# plugins/  external_plugins/  .claude-plugin/  .github/  README.md

3-3. 실행 확인

새 셸에서 claude 실행 후 /help를 입력하면 설치된 플러그인이 노출한 슬래시 명령 목록이 보인다. 동작 검증은 가장 가벼운 플러그인을 골라 5분 안에 끝낼 수 있다.

 

4. 자체 플러그인 만들기

4-1. 디렉터리 구조

자체 플러그인을 만들 때는 공식 리포 구조를 그대로 따라가는 게 가장 빠르다. 최소 구성은 다음과 같다.

my-team-plugin/
├── .claude-plugin/
│   └── plugin.json
├── README.md
├── commands/
│   └── review-pr.md
├── agents/
│   └── code-reviewer.md
├── skills/
│   └── pr-summary/SKILL.md
└── .mcp.json

4-2. plugin.json 매니페스트

매니페스트는 .claude-plugin/plugin.json에 두고 이름·버전·설명을 선언한다. commands/·agents/·skills/ 폴더는 존재만 해도 Claude Code가 인덱싱한다.

{
  "name": "my-team-plugin",
  "version": "0.1.0",
  "description": "사내 코드 리뷰·PR 체크 자동화",
  "author": "team-devx",
  "requires": {
    "claude_code": ">=1.6.0"
  }
}

4-3. CLAUDE.md 통합과 로컬 테스트

프로젝트 CLAUDE.md에 "이 저장소는 /review-pr로 PR 본문을 생성한다" 한 줄을 추가하면, 합류한 팀원이 슬래시 명령 존재를 즉시 인지한다. 로컬 등록은 ~/.claude/plugins/ 아래에 심볼릭 링크를 걸어 둔다.

ln -s "$(pwd)/my-team-plugin" ~/.claude/plugins/my-team-plugin
claude
# 새 세션에서 /plugin list 와 /review-pr 노출 확인

 

5. 자주 부딪히는 트러블슈팅

• 슬래시 명령 중복 — ~/.claude/commands/의 같은 이름 파일을 삭제하거나 이동한다.
• Windows 경로 인식 실패 — PowerShell에서 ~ 확장이 안 될 수 있다. %USERPROFILE%\.claude\plugins\official처럼 전체 경로로 적는다.
• 권한 오류 — WSL2에서 /mnt/c 아래 클론하면 git 실행 비트 처리가 실패한다. 리눅스 홈(~/) 아래에서 클론한다.
• 플러그인 미로드 — claude --debug로 파싱 로그 확인. JSON 유효성·버전을 점검한다.
• MCP 서버 충돌 — 동봉 MCP가 mcp.json과 포트를 겹치면 실패한다. README 포트를 확인한다.

 

⚠️ 단점과 주의할 점

• 마켓플레이스 명령 문법은 1.6.x 마이너 업데이트마다 조금씩 바뀐다. /plugin install·/plugin list의 옵션이 갱신될 수 있어 릴리스 노트를 먼저 확인한다.
• 훅(hook)은 셸에서 임의 명령을 실행한다. 출처 미상 플러그인은 매니페스트와 hooks/를 읽고 설치한다.
• 팀 공유 시 전체 경로가 들어간 settings.json을 그대로 커밋하면 다른 OS에서 깨진다. 경로는 환경 변수로 외부화한다.

 

🚀 지금 바로 할 일

1. claude --version으로 1.6 이상 확인 후 ~/.claude/plugins/official에 공식 리포 클론.
2. settings.json에 plugins 키와 경로를 등록하고 /help로 명령 노출 확인.
3. examples/hello-world를 모방해 my-team-plugin 골격을 만들고 심볼릭 링크로 등록.

 

💬 의견

팀 워크플로를 플러그인으로 묶어 본 경험이 있다면 어떤 슬래시 명령부터 패키징했는지 댓글로 공유 부탁드린다. 다음 편은 마켓플레이스 공개 절차를 다룬다.

참고 자료와 함께 보면 좋은 글

1차 출처와 본 블로그의 관련 글입니다.

• anthropics/claude-plugins-official 공식 리포
• Claude Code 공식 문서
• Claude Code settings.json 레퍼런스
• anthropics/skills 공식 리포
• Model Context Protocol 공식 문서