스킬·플러그인 패키지로 만들어 팀에 배포하기

한눈에 요약

혼자 쓰는 스킬은 ~/.claude/skills/나 .claude/skills/에 두면 돼요. 여러 프로젝트·여러 사람에게 버전을 붙여 나눠 줄 때 플러그인으로 묶어요.
플러그인은 스킬·에이전트·훅·MCP 서버를 한 폴더에 담고 .claude-plugin/plugin.json으로 이름을 붙인 것이에요. 마켓플레이스(marketplace.json)는 플러그인 목록이 담긴 카탈로그이고, git 저장소 하나면 돼요.
배포 전에 claude plugin validate --strict로 형식을, claude plugin eval로 Claude가 실제로 그 스킬을 쓰는지를 확인해요. eval은 모델을 호출하니 비용이 들어요.
팀 배포는 저장소의 .claude/settings.json(프로젝트 단위) 또는 관리 설정(조직 단위)으로 해요. 모두에게 공개하려면 claude.ai/directory/manage의 제출 포털을 써요.
설치한 플러그인은 사용자 권한으로 코드를 실행해요. 만들 때도, 설치할 때도 그 점을 기준으로 검토하세요.

이 튜토리얼로 할 수 있게 되는 것

잘 불려오는 SKILL.md를 설계하고, 팀 공용 플러그인 폴더로 묶을 수 있어요.
claude plugin validate와 claude plugin eval로 배포 전에 품질을 확인할 수 있어요.
팀 마켓플레이스를 만들고, 저장소 설정이나 관리 설정으로 팀원에게 자동으로 깔리게 할 수 있어요.
Anthropic 디렉터리에 제출하는 경로와 준비물을 알 수 있어요.

먼저 알아둘 개념

용어	뜻
스킬	`SKILL.md`가 든 폴더예요. Claude가 설명(description)을 보고 필요할 때 불러오거나, `/이름`으로 직접 실행해요.
플러그인	스킬·에이전트·훅·MCP 서버를 한 단위로 묶은 폴더예요. 이름 접두사가 붙어서 `/플러그인:스킬`로 실행해요.
마켓플레이스	플러그인 목록과 가져올 위치가 적힌 카탈로그예요. 저장소에 `.claude-plugin/marketplace.json`이 있으면 돼요. 앱 스토어처럼 호스팅되는 서비스가 아니에요.
설치 범위	user(나, 모든 프로젝트), project(저장소 모두), local(나, 이 저장소만)이에요.
관리 설정	조직이 모든 기기에 내려보내는 설정이에요. 사용자가 못 바꿔요.

어떤 배포 방식을 고를까요?

방식	대상	필요한 것	업데이트
폴더·ZIP 전달	몇 사람	플러그인 폴더	자동 없음 (받은 사본을 씀)
팀 마켓플레이스	저장소에 접근할 수 있는 사람	git 저장소 + `marketplace.json`	사용자가 `claude plugin update`, 또는 자동 업데이트를 켬
조직 관리 설정	조직 전체	관리자 권한	정책으로 통제
Anthropic 디렉터리	claude.ai·Cowork·Claude Code 사용자 누구나	GitHub 저장소 + 유료 claude.ai 플랜, 심사	새 버전이 심사 후 반영

단계별 따라하기

0/7 완료

SKILL.md를 설계 원칙에 맞게 썼어요
플러그인 폴더와 plugin.json을 만들고 --plugin-dir로 로드해 봤어요
claude plugin validate --strict를 통과했어요
eval 케이스를 만들고 비용 상한을 정해 실행했어요
마켓플레이스를 만들어 로컬에서 설치까지 해 봤어요
GitHub에 올리고 저장소 설정으로 팀원에게 안내했어요
(선택) 조직 관리 설정이나 디렉터리 제출을 검토했어요

SKILL.md 설계하기

Claude Code 문서가 알려 주는 원칙을 정리하면 이래요.

원칙	이유
`description` 맨 앞에 핵심 용도를 쓰고, 사용자가 실제로 쓰는 말(트리거 문구)을 넣어요	`description`과 `when_to_use`를 합친 글이 스킬 목록에서 1,536자에서 잘려요. Claude는 이 목록을 보고 고르기 때문에 모호하면 안 불려와요.
파일 첫 줄이 `---`여야 해요	아니면 프런트매터가 본문으로 취급돼요. YAML이 틀려도 오류 없이 필드가 비어서 로드돼요(조용한 실패).
`SKILL.md`는 500줄 미만으로, 긴 자료는 같은 폴더의 다른 파일로 분리해요	스킬이 로드되면 본문이 대화 내내 컨텍스트에 남아서 줄마다 반복 비용이에요. 참고 파일은 필요할 때만 읽혀요.
“한 번 하라”보다 “항상 이렇게 하라”로 써요	Claude는 이후 턴에서 파일을 다시 읽지 않아요. 계속 지켜야 할 규칙은 상시 지침 문체가 맞아요.
부작용이 있는 스킬(배포, 커밋)은 `disable-model-invocation: true`	사용자가 `/이름`으로 부를 때만 실행돼요. 이 스킬의 설명은 컨텍스트에도 안 실려요.
`allowed-tools`는 필요한 명령만, 가능하면 `${CLAUDE_SKILL_DIR}`로 번들 스크립트 지정	스킬을 호출한 그 턴에만 사전 승인돼요(다음 사용자 메시지에서 해제). 다른 도구를 막아 주는 기능은 아니에요.
!`명령`으로 최신 정보를 넣고, 실패할 수 있는 명령은 끝에 `\|\| true`를 붙여요	명령이 실패하면 스킬 호출 전체가 중단돼요. 명령당 기본 2분 제한이 있어요.
입출력 예시를 넣고, 지어내기 금지 규칙을 적어요	형식이 안정되고 환각이 줄어요.

팀 PR 설명 스킬 예시예요. plugins/team-kit/skills/pr-description/SKILL.md로 저장해요.

---
name: pr-description
description: 변경 사항을 팀 형식의 PR 설명(요약, 변경 내용, 테스트 방법, 위험 요소)으로 정리한다. PR 설명, 풀 리퀘스트 본문, 변경 요약을 써 달라고 할 때 사용한다.
---

# PR 설명 작성

변경 내용을 받으면 아래 순서의 마크다운으로 작성한다.

1. `## 요약` — 한두 문장
2. `## 변경 내용` — 파일 또는 모듈 단위 목록
3. `## 테스트 방법` — 재현 가능한 명령
4. `## 위험 요소` — 없으면 "없음"

입력에 없는 사실(테스트 결과, 이슈 번호)은 지어내지 않고 "확인 필요"라고 쓴다.

부작용이 있는 스킬은 이렇게 써요. 직접 호출만 허용하고, 필요한 git 명령만 사전 승인해요.

---
name: release-notes
description: 마지막 태그 이후 커밋으로 릴리스 노트 초안을 만든다. 릴리스 노트, 변경 로그 정리를 요청할 때 사용한다.
disable-model-invocation: true
allowed-tools: Bash(git log *)
---

## 마지막 태그 이후 커밋

!`git log --oneline "$(git describe --tags --abbrev=0)"..HEAD || true`

## 지침

위 커밋을 기능, 수정, 기타로 묶어 한국어 릴리스 노트 초안을 쓴다. 커밋이 없으면 "변경 없음"이라고 답한다.

플러그인 폴더 만들기

마켓플레이스 저장소 하나에 플러그인을 plugins/ 아래 여러 개 두는 구조로 만들어요.
```
team-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── team-kit/
        ├── .claude-plugin/
        │   └── plugin.json
        ├── skills/
        │   ├── pr-description/SKILL.md
        │   └── release-notes/SKILL.md
        ├── .mcp.json            (선택: MCP 서버 번들)
        └── evals/               (선택: claude plugin eval 케이스)
```
skills/, agents/, hooks/, .mcp.json은 플러그인 루트에 두세요. .claude-plugin/ 안에 넣으면 로드되지 않아요.

plugins/team-kit/.claude-plugin/plugin.json이에요.
```
{
  "name": "team-kit",
  "displayName": "팀 도구 모음",
  "description": "우리 팀의 PR 설명 작성 스킬 모음",
  "version": "1.0.0",
  "author": { "name": "Platform Team" },
  "repository": "https://github.com/your-org/team-marketplace",
  "license": "MIT"
}
```
- name은 필수예요. 공백 없는 kebab-case로 정하고 한 번 정하면 바꾸지 마세요. 이름이 바뀌면 이미 설치한 사람의 설치가 끊겨요. 표시 이름은 displayName으로 바꿔요.
- version을 적으면 올리기 전까지 사용자가 업데이트를 못 받아요. 푸시해도 claude plugin update가 “already at the latest version”이라고 답해요. 릴리스마다 올리거나, git 마켓플레이스에서는 version을 생략해 커밋 SHA를 버전으로 쓰는 방법이 있어요.
- 스킬은 /team-kit:pr-description처럼 플러그인 이름이 접두사로 붙어요.
MCP 서버 번들하기(선택). 5. MCP 서버 직접 만들기에서 만든 서버를 같이 배포하려면 플러그인 루트의 .mcp.json에 넣어요. 파일 경로는 ${CLAUDE_PLUGIN_ROOT}로 쓰라고 공식 문서가 안내해요. 서버 실행에 필요한 mcp 패키지는 사용자 컴퓨터에 이미 있어야 하니 README에 적어 두세요.
```
{
  "mcpServers": {
    "inventory": {
      "command": "python3",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server/server.py"]
    }
  }
}
```
번들 서버는 플러그인이 켜져 있는 모든 세션에서 같이 실행되고, 도구 이름은 mcp__plugin_<플러그인>_<서버>__<도구> 형태가 돼요.
검증하고 로컬에서 써 보기

형식부터 확인해요. --strict는 경고(알 수 없는 필드, 빠진 메타데이터)도 실패로 처리해서 CI에 알맞아요.
터미널 창
```
claude plugin validate --strict ./team-marketplace/plugins/team-kit
claude plugin validate --strict ./team-marketplace
```
각각 Validation passed가 나와야 해요. 이어서 설치 없이 한 세션에서만 로드해 봐요.
터미널 창
```
claude --plugin-dir ./team-marketplace/plugins/team-kit
```
세션에서 /team-kit:pr-description을 실행하거나, “getUser를 fetchUser로 바꾼 변경으로 PR 설명 써 줘”처럼 평소 말투로 요청해 보세요. 파일을 고친 뒤에는 /reload-plugins로 반영해요. 안 보이면 /plugin의 Errors 탭과 claude plugin list를 확인하세요.

이 프롬프트를 복사해서 붙여넣으세요
getUser 함수를 fetchUser로 이름을 바꾸고 호출부 3곳을 고쳤어. 이 변경으로 PR 설명 써 줘.

안 불려온다면 /team-kit:pr-description으로 직접 호출해 “안 불려오는 것”과 “불려오지만 결과가 이상한 것”을 나눠 보세요. /skills로 로드 여부도 볼 수 있어요.
claude plugin eval로 품질 확인하기

형식이 맞아도 Claude가 스킬을 안 고르거나 결과가 어긋날 수 있어요. claude plugin eval은 플러그인의 테스트 케이스를 실제로 돌려 점수를 매기고, 플러그인 없는 기준선과 비교해 줘요. Claude Code 2.1.269 이상이 필요해요.

실행마다 에이전트 호출과 채점 호출이 계정 사용량(또는 API 요금)으로 잡혀요. 기본값은 케이스마다 3번, 그리고 같은 횟수의 플러그인 없는 기준선이라서 케이스 하나가 6번 실행이에요. 처음에는 --ablation none(기준선 생략, 절반 비용)과 --runs 1로 돌리고, 항상 --max-cost-usd로 상한을 거세요. 플러그인을 믿을 수 있는 경우에만 실행하세요. eval은 내 권한으로 플러그인을 로드해 실행해요.

케이스는 evals/<케이스 이름>/ 폴더에 두어요. claude plugin eval init이 질문을 하며 만들어 주거나(대화형 세션), 직접 쓸 수도 있어요(claude plugin eval init --bare 이름은 빈 템플릿).

evals/pr-from-diff/prompt.md: 프런트매터에 실행 한도를, 본문에 사용자가 입력할 문장을 써요. 스킬 이름을 부르지 말고 평소 말투로 써야 “자연스러운 요청에도 불려오는지”를 볼 수 있어요.
```
---
max_turns: 5
allowed_tools: [Skill]
---

getUser를 fetchUser로 이름을 바꾸고 호출부 3곳을 고쳤어. 이 변경으로 PR 설명 써 줘.
```
evals/pr-from-diff/graders/skill-fired.md: 스킬이 실제로 호출됐는지(tool_used)를 봐요.
```
---
type: tool_used
tool: Skill
input_match: '"skill"\s*:\s*"(?:[\w-]+:)?pr-description"'
---
```
evals/pr-from-diff/graders/format.md: 답변에 네 개의 제목이 순서대로 있는지를 정규식(regex)으로 봐요. 정규식 채점은 호출 없이 같은 결과가 나와서 안정적이고 공짜예요.
```
---
type: regex
pattern: '## 요약[\s\S]*## 변경 내용[\s\S]*## 테스트 방법[\s\S]*## 위험 요소'
---
```
실행은 플러그인 폴더에서 해요.
터미널 창
```
cd team-marketplace/plugins/team-kit
claude plugin eval . --runs 1 --ablation none --max-cost-usd 2
```
결과 표에서 WITH(플러그인 사용 점수), W/OUT(플러그인 없는 점수), Δ(차이)를 봐요. 문서가 알려 주는 가장 흔한 첫 발견은 “Δ가 0에 가깝고 tool_used: Skill 채점이 실패”예요. Claude가 자연스러운 말에서 스킬을 고르지 않는다는 뜻이니 description을 고쳐 다시 돌려 보세요. 한 번 실행은 편차가 크니, 바꾼 효과는 기본 횟수(3회)로 다시 확인하세요.

CI에서는 첫 신뢰 확인을 건너뛰고(--trust-plugin) 결과를 JSON으로 저장하며 점수 미달이면 실패시켜요. 모델은 고정해서 점수를 비교 가능하게 해요.
터미널 창
```
claude plugin eval . \
  --trust-plugin \
  --json results.json \
  --threshold 0.8 \
  --model claude-sonnet-5-5 \
  --judge-model claude-haiku-5-5 \
  --no-publish \
  --max-cost-usd 20
```
종료 코드는 0이 통과, 1이 점수 미달·로드 실패 등, 2가 비용 상한 도달이나 인증 거부로 인한 부분 실행이에요. 매 변경마다 도는 가벼운 검사에는 judge 없이 도는 regex·tool_used 채점기만 두면 비용이 안 늘어요. 일반 평가 방법은 8. 평가(evals)로 LLM 결과 품질 관리하기를 보세요.

위 eval 케이스의 파일 구조와 채점기 옵션은 공식 문서(plugin-evals)를 따랐어요. 이 편을 쓰며 claude plugin validate는 실제로 돌려 통과를 확인했지만, claude plugin eval은 비용 때문에 실행하지 않았어요. 점수 예시는 싣지 않았어요.
마켓플레이스 만들기

마켓플레이스 저장소 루트의 .claude-plugin/marketplace.json이에요. name, owner, plugins가 필수예요.
```
{
  "name": "team-marketplace",
  "description": "우리 팀 플러그인",
  "owner": { "name": "Platform Team" },
  "plugins": [
    {
      "name": "team-kit",
      "source": "./plugins/team-kit",
      "description": "PR 설명 작성 스킬 모음"
    }
  ]
}
```
- 상대 경로 source는 마켓플레이스 루트(.claude-plugin/이 있는 폴더) 기준이고 ..는 쓸 수 없어요.
- 항목의 name과 plugin.json의 name을 같게 하세요. 다르면 설치 때 not found가 나요.
- 플러그인이 다른 저장소에 있으면 source에 { "source": "github", "repo": "your-org/team-kit" } 같은 객체를 써요. git-subdir(모노레포 하위 폴더), url, archive(zip), npm 소스도 있어요.
- 공식 마켓플레이스 이름(예: claude-plugins-official)은 쓸 수 없어요.
로컬에서 설치까지 해 보고 확인해요.
터미널 창
```
claude plugin marketplace add ./team-marketplace
claude plugin install team-kit@team-marketplace
claude plugin list
claude plugin details team-kit
```
details는 구성요소 목록과 세션마다 더해지는 토큰 비용 추정을 보여 줘요. 이 예제는 상시 비용이 약 114토큰이었어요(스킬 하나 기준, 직접 실행). 스킬을 늘릴수록 이 숫자가 커지니, 안 쓰는 스킬은 /skill-doctor로 찾아서 정리하세요.

로컬 경로로 추가한 마켓플레이스는 파일을 고치면 다음 세션 시작이나 /reload-plugins에서 바로 반영돼요. 호스팅된 마켓플레이스는 사용자가 사본을 받으므로, 위의 version 규칙이 적용돼요.
팀에 배포하기: 저장소 단위

team-marketplace를 GitHub에 올려요. 비공개 저장소면 마켓플레이스도 비공개라서, 저장소를 clone할 수 있는 사람만 설치할 수 있어요.

팀원에게 안내할 명령은 두 줄이에요.
터미널 창
```
claude plugin marketplace add your-org/team-marketplace
claude plugin install team-kit@team-marketplace
```
Claude Code 2.1.292 이상에서는 한 줄로도 돼요: claude plugin install team-kit --marketplace your-org/team-marketplace. 업데이트는 claude plugin update team-kit@team-marketplace예요.

팀 코드 저장소에서 자동으로 권하기. 팀이 쓰는 코드 저장소의 .claude/settings.json에 아래를 커밋하면 마켓플레이스 등록과 플러그인 활성화를 저장소 안에서 선언할 수 있어요.
```
{
  "extraKnownMarketplaces": {
    "team-marketplace": {
      "source": { "source": "github", "repo": "your-org/team-marketplace" }
    }
  },
  "enabledPlugins": {
    "team-kit@team-marketplace": true
  }
}
```
적용 조건과 한계가 있어요(공식 문서).
- extraKnownMarketplaces는 팀원이 폴더 신뢰(workspace trust) 대화상자를 수락한 폴더에서만 적용돼요. 미신뢰 폴더에서는 메시지 없이 무시돼요.
- 마켓플레이스 안에 상대 경로로 든 플러그인은 그대로 로드돼요. 플러그인이 외부 저장소를 가리키면 팀원이 각자 claude plugin install team-kit@team-marketplace --scope project를 한 번 해야 해요. 그 전에는 “enabled in project settings but isn’t installed”로 보여요.
- claude -p나 CI에서는 설치가 백그라운드로 진행돼서 첫 턴에 플러그인이 빠질 수 있어요. 이럴 때는 환경변수 CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1로 설치를 기다리게 해요.
- 비공개 마켓플레이스를 CI에서 설치하려면 읽기 권한이 있는 토큰을 GH_TOKEN으로 내보내고 gh auth setup-git을 실행하세요. GitHub Actions의 기본 토큰은 그 워크플로의 저장소에만 접근해요. 토큰은 저장소 시크릿에 두세요.
- 클라우드 세션(claude.ai/code)은 내 컴퓨터의 설정에 있는 플러그인을 로드하지 않아요.
자동 업데이트는 마켓플레이스마다 사용자 쪽 설정이에요. 서드파티(우리 팀 포함) 마켓플레이스는 기본이 꺼짐이라서, 팀원이 /plugin에서 켜거나 관리 설정의 autoUpdate로 정해요.

릴리스 표시. 다른 플러그인이 버전 범위로 내 플러그인에 의존하는 경우에는 git 태그가 필요해요. 플러그인 폴더에서 claude plugin tag --push를 실행하면 {이름}--v{버전} 태그를 만들어 푸시해요(--dry-run으로 먼저 확인).

팀에 배포하기: 조직 관리 설정

조직 전체에 강제하려면 관리 설정(managed settings)을 써요. 전달 방식은 세 가지예요.

방식	설명
서버 관리 설정	claude.ai 관리자 화면 조직 설정(Organization settings) > Claude Code > 관리 설정(Managed settings)에 JSON을 넣어요. Owner 권한이 필요해요.
MDM	macOS plist, Windows 레지스트리로 배포해요.
관리 설정 파일	시스템 경로의 `managed-settings.json`이에요.

마켓플레이스를 등록하고 플러그인을 강제 설치하는 예시예요(공식 문서 예시를 우리 이름으로 바꿨어요).

{
  "extraKnownMarketplaces": {
    "team-marketplace": {
      "source": { "source": "github", "repo": "your-org/team-marketplace" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "team-kit@team-marketplace": true
  }
}

사용자가 개인 설정에서 꺼도 관리 설정이 우선해서 계속 로드돼요. 반대로 enabledPlugins에서 false로 두면 모든 범위에서 막고 목록에서도 숨겨요. 제한용 키도 있어요.

키	역할
`strictKnownMarketplaces`	허용할 마켓플레이스 소스 목록이에요. `[]`면 공식 마켓플레이스까지 전부 막아요.
`blockedMarketplaces`	차단 목록이에요. 허용 목록보다 먼저 검사해요.
`disableSideloadFlags`	`--plugin-dir`, `--plugin-url` 같은 임의 로드를 막아요.
`strictPluginOnlyCustomization`	플러그인·관리 설정이 아닌 곳의 스킬·에이전트·훅·MCP 서버를 막아요.
`syncClaudeAiPlugins`	`false`면 claude.ai 계정에서 동기화된 플러그인을 내려받지 않아요.

여러 키를 쓸 때 주의할 점이에요.

서버 관리 설정이 정책 키를 하나라도 보내면, 기본값에서는 MDM·파일의 플러그인 키는 무시돼요. 둘을 같이 쓰려면 managedSourcesBehavior를 "merge"로 해요.
허용 목록(strictKnownMarketplaces)을 쓰면 ~/.claude/skills/의 플러그인이 로드되지 않을 수 있어요. 유지하려면 { "source": "skills-dir" }를 목록에 넣어요.
허용 목록은 마켓플레이스를 등록해 주지 않아요. 등록은 extraKnownMarketplaces가 하고, 등록할 소스는 허용 목록을 통과해야 해요.
부서별로 다른 정책은 서버 관리 설정으로는 안 돼요(조직 전체에 하나). 부서별 MDM 파일이나 게이트웨이 정책을 써요.
설치·로드 현황은 OpenTelemetry 이벤트(claude_code.plugin_installed, claude_code.plugin_loaded)와 Enterprise의 Analytics API로 볼 수 있어요.

claude.ai 조직 설정의 Plugins & skills에서 구성원 계정에 플러그인을 켜면, 그 플러그인이 Claude Code에는 <이름>@synced로 전달돼요. 이것은 위의 관리 설정 키와는 별개의 경로예요. 스킬 단위 공유는 C8의 공유 방법도 보세요.

(선택) Anthropic 디렉터리에 제출하기

팀을 넘어 누구나 설치하게 하려면 개발자 포털에 제출해요. 심사를 거치고, 통과하면 claude.ai와 Cowork, 그리고 계정 동기화를 통해 Claude Code 사용자에게 가요.

준비물	내용
GitHub 저장소	플러그인이 든 저장소예요. claude.ai에 GitHub 계정을 연결해야 하고, 그 계정이 저장소에 푸시할 수 있어야 해요.
유료 claude.ai 플랜	Pro/Max는 본인 계정으로, Team/Enterprise는 Owner가 제출해요. Enterprise는 역할로 Directory 권한을 줄 수 있어요.
정책 준수	Anthropic Software Directory Terms와 Policy를 지켜야 해요.
사전 점검	`claude plugin validate ./플러그인 --strict`를 통과하고, 공식 pre-submission checklist를 확인해요. 포털의 Validate 단계는 CLI보다 검사가 더 많아요.

제출 흐름이에요(2026-10-11 공식 문서 기준).

claude.ai/directory/manage에서 Submit new > Plugin bundle
Source 단계에서 저장소, 플러그인 폴더(저장소 루트가 아니라면), 추적할 브랜치나 태그를 넣고 Validate
Listing details(plugin.json과 README에서 읽어 와요), Data handling(개인정보 수집·저장·전송 여부), Compliance 단계를 채워요
Submit for review

심사 뒤의 동작도 알아 두세요.

버전마다 검증과 보안 스캔을 하고, 통과하면 게시할 수 있어요. 검토자 확인이 필요한 버전은 보류돼요. 게시는 기본적으로 Anthropic 검토자가 해요.
이후에는 추적 브랜치에 병합하면 새 커밋을 스캔하고 게시해요. plugin.json에 version을 적었다면 릴리스마다 올리세요.
비공개 저장소로도 제출할 수 있어요. 이때 소스가 Anthropic에 업로드되어 스캔되고 검토자에게 보여요. 게시 전에는 공개로 바꿔야 해요.
조직당 24시간에 제출 10건 제한이 있어요.
플러그인이 참조하는 원격 MCP 서버가 직접 만든 것이라면, 서버도 MCP connector로 따로 제출해야 해요.
Anthropic 공식 마켓플레이스(claude-plugins-official)는 이 포털 제출을 받지 않아요.

빠른 참조표

자주 쓰는 `claude plugin` 명령

명령	용도
`claude plugin init <이름> [--with skills ...]`	`~/.claude/skills/<이름>/`에 플러그인을 만들어 매 세션 자동 로드해요
`claude --plugin-dir <경로>`	설치 없이 한 세션만 플러그인을 로드해요 (`/reload-plugins`로 반영)
`claude plugin validate [--strict] <경로>`	플러그인 또는 마켓플레이스의 형식을 검사해요
`claude plugin eval [대상]`	케이스를 돌려 점수와 기준선 대비 차이(Δ)를 줘요. 비용이 들어요
`claude plugin marketplace add <소스>`	마켓플레이스를 등록해요 (`owner/repo`, URL, 경로)
`claude plugin install <이름>@<마켓플레이스>`	설치해요 (`--scope project`로 저장소에 공유)
`claude plugin update <이름>@<마켓플레이스>`	새 버전으로 올려요 (재시작 필요)
`claude plugin list` / `details <이름>`	설치 목록과 구성요소·토큰 비용을 봐요
`claude plugin disable` / `enable` / `uninstall`	끄기 / 켜기 / 제거
`claude plugin tag [--push]`	`{이름}--v{버전}` 릴리스 태그를 만들어요
`claude plugin marketplace remove <이름>`	마켓플레이스를 제거해요 (그 플러그인도 함께 제거)

파일 위치 요약

파일	위치
플러그인 매니페스트	`<플러그인>/.claude-plugin/plugin.json`
스킬	`<플러그인>/skills/<이름>/SKILL.md`
에이전트·훅·MCP	`<플러그인>/agents/`, `hooks/hooks.json`, `.mcp.json`
마켓플레이스	`<저장소>/.claude-plugin/marketplace.json`
저장소 단위 팀 설정	`<코드 저장소>/.claude/settings.json`
평가 케이스	`<플러그인>/evals/<케이스>/prompt.md` + `graders/*.md`

스킬 점검 명령 (세션 안)

명령	확인할 것
`/skills`	로드된 스킬 목록
`/skill-doctor`	스킬별 컨텍스트 비용과 호출 이력, 안 쓰는 스킬
`/reload-plugins`	디스크에서 고친 내용 반영
`/plugin`	Installed·Errors·Marketplaces 탭

자주 막히는 지점

플러그인은 로드되는데 스킬이 안 보여요

원인: skills/를 .claude-plugin/ 안에 넣었거나, 매니페스트의 skills 경로가 SKILL.md가 든 폴더를 가리키지 않아요.
해결: skills/를 플러그인 루트로 옮기고 /reload-plugins를 실행하세요. /plugin의 Errors 탭에 원인이 나와요.

푸시했는데 팀원이 새 버전을 못 받아요

원인: plugin.json에 version을 적어 두고 올리지 않았어요. 이 경우 claude plugin update가 “already at the latest version”이라고 답해요.
해결: 릴리스마다 version을 올리거나, git 마켓플레이스에서는 version을 생략해 커밋 SHA를 버전으로 쓰세요. 서드파티 마켓플레이스는 자동 업데이트도 기본이 꺼져 있으니 팀원이 켜거나 claude plugin update를 실행해야 해요.

설치할 때 `Plugin "…" not found in marketplace`가 나요

원인: 마켓플레이스 항목의 name과 plugin.json의 name이 달라요. 또는 source 경로가 마켓플레이스 루트 기준이 아니에요.
해결: 두 이름을 같게 하고, source는 ./plugins/team-kit처럼 루트에서 시작하는 상대 경로로 쓰세요. claude plugin validate가 .. 경로는 잡아 줘요. 없는 폴더는 설치할 때야 오류가 나요.

스킬이 있는데 Claude가 자동으로 안 써요

원인: description이 모호하거나 핵심 용도가 뒤쪽에 있어요. 또는 disable-model-invocation: true가 붙어 있어요.
해결: 사용자가 실제로 쓰는 말을 넣어 앞부분을 다시 쓰고, claude plugin eval의 tool_used: Skill 채점으로 확인하세요. /이름 직접 호출이 잘 되는지 보면 원인이 나뉘어요.

저장소 설정에 마켓플레이스를 넣었는데 팀원에게 안 깔려요

원인: 팀원이 그 폴더의 신뢰 대화상자를 수락하지 않았거나, 플러그인이 외부 저장소를 가리켜 각자 설치가 필요해요.
해결: 신뢰를 수락하게 안내하고, 외부 소스 플러그인이면 claude plugin install … --scope project를 한 번 실행하게 하세요.

`claude plugin eval` 비용이 예상보다 커요

원인: 케이스 수 x 3회 x 2(기준선)에 채점 호출이 더해져요.
해결: --runs 1과 --ablation none으로 줄이고, --max-cost-usd로 상한을 걸고, 가능한 채점은 regex·tool_used로 바꾸세요. 비용 상한에 닿으면 종료 코드 2와 부분 결과가 나와요.

실전 팁

작게 시작해서 늘리세요. 스킬 하나, 케이스 하나, 팀원 한 명에게서 시작해요. 스킬이 늘수록 모든 세션의 시작 비용도 늘어요.
스킬은 배포 전에 평가로, 배포 후에는 사용량으로 보세요. /skill-doctor와 claude plugin details로 안 쓰는 스킬을 정리하세요.
이름은 처음부터 신중하게. 플러그인 이름은 나중에 못 바꿔요. 정말 바꿔야 하면 마켓플레이스의 renames로 기존 설치를 옮겨 주세요.
서드파티 마켓플레이스는 허용 목록으로. 조직에서는 strictKnownMarketplaces로 회사 마켓플레이스만 허용하는 구성을 검토하세요.
비밀 값은 플러그인에 넣지 마세요. API 키와 토큰은 사용자 환경변수나 저장소 시크릿에 두고, 코드와 .mcp.json에는 ${VAR}만 쓰세요.
코드 예제의 검증 범위. 이 편의 JSON·마크다운 예제는 공식 문서 기준이며 2026-10-11에 claude plugin validate --strict로 형식을 검증했고, 로컬 마켓플레이스 추가와 설치까지 확인했어요. claude plugin eval은 실행하지 않았어요.

다음에 볼 튜토리얼

C8. 스킬 — 스킬의 기본과 claude.ai 업로드, 공유 방법
5. MCP 서버 직접 만들어 Claude에 연결하기 — 플러그인에 번들할 MCP 서버 만들기
8. 평가(evals)로 LLM 결과 품질 관리하기 — 플러그인 eval을 넘어 일반적인 품질 관리
C14. Claude Code 핵심 기능 — 훅, 서브에이전트, 플러그인 설치 명령

출처

마지막 확인일: 2026년 10월 13일

Extend Claude with skills (Claude Code) code.claude.com
Plugins overview (Claude Code) code.claude.com
Create a Claude Code plugin code.claude.com
Create a marketplace code.claude.com
Publish and distribute a plugin code.claude.com
Manage Claude Code plugins for your organization code.claude.com
Test plugins with evals code.claude.com
Submit your plugin (Anthropic directory) claude.com
Connect Claude Code to tools via MCP code.claude.com

가격·한도·메뉴 이름은 자주 바뀌어요. 중요한 결정 전에는 위 공식 페이지에서 최신 내용을 다시 확인하세요.