Contributing to Claude Agents & Skills Plugin Marketplace

Contributing to Claude Agents & Skills Plugin Marketplace

Thank you for your interest in contributing. This guide covers the v2.0.0 plugin format used by the marketplace. All new contributions must follow this format to be installable via `/plugin install`.

Plugin Format Overview

Each plugin lives in its own directory under `plugins/` and follows this structure:

plugins/your-plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required: plugin manifest
├── skills/                  # Skills provided by this plugin (if any)
│   └── your-skill-name/
│       ├── SKILL.md         # Main skill definition
│       └── README.md        # Human-readable documentation
├── agents/                  # Agents provided by this plugin (if any)
│   └── your-agent-name.md   # Agent definition
├── references/              # Supporting reference documents (optional)
├── scripts/                 # Python utility scripts (optional)
├── examples/                # Example data files (optional)
└── README.md                # Plugin-level documentation

A plugin must contain at least one skill or agent. Plugins may contain both.

Step 1: Create the Plugin Directory

mkdir -p plugins/your-plugin-name/.claude-plugin
mkdir -p plugins/your-plugin-name/skills/your-plugin-name
# Add agents directory if needed
mkdir -p plugins/your-plugin-name/agents

Step 2: Add the plugin.json Manifest

Create `plugins/your-plugin-name/.claude-plugin/plugin.json`:

{
  "name": "your-plugin-name",
  "description": "One-sentence description of what this plugin does",
  "version": "1.0.0",
  "author": { "name": "your-github-username" },
  "repository": "https://github.com/mrelph/claude-agents-skills",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2", "keyword3"]
}

**Required fields:**

Field	Type	Description
name	string	Kebab-case plugin identifier, unique in the marketplace
description	string	One-sentence description for the plugin catalog
version	string	Semantic version (MAJOR.MINOR.PATCH)
author	object	{ "name": "github-username" }
repository	string	Repository URL
license	string	SPDX license identifier (use MIT for this repo)
keywords	array	3–8 tags that help users discover the plugin

Step 3: Add Skills

Create a skill definition at `plugins/your-plugin-name/skills/your-skill-name/SKILL.md`:

---
name: your-skill-name
description: Brief description of what the skill does
allowed-tools: Read, Bash, WebSearch, Write
metadata:
  version: 1.0.0
  last-updated: 2026-01-01
---

# Your Skill Name

[Skill instructions and workflow...]

**Critical requirement — use `${CLAUDE_PLUGIN_ROOT}/` for all file paths.**

Any references to files within the plugin (reference documents, scripts, examples) must use the `${CLAUDE_PLUGIN_ROOT}/` variable so that Claude Code can resolve them regardless of where the plugin i