# Contributing a plugin

This marketplace is a registry. To add a plugin, you create the plugin under
`plugins/` and register it in `.claude-plugin/marketplace.json`, then open a PR.

## 1. Create the plugin folder

Every plugin lives in its own folder under `plugins/`. A plugin needs, at
minimum, a manifest at `.claude-plugin/plugin.json`:

```text
plugins/
└── my-plugin/
    ├── .claude-plugin/
    │   └── plugin.json
    ├── skills/                 # optional: skill folders, each with SKILL.md
    │   └── my-skill/
    │       └── SKILL.md
    ├── commands/               # optional: slash command markdown files
    ├── agents/                 # optional: subagent markdown files
    ├── hooks/hooks.json        # optional
    ├── .mcp.json               # optional: MCP servers
    └── README.md
```

Minimal `plugins/my-plugin/.claude-plugin/plugin.json`:

```json
{
  "name": "my-plugin",
  "description": "What this plugin does.",
  "version": "0.1.0",
  "author": { "name": "Your Name", "email": "you@techery.io" }
}
```

`name` must be kebab-case and is used to namespace the plugin's skills and
commands. Only `.claude-plugin/plugin.json` goes inside `.claude-plugin/`;
everything else (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`) sits
at the plugin root.

## 2. Register it in the marketplace

Add an entry to the `plugins` array in
[`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json). `source`
must be an explicit relative path to the plugin folder (a bare folder name is
**not** a supported source type):

```json
{
  "name": "songwhip-marketplace",
  "owner": { "name": "Songwhip", "email": "alex.pryschepa@techery.io" },
  "description": "Claude Code plugins for Songwhip engineering workflows.",
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./plugins/my-plugin",
      "description": "What this plugin does.",
      "version": "0.1.0"
    }
  ]
}
```

The plugin entry's `name` must match the `name` in its `plugin.json`, and
`source` must start with `./`.

## 3. Test it locally

Load the plugin directly into a session without registering it, to iterate fast:

```text
claude --plugin-dir ./apryschepa/songwhip-marketplace/plugins/my-plugin
```

Or add the whole marketplace from your checkout and install it:

```text
/plugin marketplace add ./apryschepa/songwhip-marketplace
/plugin install my-plugin@songwhip-marketplace
/reload-plugins
```

Confirm the manifests are valid JSON before pushing — a malformed
`marketplace.json` or `plugin.json` makes the marketplace fail to load:

```text
node -e "require('./apryschepa/songwhip-marketplace/.claude-plugin/marketplace.json')"
```

## 4. Open a PR

Commit the new `plugins/<name>/` folder and the `marketplace.json` change, then
open a pull request. Add a short line to the **Available plugins** section of
[README.md](./README.md) so teammates can discover it.

## Conventions

- One plugin per folder under `plugins/`; folder name == plugin `name`.
- Keep each plugin focused on a single purpose.
- Bump the plugin's `version` (semver) when you change its behavior.
- Document what the plugin does in its own `README.md`.