Meta Plugin Creator

Plugin Creator

Overview

Plugins are shareable packages that bundle skills, agents, commands, hooks, MCP servers, and LSP servers into installable units for Claude Code. A plugin requires only a .claude-plugin/plugin.json manifest at minimum; all other components are optional and auto-discovered from conventional directories at the plugin root.

When to use: Sharing functionality across projects or teams, distributing through marketplaces, versioning reusable agent capabilities, bundling MCP servers with skills.

When NOT to use: Single-project customizations (use .claude/ directory instead), quick experiments before packaging, personal workflows that do not need distribution.

Quick Reference

Common Mistakes

Delegation

• Plugin component creation: Build skills, agents, and commands following their respective standards
• Pattern discovery: Use Explore agent to find existing plugin patterns in the codebase
• Code review: Use Task agent for plugin structure validation

If the meta-skill-creator skill is available, delegate skill authoring within plugins to it.

Otherwise, recommend: npx skills add oakoss/agent-skills --skill meta-skill-creator

References

• Plugin manifest schema, directory structure, and component paths
• Skills, agents, commands, hooks, MCP servers, and LSP servers in plugins
• Installation scopes, environment variables, and publishing

Plugin Components

Skills

Skills are auto-discovered from skills/*/SKILL.md and provide context-aware capabilities that the agent loads when relevant.

skills/
└── code-review/
    ├── SKILL.md
    ├── references/
    └── scripts/

Each SKILL.md needs frontmatter with name and description:

---
name: code-review
description: Reviews code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
---

When reviewing code, check for:
1. Code organization and structure
2. Error handling
3. Security concerns
4. Test coverage

Skills support the full Agent Skills standard including reference files, scripts, and progressive disclosure.

Commands

Commands are slash commands defined as Markdown files in commands/. They are namespaced by plugin name: a command at commands/deploy.md in a plugin named my-tools is invoked as /my-tools:deploy.

---
description: Deploy to production
argument-hint: [environment]
---

Deploy the application to $ARGUMENTS environment.

The $ARGUMENTS placeholder captures any text the user provides after the command name.

Agents

Agents are specialized subagents defined as Markdown files in agents/. They appear in the /agents interface and can be invoked automatically based on task context.

---
description: Review code for security vulnerabilities
capabilities: ['security-analysis', 'vulnerability-detection']
tools: Read, Grep, Glob
model: haiku
---

# Security Reviewer

You review code for security issues. Focus on:

- Authentication and authorization flaws
- Input validation gaps
- Injection vulnerabilities
- Sensitive data exposure

Hooks

Hooks are event handlers that run automatically when specific events occur. Define them in hooks/hooks.json or inline in plugin.json.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
          }
        ]
      }
    ]
  }
}

Available Events

Hook Types

Event names are case-sensitive. Scripts must be executable (chmod +x).

MCP Servers

MCP servers connect the plugin to external tools via the Model Context Protocol. Define them in .mcp.json or inline in plugin.json.

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

Plugin MCP servers start automatically when the plugin is enabled and appear as standard tools in the agent toolkit.

LSP Servers

LSP servers provide real-time code intelligence (diagnostics, go-to-definition, find references). Define them in .lsp.json or inline in plugin.json.

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

Required LSP Fields

Optional LSP Fields

TypeScript LSP Example

Complete configuration showing initializationOptions and logging:

{
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".ts": "typescript",
      ".tsx": "typescriptreact",
      ".js": "javascript",
      ".jsx": "javascriptreact"
    },
    "initializationOptions": {
      "preferences": {
        "includeInlayParameterNameHints": "all"
      }
    },
    "loggingConfig": {
      "args": ["--log-level", "verbose"],
      "env": {
        "TSS_LOG": "-level verbose -file ${CLAUDE_PLUGIN_LSP_LOG_FILE}"
      }
    }
  }
}

The language server binary must be installed separately. The plugin configures how the agent connects to it.

Distribution

Installation Scopes

When installing a plugin, choose a scope that determines availability and visibility:

Install with a specific scope:

claude plugin install formatter@my-marketplace --scope project

Environment Variables

Plugin Path Variables

Always use ${CLAUDE_PLUGIN_ROOT} for paths to files within the plugin. Absolute paths break when the plugin is installed to a different location.

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

Auto-Update Configuration

Control auto-update behavior for plugins and Claude Code:

# Disable all auto-updates
export DISABLE_AUTOUPDATER=true

# Keep plugin updates, disable Claude Code updates
export DISABLE_AUTOUPDATER=true
export FORCE_AUTOUPDATE_PLUGINS=true

CLI Commands

Plugin Management

claude plugin install <plugin> [--scope user|project|local]
claude plugin uninstall <plugin> [--scope user|project|local]
claude plugin enable <plugin> [--scope user|project|local]
claude plugin disable <plugin> [--scope user|project|local]
claude plugin update <plugin> [--scope user|project|local|managed]
claude plugin validate .

Local Development

Test a plugin without installation:

claude --plugin-dir ./my-plugin

Load multiple plugins simultaneously:

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

Interactive UI

/plugin              # Open plugin manager

Tabs:

• Discover: Browse available plugins from connected marketplaces
• Installed: Manage installed plugins (enable, disable, uninstall)
• Marketplaces: Add/remove marketplaces
• Errors: View loading errors for troubleshooting

Debugging

claude --debug

Shows plugin loading details, manifest errors, component registration, and MCP server initialization.

Common Issues

Debug Checklist

1. Run claude --debug and check "loading plugin" messages 2. Verify component directories appear in debug output 3. Check file permissions on scripts 4. Test scripts manually outside Claude 5. Validate JSON syntax in all config files 6. Clear cache if needed: rm -rf ~/.claude/plugins/cache

Marketplace Publishing

Marketplace Structure

A marketplace is a git repository with .claude-plugin/marketplace.json:

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "metadata": {
    "description": "Internal development tools",
    "version": "1.0.0",
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting",
      "version": "2.1.0"
    }
  ]
}

Required Marketplace Fields

Plugin Entry Fields

Each entry requires name and source. The source can be:

Relative path (same repository):

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

GitHub repository:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0"
  }
}

Git URL:

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

The strict Field

When strict: true, fields in the marketplace entry merge with the plugin's own plugin.json.

Marketplace CLI

# Add a marketplace
/plugin marketplace add owner/repo
/plugin marketplace add https://gitlab.com/team/plugins.git
/plugin marketplace add ./local-marketplace

# Update marketplace catalog
/plugin marketplace update

# Install from marketplace
/plugin install my-plugin@marketplace-name

Team Distribution

Auto-Prompt Installation

Add marketplace to .claude/settings.json so team members are prompted to install:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "formatter@company-tools": true,
    "deploy-tools@company-tools": true
  }
}

Private Repository Access

For background auto-updates of private marketplace repos, set authentication tokens:

Manual installation and updates use existing git credential helpers.

Official Marketplace Plugins

Code Intelligence (LSP)

• pyright-lsp — Python type checking
• typescript-lsp — TypeScript/JavaScript
• rust-analyzer-lsp — Rust
• gopls-lsp — Go
• clangd-lsp — C/C++

External Integrations (MCP)

• github, gitlab — Source control
• atlassian, linear, notion — Project management
• slack — Communication
• vercel, firebase, supabase — Infrastructure

Development Workflows

• commit-commands — Git workflows
• pr-review-toolkit — PR review agents
• plugin-dev — Plugin development toolkit

Validation Checklist

Before publishing, verify:

• .claude-plugin/plugin.json exists with at least a name field
• All component directories are at plugin root, not inside .claude-plugin/
• All paths are relative, starting with ./
• Scripts are executable (chmod +x)
• All file references use ${CLAUDE_PLUGIN_ROOT}
• Version follows semver (MAJOR.MINOR.PATCH)
• claude plugin validate . passes with no errors

Plugin Anatomy

Directory Structure

A complete plugin follows this layout. Only .claude-plugin/plugin.json is required; all other directories are optional.

my-plugin/
├── .claude-plugin/           # Metadata directory
│   └── plugin.json          # Required: plugin manifest
├── skills/                   # Agent Skills (auto-discovered)
│   └── code-review/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Slash commands (auto-discovered)
│   ├── deploy.md
│   └── status.md
├── agents/                   # Subagents (auto-discovered)
│   ├── reviewer.md
│   └── tester.md
├── hooks/                    # Event hooks
│   └── hooks.json
├── .mcp.json                # MCP server config
├── .lsp.json                # LSP server config
├── scripts/                 # Utility scripts for hooks
│   └── format.sh
├── LICENSE
└── CHANGELOG.md

Only plugin.json belongs inside .claude-plugin/. All component directories (skills, commands, agents, hooks) go at the plugin root.

Plugin Manifest Schema

Minimal Manifest

{
  "name": "my-plugin"
}

The name field is the only required field. It must be kebab-case with no spaces.

Complete Schema

{
  "name": "my-plugin",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "lspServers": "./.lsp.json",
  "outputStyles": "./styles/"
}

Required Fields

Metadata Fields

Component Path Fields

Custom paths supplement default directories. If commands/ exists at the root, it is loaded in addition to any custom command paths.

Path Behavior Rules

All paths must be relative to the plugin root and start with ./. Multiple paths can be specified as arrays:

{
  "commands": ["./specialized/deploy.md", "./utilities/batch-process.md"],
  "agents": ["./custom-agents/reviewer.md", "./custom-agents/tester.md"]
}

Plugins cannot reference files outside their directory. Path traversal (../) does not work because plugins are copied to a cache directory during installation.

Version Management

Follow semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR: Breaking changes (incompatible API changes)
• MINOR: New features (backward-compatible additions)
• PATCH: Bug fixes (backward-compatible fixes)

Start at 1.0.0 for the first stable release. Pre-release versions like 2.0.0-beta.1 are supported for testing.

Complete Plugin Example

A deployment-tools plugin with commands, agents, skills, hooks, and MCP server:

deployment-tools/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── deploy.md
│   ├── rollback.md
│   └── status.md
├── agents/
│   └── deployment-checker.md
├── skills/
│   └── infrastructure/
│       ├── SKILL.md
│       └── scripts/
│           └── validate-config.py
├── hooks/
│   └── hooks.json
├── .mcp.json
├── scripts/
│   ├── pre-deploy.sh
│   └── notify.py
├── LICENSE
└── CHANGELOG.md

plugin.json

{
  "name": "deployment-tools",
  "version": "2.1.0",
  "description": "Deployment automation for Claude Code",
  "author": {
    "name": "DevOps Team",
    "email": "devops@company.com"
  },
  "repository": "https://github.com/company/deployment-tools",
  "license": "MIT",
  "keywords": ["deployment", "ci-cd", "automation"]
}

hooks.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/pre-deploy.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/notify.py"
          }
        ]
      }
    ]
  }
}

.mcp.json

{
  "mcpServers": {
    "deployment-api": {
      "command": "npx",
      "args": ["@company/deploy-mcp-server"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}",
      "env": {
        "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config.json"
      }
    }
  }
}

Plugin Caching

When installed, plugins are copied to a cache directory rather than used in-place. This means:

• Files outside the plugin directory are not available after installation
• Symlinks within the plugin directory are followed during copying
• All file references must use ${CLAUDE_PLUGIN_ROOT} to resolve correctly regardless of installation location

Using Symlinks for Shared Dependencies

If you need to reference external files or shared utilities, create symlinks inside the plugin directory. Symlinks are followed during the copy process:

# Inside plugin directory
ln -s /path/to/shared-utils ./shared-utils

The symlinked content becomes part of the plugin cache, allowing access to shared resources while maintaining plugin isolation.