# Add a plugin

Add a new plugin under `plugins/` and register it in both marketplace manifests:

- `.cursor-plugin/marketplace.json`
- `.claude-plugin/marketplace.json`

## 1. Create plugin directory

Create a new folder:

```text
plugins/my-new-plugin/
```

Tip: You can copy `plugins/humand-area-starter/` as a starting point.

Add the required manifest:

```text
plugins/my-new-plugin/.cursor-plugin/plugin.json
plugins/my-new-plugin/.claude-plugin/plugin.json
```

Example manifest (`.claude-plugin/plugin.json`):

```json
{
  "name": "my-new-plugin",
  "version": "0.1.0",
  "description": "Describe what this plugin does",
  "author": {
    "name": "Your Org"
  }
}
```

> **Note:** Do not add `displayName` to `.claude-plugin/plugin.json` — it is not a recognized field in the Claude plugin schema and will fail `claude plugin validate`.

## 2. Add plugin components

Add only the components you need:

- `rules/` with `.mdc` files (YAML frontmatter required)
- `skills/<skill-name>/SKILL.md` (YAML frontmatter required)
- `agents/*.md` (YAML frontmatter required)
- `commands/*.(md|mdc|markdown|txt)` (frontmatter recommended)
- `hooks/hooks.json` and `scripts/*` for automation hooks
- `mcp.json` for MCP server definitions
- `assets/logo.svg` for marketplace display

## 3. Register in marketplace manifests

Edit `.cursor-plugin/marketplace.json` and append a new entry:

```json
{
  "name": "my-new-plugin",
  "source": "my-new-plugin",
  "description": "Describe your plugin"
}
```

`source` is resolved from `metadata.pluginRoot` in marketplace (`plugins` in this repo), so `my-new-plugin` maps to `plugins/my-new-plugin`.

Edit `.claude-plugin/marketplace.json` and append a new entry:

```json
{
  "name": "my-new-plugin",
  "source": "./plugins/my-new-plugin",
  "description": "Describe your plugin"
}
```

## 4. Validate

```bash
node scripts/validate-template.mjs
claude plugin validate .
```

Fix all reported errors before committing.

## 5. Common pitfalls

- Plugin `name` not kebab-case.
- `source` path in marketplace manifests does not match folder name.
- Missing `.cursor-plugin/plugin.json` or `.claude-plugin/plugin.json` in plugin folder.
- Missing frontmatter keys (`name`, `description`) in skills, agents, or commands.
- Rule files missing frontmatter `description`.
- Broken relative paths for `logo`, `hooks`, or `mcpServers` in manifest files.
- `displayName` or `logo` in `.claude-plugin/plugin.json` — neither is a valid Claude field and both will fail `claude plugin validate`. Use `name` only for the display name; `logo` is Cursor-only.
- Unquoted YAML `description` containing `: ` (colon + space) — YAML interprets it as a key separator and silently drops all frontmatter. Always quote descriptions that contain colons: `description: "Usage: /my-command arg"`.