From 730f1006194e08d1cb4cc7d2b59d9edc0c633315 Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Thu, 19 Mar 2026 16:00:43 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20sync=20KB=20=E2=80=94=20claude-plugins-?= =?UTF-8?q?marketplace.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- development/claude-plugins-marketplace.md | 27 ++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/development/claude-plugins-marketplace.md b/development/claude-plugins-marketplace.md index 3ce0024..2e82075 100644 --- a/development/claude-plugins-marketplace.md +++ b/development/claude-plugins-marketplace.md @@ -72,12 +72,24 @@ Each plugin lives under `plugins//` with this layout: plugins// .claude-plugin/ plugin.json # name, description, version - skills// # for skill plugins + commands/ # user-facing slash commands (preferred) + .md # shows as /plugin-name:verb in autocomplete + skills// # alternative to commands (legacy) SKILL.md # skill definition with frontmatter + scripts/ # helper scripts referenced by commands/skills + tool.py agents/ # for agent plugins .md # agent definition ``` +### Commands vs Skills + +**Commands** (`.md` files in `commands/`) are preferred for user-facing slash commands. They appear in autocomplete as `/plugin-name:command-name`, giving a clean grouped prefix (e.g., `/json-pretty:format`). + +**Skills** (`SKILL.md` in `skills//`) are the older pattern. They work but don't group as cleanly in autocomplete. + +Commands reference scripts via `${CLAUDE_PLUGIN_ROOT}/scripts/` — no symlinks needed. + ### plugin.json ```json @@ -88,7 +100,16 @@ plugins// } ``` -### SKILL.md Frontmatter +### Command Frontmatter + +```yaml +--- +description: "What this command does" +allowed-tools: Bash +--- +``` + +### SKILL.md Frontmatter (legacy) ```yaml --- @@ -123,7 +144,7 @@ Then update the cache: `claude plugin marketplace update cal-claude-plugins` ## Important Notes -- **SKILL.md `name:` must match directory name** — a mismatch causes the skill to not load (e.g., the `optimise-claude` plugin had `name: claude-optimised` which broke it) +- **Commands use `${CLAUDE_PLUGIN_ROOT}`** — reference scripts via `${CLAUDE_PLUGIN_ROOT}/scripts/` instead of absolute paths or symlinks - **SSH remote** — uses `git@git.manticorum.com:cal/claude-plugins.git` via SSH config alias (`~/.ssh/config` maps `git.manticorum.com` → `10.10.0.225` as user `git`) - **No secrets** — repo is public; plugins are just prompt definitions, no credentials - **Plugins requiring MCP servers** — `backlog`, `issue-worker`, and `pr-reviewer` require `gitea-mcp`; they install fine without it but those tool calls won't execute