Create plugin
Use when adding a new plugin to this claude-plugins marketplace - scaffolds plugins/<name>/ with a spec-compliant plugin.json and chosen components (commands, skills, agents, hooks), a README and CLAUDE.md, registers it in .claude-plugin/marketplace.json and the root README plugins table, scaffolds a bats test suite for hooks plugins, and verifies with the same checks the CI runs.From its SKILL.md
npx -y skills add kwitsch/claude-plugins --skill create-pluginAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
12.2 KB, as published. Nobody here has run it
Creating a New Marketplace Plugin
Scaffold new plugin, register in marketplace manifest, pass CI + installable.
Repository layout (recap)
.claude-plugin/marketplace.json— repo root marketplace manifest. Lists every plugin.plugins/<plugin-name>/.claude-plugin/plugin.json— per-plugin manifest.plugins/<plugin-name>/{commands,skills,agents,hooks}/— plugin components at plugin root.plugins/<plugin-name>/README.mdandplugins/<plugin-name>/CLAUDE.md— per-plugin docs.test/<plugin-name>/test.bats— per-plugin bats suite (top-level), run by CI..github/workflows/ci.yml— validatesmarketplace.jsonand each plugin manifest withjq..github/workflows/test.yml— runs each plugin'stest/<name>/test.batsvia static matrix.
Checklist
TaskCreate one task per step below, then TaskUpdate each to in_progress/completed in order — Task tools are the session default (Claude Code v2.1.142+), superseding TodoWrite.
- Gather inputs — ask one at a time.
- Validate name — kebab-case, not already taken.
- Scaffold plugin directory —
plugin.json+ chosen component stubs. - Scaffold docs —
plugins/<name>/README.md(minimal) +plugins/<name>/CLAUDE.md, add row to root README plugins table. - Scaffold test suite (hooks only) —
test/<name>/test.bats+ add plugin totest.ymlmatrix. - Register in marketplace.json — add entry to
pluginsarray. - Verify — run CI checks locally; manifests + bats suite (if scaffolded) must pass.
- Report — list every file created or changed.
Step 1 — Gather inputs
Ask one at a time. Collect:
- name — kebab-case (lowercase, digits, hyphens), e.g.
my-plugin. Directory name and manifestname. - description — one sentence, what plugin does.
- author — default
Kwitschunless told otherwise. - version — default
0.1.0. - category — single string, e.g.
productivity,example(optional). - tags — short keywords array (optional).
- components — which of
skills,agents,hooks,commands(legacy) to scaffold. Min one;skillsis default. Forhooks, also pick the hook kind (see.claude/rules/hooks-mcp-server.mddecision tree):- command — required only for: pre-connect events (
SessionStart/Setup), fail-closed hard gates (need exit 2), or fail-open-sensitive side-effects that must reliably fire (e.g.PreCompactsnapshot, a state-write other hooks read). Also the default for latency-sensitive high-frequency events (MessageDisplay;UserPromptSubmitis a latency/cost trade-off wheremcp_toolis also viable — see the matrix) → a.mjs/.shcommand hook. - mcp — otherwise, non-blocking mid-session hooks (
PreToolUse,PostToolUse,Stop,SubagentStop,PreCompact/ConfigChangewhen no must-fire side-effect, …) → anmcp_toolhook backed by a self-contained plugin-local MCP server (preferred). See the per-eventhooks-mcp-tool-event-matrix.
- command — required only for: pre-connect events (
Step 2 — Validate the name
- Confirm name matches
^[a-z0-9]+(-[a-z0-9]+)*$. - Confirm
plugins/<name>/doesn't exist. - Confirm no entry in
.claude-plugin/marketplace.jsonuses thatname.
Fail: report conflict, ask for different name. Never overwrite existing plugin.
Step 3 — Scaffold the plugin directory
Create plugins/<name>/.claude-plugin/plugin.json:
{
"name": "<name>",
"version": "<version>",
"description": "<description>",
"author": {
"name": "<author>"
}
}
Important: Component dirs at plugin root. Never put skills/, commands/, agents/, or hooks/ inside .claude-plugin/ — only plugin.json there.
Stub each chosen component:
-
skills →
plugins/<name>/skills/<name>/SKILL.md:--- name: <name> description: Use when <trigger condition> - <what the skill does>. --- # <Human-readable title> Step-by-step instructions for the skill go here. -
commands (legacy — prefer
skills/for new plugins) →plugins/<name>/commands/<name>.md:--- description: <short description of what this command does> --- Describe here what Claude should do when this command runs. -
agents →
plugins/<name>/agents/<name>.md:--- name: <name> description: <when this subagent should be used> --- System prompt / instructions for the subagent. -
hooks →
plugins/<name>/hooks/hooks.json:{ "hooks": {} }The empty
{}registers no behavior — populate it with real hook entries (e.g. aPreToolUse/PostToolUsematcher) and add the referenced script underplugins/<name>/hooks/, then cover it with behavioral tests in Step 5. -
hooks (mcp kind) → scaffold three files (see
.claude/rules/hooks-mcp-server.mdfor the full reference content):plugins/<name>/mcp/server.mjs— the self-contained zero-dep MCP stdio server (setSERVER_NAME = "<name>-hooks"). Copy it verbatim from the hooks-mcp-server rule, thenchmod +x plugins/<name>/mcp/server.mjs.plugins/<name>/.mcp.json— registers"<name>-hooks"→${CLAUDE_PLUGIN_ROOT}/mcp/server.mjs.plugins/<name>/hooks/hooks.json— aPostToolUsemcp_toolhandler (server: "<name>-hooks",tool: "example_context").
Only create the directories for components the user actually chose.
Step 4 — Scaffold docs
Create plugins/<name>/README.md (minimal):
# <name>
<description>
## Install
```
/plugin install <name>@kwitsch-plugins
```
## What it does
<one short paragraph describing the plugin's behavior>
Create plugins/<name>/CLAUDE.md (short, project-specific context):
# CLAUDE.md — <name>
<one or two lines on what the plugin is and its main component>.
## Behavior
<what the plugin's component(s) do at runtime — key rules, guards, edge cases>.
## Tests
`test/<name>/test.bats` (bats). Run: `BATS_LIB_PATH=/usr/lib/bats bats test/<name>/`.
Add row to ## Plugins table in root README.md, preserve existing rows:
| [<name>](plugins/<name>/README.md) | <description> |
Step 5 — Scaffold the test suite (hooks plugins only)
Only for hooks component. Prompt-only plugins (commands/skills/agents) have nothing to test — skip.
Create test/<name>/test.bats with passing smoke test:
#!/usr/bin/env bats
setup() {
bats_load_library bats-support
bats_load_library bats-assert
REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../.." && pwd)"
HOOKS="$REPO_ROOT/plugins/<name>/hooks/hooks.json"
}
@test "hooks.json is valid JSON" {
run jq empty "$HOOKS"
assert_success
}
# TODO: add behavioral tests for this plugin's hooks here.
For an mcp-kind hooks plugin, scaffold test/<name>/test.bats with:
#!/usr/bin/env bats
setup() {
bats_load_library bats-support
bats_load_library bats-assert
REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../.." && pwd)"
PLUGIN="$REPO_ROOT/plugins/<name>"
MCP_JSON="$PLUGIN/.mcp.json"
HOOKS="$PLUGIN/hooks/hooks.json"
SERVER="$PLUGIN/mcp/server.mjs"
}
@test ".mcp.json is valid JSON" {
run jq empty "$MCP_JSON"
assert_success
}
@test "hooks.json is valid JSON" {
run jq empty "$HOOKS"
assert_success
}
@test "every mcp_tool hook references a configured server" {
run bash -c '
set -e
for s in $(jq -r "[.hooks[][].hooks[] | select(.type==\"mcp_tool\") | .server] | unique[]" "'"$HOOKS"'"); do
jq -e --arg s "$s" ".mcpServers[\$s]" "'"$MCP_JSON"'" >/dev/null \
|| { echo "server not configured: $s" >&2; exit 1; }
done
'
assert_success
}
@test "every mcp_tool hook names a non-empty tool" {
run jq -e '[.hooks[][].hooks[] | select(.type=="mcp_tool")] | all(.tool | type=="string" and length>0)' "$HOOKS"
assert_success
}
@test "server.mjs is executable" {
[ -x "$SERVER" ]
}
@test "server.mjs has a node shebang" {
run head -n1 "$SERVER"
assert_output '#!/usr/bin/env node'
}
@test "server.mjs passes node --check" {
run node --check "$SERVER"
assert_success
}
@test "server lists its tool over stdio" {
# Runs under node; if bun is installed the shim re-execs transparently — same output.
run bash -c '
printf "%s\n%s\n" \
"{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}" \
"{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}" \
| node "'"$SERVER"'"
'
assert_success
assert_output --partial '"example_context"'
}
Wire into CI: in .github/workflows/test.yml, append - <name> under plugin:, preserve existing entries + valid YAML:
matrix:
plugin:
- git-sign-key # existing entry — keep it
- <name> # the new plugin
Step 6 — Register in marketplace.json
Add entry to plugins array in .claude-plugin/marketplace.json. Preserve existing entries + valid JSON (no trailing commas):
{
"name": "<name>",
"source": "./plugins/<name>",
"description": "<description>",
"author": {
"name": "<author>"
},
"category": "<category>",
"tags": ["<tag1>", "<tag2>"]
}
Use full ./plugins/<name> path — metadata.pluginRoot documented but broken in Claude Code (anthropics/claude-code#61224/#64431); reintroduce after upstream fix. No version field — plugin.json is single source of truth (CI fails if marketplace entry declares one). Omit category/tags if not provided. name and source only required fields.
Step 7 — Verify (mirror the CI)
Run same checks as .github/workflows/ci.yml:
manifest=".claude-plugin/marketplace.json"
test -f "$manifest" || {
echo "Missing $manifest"
exit 1
}
# marketplace.json is valid JSON
jq empty "$manifest"
# Required top-level fields
jq -e '.name and .owner and (.plugins | type == "array")' "$manifest" > /dev/null
# Every plugin entry has name + source
jq -e 'all(.plugins[]; .name and .source)' "$manifest" > /dev/null
# No marketplace entry carries a version (plugin.json is the single source)
jq -e 'all(.plugins[]; has("version") | not)' "$manifest" > /dev/null
# Every local plugin source (a full ./plugins/<name> path from the marketplace
# root) exists, its manifest is valid JSON and declares a version. The
# metadata.pluginRoot fallback is kept forward-compatible pending
# anthropics/claude-code#61224; pluginRoot is intentionally unused for now.
root="$(jq -r '.metadata.pluginRoot // "."' "$manifest")"
jq -r '.plugins[].source | if type == "string" then . else "remote" end' "$manifest" | while IFS= read -r src; do
case "$src" in
remote) ;;
*)
dir="$root/$src"
test -d "$dir" || {
echo "Missing source dir: $dir"
exit 1
}
pm="$dir/.claude-plugin/plugin.json"
[ -f "$pm" ] || {
echo "Missing plugin manifest: $pm"
exit 1
}
jq empty "$pm"
jq -e '.version' "$pm" > /dev/null || {
echo "$pm declares no version"
exit 1
}
;;
esac
done
All commands must succeed with no error output. Fix before reporting done.
For hooks plugin, also run suite + confirm matrix wiring:
# The new bats suite passes
BATS_LIB_PATH=/usr/lib/bats bats "test/<name>/"
# The plugin is present in the test matrix ($ is grep's end-of-line anchor)
grep -q "^[[:space:]]*-[[:space:]]*<name>\$" .github/workflows/test.yml \
|| {
echo "Missing test.yml matrix entry for <name>"
exit 1
}
For an mcp-kind plugin the same bats suite also exercises the server: executable bit + node shebang, node --check, and a live initialize+tools/list over stdio must pass. node is the CI baseline (bun optional; the shim falls back to node when bun is absent).
Step 8 — Report
List every file created: plugin.json, component stubs, README.md, CLAUDE.md, marketplace.json entry, and (hooks plugin) test/<name>/test.bats + test.yml matrix entry. Remind: commit and install via /plugin install <name>@kwitsch-plugins.