Creating Custom Plugins

Package your .claude/ settings into a plugin when you want to share them with team members or deploy them across multiple repositories. This guide walks you through building your first plugin from scratch and migrating existing configurations.

첫 번째 플러그인 만들기

The simplest example: a plugin with a single skill.

1. 디렉토리와 매니페스트 생성

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

Create my-first-plugin/.claude-plugin/plugin.json:

{
  "name": "my-first-plugin",
  "description": "Basic example plugin",
  "version": "1.0.0",
  "author": {
    "name": "Team Name"
  }
}

Field	Required	Description
name	Yes	Unique identifier; also serves as skill namespace
description	-	Summary displayed in the /plugin view
version	-	Pins the plugin to this version on updates
author.name	-	Author name for display

2. 스킬 추가

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

my-first-plugin/skills/hello/SKILL.md:

---
name: hello
description: Greet the user warmly
disable-model-invocation: true
---

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

With disable-model-invocation: true, Claude will not invoke this skill autonomously; the user triggers it manually via /my-first-plugin:hello.

3. 유효성 검사

claude plugin validate ./my-first-plugin

Validation messages:

• Validation passed → Ready
• Validation passed with warnings → Loads, but fails with --strict
• Validation failed → Fix required

4. 테스트 실행

Load into a single session without registering a marketplace:

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

Inside the session:

/my-first-plugin:hello

--plugin-dir applies only to the current session and does not write to settings files.

플러그인 레이아웃

my-plugin/
├── .claude-plugin/
│   └── plugin.json         # Manifest
├── skills/                 # Skills (SKILL.md files)
├── commands/               # Legacy commands (.md files; skills/ recommended for new)
├── agents/                 # Subagents (.md files)
├── hooks/
│   └── hooks.json          # Hook handlers
├── .mcp.json               # MCP server configuration
└── .lsp.json               # LSP server configuration

컴포넌트 패키징

Agents

Place Markdown files under agents/:

---
name: security-reviewer
description: Security audit specialist agent
tools: Read, Grep, Glob
model: sonnet
---

Inspect for vulnerabilities based on OWASP Top 10 standards.

Agent names are also namespaced: my-plugin:security-reviewer

Hooks

Define event handlers in hooks/hooks.json:

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

MCP 서버

Create .mcp.json at the plugin root or define servers inline in plugin.json:

{
  "mcpServers": {
    "deploy-api": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
    }
  }
}

${CLAUDE_PLUGIN_ROOT} automatically resolves to the absolute install path of the plugin.

LSP 서버 (코드 인텔리전스)

Bundle language servers for code intelligence:

{
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": { ".go": "go" }
    }
  }
}

LSP Requirements

The required binary (e.g., gopls) must be installed on the user's system.

매니페스트 주요 필드

Key fields available in plugin.json:

Field	Description
defaultEnabled	When true (default), enabled immediately upon installation
dependencies	List of other plugins this plugin depends on
userConfig	Prompts users for configuration values upon installation
skills	Additional directories to scan beyond skills/
commands	Overrides default commands/ or provides inline commands
hooks	Additional hook configs beyond hooks/hooks.json

사용자 설정 (userConfig)

Prompt users for values during installation:

{
  "userConfig": {
    "api_token": {
      "type": "string",
      "title": "API Token",
      "description": "Authentication token for the deployment API",
      "sensitive": true
    }
  }
}

Setting sensitive: true masks input and stores it securely in system credential storage. Reference it in skills and agents as ${user_config.api_token}.

Eval로 플러그인 동작 검증 (v2.1.269+)

Validate plugin behavior automatically with claude plugin eval:

# Initialize eval cases interactively
claude plugin eval init

# Run full evaluation (default 3 runs)
claude plugin eval .

# Fail CI if score is below threshold
claude plugin eval . --threshold 0.8 --ci

Cost Awareness

Evals trigger real model invocations. Use -n to preview expected costs before executing.

기존 .claude/ 설정을 플러그인으로 변환

Migrate existing project-level .claude/ Skills, Hooks, and MCP settings directly into a plugin:

# 1. Create plugin structure
mkdir -p my-plugin/.claude-plugin

# 2. Copy components
cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

Move the hooks object from configuration into my-plugin/hooks/hooks.json.

Test the conversion:

claude --plugin-dir ./my-plugin

Verify skills with namespaced prefixes (e.g., /my-plugin:deploy). Once verified, remove original .claude/ files.

플러그인 초기화 스캐폴드

# Scaffold plugin under ~/.claude/skills/ (v2.1.157+)
claude plugin init my-tool

# Scaffold with skills structure included
claude plugin init my-tool --with skills

Plugins under ~/.claude/skills/ load automatically in all sessions without manual installation.

다음 단계

• Operating Marketplaces →
• Installing and Managing Plugins →