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/<name>/` with this layout:
 plugins/<name>/
   .claude-plugin/
     plugin.json          # name, description, version
-  skills/<name>/         # for skill plugins
+  commands/              # user-facing slash commands (preferred)
+    <verb>.md            # shows as /plugin-name:verb in autocomplete
+  skills/<verb>/         # alternative to commands (legacy)
     SKILL.md             # skill definition with frontmatter
+  scripts/               # helper scripts referenced by commands/skills
+    tool.py
   agents/                # for agent plugins
     <name>.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/<name>/`) 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/<name>/
 }
 ```
 
-### 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