Claude Code 플러그인 만들기

• 아직 아무것도 없음: 첫 번째 플러그인 만들기를 따른 다음 마켓플레이스 없이 개발 및 테스트 및 디버그를 따릅니다.
• .claude/ 아래에 파일이 이미 있음: 레이아웃을 배우기 위해 첫 번째 플러그인 연습을 한 번 수행한 다음 기존 .claude/ 설정 변환을 따릅니다.

​

플러그인을 사용할 시기 결정

• 파일이 가는 위치: 플러그인 루트라고 하는 플러그인의 자체 디렉토리 아래에 skills/, agents/, hooks/hooks.json 및 .mcp.json으로 저장됩니다.
• 이름 지정 방식: 플러그인 스킬 및 에이전트는 플러그인 이름을 접두사로 가져옵니다(예: /my-plugin:hello). 따라서 두 플러그인이 각각 hello 스킬을 제공할 수 있으며 충돌하지 않습니다.

​

첫 번째 플러그인 만들기

mkdir -p my-first-plugin/.claude-plugin

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

mkdir -p my-first-plugin/skills/hello

---
name: hello
description: Greet the user with a friendly message
disable-model-invocation: true
---

Greet the user warmly and ask how you can help them today.

claude plugin validate ./my-first-plugin

claude --plugin-dir ./my-first-plugin

/my-first-plugin:hello

​

플러그인 공유

• 몇 사람에게 직접 보내기: 플러그인의 디렉토리 또는 .zip을 제공하면 아무것도 게시할 필요가 없습니다. 마켓플레이스 없이 플러그인 공유를 참조하세요.
• 자신의 마켓플레이스에 나열: 팀원이 마켓플레이스를 한 번 추가하고 이름으로 플러그인을 설치하면 업데이트를 받습니다. 자신의 마켓플레이스를 통해 게시를 참조하세요.
• Anthropic의 커뮤니티 마켓플레이스에 제출: 나열되면 해당 마켓플레이스를 추가하는 모든 사람이 설치할 수 있습니다. 커뮤니티 마켓플레이스에 제출을 참조하세요.

​

플러그인 레이아웃

​

마켓플레이스 없이 개발

• --plugin-dir: 한 세션 동안 디렉토리 또는 .zip 아카이브를 로드합니다.
• --plugin-url: 한 세션 동안 URL에서 .zip 아카이브를 가져옵니다.
• claude plugin init: ~/.claude/skills/ 아래에 모든 세션에서 로드되는 플러그인을 스캐폴드합니다.

​

한 세션 동안 플러그인 로드

​

디렉토리 또는 .zip에서

claude --plugin-dir ./my-first-plugin --plugin-dir ./other-plugin.zip

​

플러그인 폴더에서

• 추가하는 하위 폴더는 매니페스트가 존재하면 새 플러그인으로 로드됩니다.
• 하위 폴더를 제거하면 해당 플러그인이 언로드됩니다.

​

URL에서

claude --plugin-url https://example.com/my-first-plugin.zip

​

환경 변수에서

​

모든 세션에서 플러그인 로드

​

claude plugin init으로 플러그인 스캐폴드

claude plugin init my-tool

​

스캐폴드된 플러그인의 스킬 이름

​

플러그인 로드 중지

​

저장소를 통해 플러그인 공유

​

테스트 및 디버그

1. 셸에서 claude plugin validate <path>를 실행합니다. 모든 스킬, 에이전트 및 명령 파일의 매니페스트 및 프론트매터를 확인하고 Validation passed에서 종료 코드 0으로 종료합니다. 경고에서도 실패하려면 --strict를 추가합니다. 종료 코드 및 디렉토리 처리는 플러그인 명령 참조에 있습니다.
2. 실행 중인 세션에서 /reload-plugins를 실행하여 디스크에서 만든 편집을 적용합니다. 개수가 있는 하나의 Reloaded: 줄을 출력합니다. 그런 다음 /plugin-name:skill 명령을 입력하거나 /plugin Installed 탭에서 플러그인을 찾아 스킬이 로드되었는지 확인합니다.
3. 동일한 세션에서 /plugin을 실행합니다. Installed 탭은 플러그인을 나열하고, 플러그인의 세부 정보에서 Claude Code가 찾은 구성 요소를 나열합니다. Errors 탭은 로드되지 않은 것과 이유(예: 매니페스트의 존재하지 않는 경로)를 나열합니다.
4. 셸로 돌아가서 claude plugin list를 실행합니다. 세션 전용 및 스킬 디렉토리 플러그인을 자체 섹션에 Status: ✔ loaded 또는 로드 오류와 함께 출력합니다. 개발 중인 플러그인을 포함하려면 plugin list 전에 --plugin-dir을 경로와 함께 전달합니다.

​

구성 요소 경로를 찾을 수 없음

​

--plugin-dir이 마켓플레이스 루트에서 plugins/ 아래의 플러그인을 로드하지 않음

​

플러그인이 로드되지만 스킬이 누락됨

​

userConfig 대화 상자가 나타나지 않음

​

플러그인이 Claude의 동작을 변경하는지 확인

​

기존 .claude/ 설정 변환

mkdir -p my-plugin/.claude-plugin

{
  "name": "my-plugin",
  "description": "Migrated from standalone configuration",
  "version": "1.0.0"
}

cp -r .claude/commands my-plugin/

cp -r .claude/agents my-plugin/

cp -r .claude/skills my-plugin/

mkdir -p my-plugin/hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }]
      }
    ]
  }
}

claude --plugin-dir ./my-plugin

• 스킬 및 에이전트: 두 세트는 충돌하지 않습니다. 플러그인의 스킬 및 에이전트는 my-plugin: 접두사를 가지기 때문입니다. /deploy 및 /my-plugin:deploy 모두 작동하며, Claude는 reviewer 및 my-plugin:reviewer를 두 개의 서브에이전트로 봅니다.
• 훅: 훅에는 접두사가 없으므로 설정 파일과 hooks/hooks.json 모두에 있는 훅은 이벤트가 발생할 때마다 두 번 실행됩니다.

​

다음 단계

• 플러그인 구성 요소: 에이전트, 훅, MCP 서버, LSP 서버 및 사용자 구성을 플러그인에 추가합니다
• 플러그인으로 evals 테스트: eval 사례를 작성하고 claude plugin eval로 실행하여 플러그인이 Claude의 동작을 얼마나 안정적으로 안내하는지 확인합니다
• 플러그인 게시: 버전을 지정하고, 마켓플레이스에 넣고, 커뮤니티 마켓플레이스에 제출합니다
• claude.ai 및 Cowork의 플러그인: 동일한 플러그인 폴더가 claude.ai 및 Cowork에 설치됩니다. 일부 구성 요소는 Claude Code 전용입니다
• 플러그인 매니페스트 참조: 모든 plugin.json 필드, 경로 규칙 및 디렉토리
• 스킬: 플러그인이 제공하는 스킬을 작성합니다
• Anthropic의 claude-code 저장소의 플러그인: feature-dev 및 code-review와 같은 이 페이지의 레이아웃의 완전한 작업 예제