Plugins

my-plugin/
├── .claude-plugin/
│   ├── plugin.json        # Manifest (REQUIRED)
│   └── marketplace.json   # For publishers
├── commands/              # Slash commands (auto-detected)
│   ├── build.md
│   └── deploy.md
├── agents/                # Custom agents (auto-detected)
│   └── test-runner.md
├── skills/                # Skills (auto-detected)
│   └── my-skill/
│       └── SKILL.md
├── output-styles/         # Output styles (auto-detected)
│   └── concise.md
├── hooks/
│   └── hooks.json         # Hook configurations
└── .mcp.json              # MCP servers (optional)

Complete schema

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What this plugin does",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/plugin",
  "repository": "https://github.com/org/plugin",
  "license": "MIT",
  "keywords": ["testing", "deployment"],
  "dependencies": [
    "other-plugin",
    "dep-plugin@other-marketplace"
  ],

  "commands": { ... },
  "agents": [ ... ],
  "skills": [ ... ],
  "outputStyles": [ ... ],
  "hooks": { ... },
  "mcpServers": { ... },
  "lspServers": { ... },
  "channels": [ ... ],
  "userConfig": { ... },
  "settings": { ... }
}

LSP Servers

Language server protocol for code intelligence.

Channels

Messaging channels for KAIROS assistant mode.

"channels": [{
  "server": "my-chat-server",
  "displayName": "Team Chat",
  "userConfig": {
    "CHANNEL_ID": {
      "type": "string",
      "title": "Channel ID"
    }
  }
}]

server must match a key in mcpServers. MCP server must declare claude/channel capability.

Settings

Configuration overrides when the plugin is enabled.

"settings": {
  "agent": {
    "my-agent": {
      "tools": ["Read", "Grep"],
      "model": "haiku"
    }
  }
}

Currently only the "agent" key is supported. Merged into the settings cascade when enabled.

Schema example

"userConfig": {
  "API_KEY": {
    "type": "string",
    "title": "API Key",
    "description": "Your API key",
    "required": true,
    "sensitive": true      // stored in Keychain
  },
  "MAX_RESULTS": {
    "type": "number",
    "title": "Max Results",
    "default": 10,
    "min": 1,
    "max": 100
  },
  "VERBOSE": {
    "type": "boolean",
    "default": false
  },
  "PROJECT_DIR": { "type": "directory" },
  "CONFIG_FILE": { "type": "file" }
}

extraKnownMarketplaces in settings.json

{
  "extraKnownMarketplaces": [
    {
      "type": "github",
      "repo": "org/plugins",
      "ref": "main"
    },
    {
      "type": "url",
      "url": "https://plugins.example.com/marketplace.json"
    },
    {
      "type": "npm",
      "package": "@org/marketplace"
    },
    {
      "type": "directory",
      "path": "/local/marketplace"
    },
    {
      "type": "settings",
      "name": "inline-marketplace",
      "plugins": [
        { "name": "my-plugin", "source": "./path" }
      ]
    }
  ]
}

Plugin MCP server naming

plugin:<pluginName>:<serverName>

Deduplicated against manually-configured servers — manual wins. Plugin MCP servers follow the same permission system as regular MCP tools.

Plugin ID format

// String
"my-plugin@my-marketplace"

// Object with options
{
  "id": "my-plugin@my-marketplace",
  "version": "^1.0.0",
  "required": true,
  "config": { "API_KEY": "value" }
}

Both parts validated: [a-z0-9][-a-z0-9._]*