Lesson 8.3 — Plugins & marketplaces¶

A plugin is a convention pack; a marketplace is the tap your whole team installs from.

TL;DR: A plugin bundles many extension types — skills, commands, hooks, subagents, MCP/LSP servers — into one installable, versioned unit ¹³. A marketplace is a git-hosted catalog: add it, then /plugin install name@marketplace ². This is how a team distributes its agent-first conventions.

ELI5: the Homebrew tap¶

Your skills, hooks, and reviewer subagents are custom tools; a plugin staples them into one box; a marketplace is the tap everyone points at.

A plugin is a convention pack. A marketplace is the tap you point the team at — /plugin marketplace add your-org/plugins, then /plugin install … — just like brew tap then brew install. Adding the tap installs nothing; you still choose what to pull ².

What a plugin bundles¶

Not one thing — a plugin is the container for every extension type a team built ¹³.

flowchart TB
    subgraph PLUGIN["one plugin (.claude-plugin/plugin.json)"]
        SK["skills/"] ~~~ CM["commands/"] ~~~ AG["agents/"]
        HK["hooks/hooks.json"] ~~~ MCP[".mcp.json"] ~~~ LSP[".lsp.json"]
    end
    PLUGIN --> INST["/plugin install → all of it, at once"]

"A plugin is a self-contained directory of components… skills, agents, hooks, MCP servers, LSP servers, and monitors" ³. The load-bearing point: a one-skill plugin is the minimal case, not the definition — a plugin is how you ship a whole team's extensions as one versioned artifact ¹.

🧠 Test Yourself: A teammate says "a plugin is just a skill with a fancier name." Where's the flaw?
Answer
A skill is one component type. A plugin is the container that can bundle skills and commands, hooks, subagents, MCP/LSP servers, and monitors — distributed and versioned as a unit ³.

The manifest & layout¶

.claude-plugin/plugin.json (only name is required); every other directory sits at the plugin root, not inside .claude-plugin/ ¹³.

Path	Holds
`.claude-plugin/plugin.json`	the manifest — only this file goes here
`skills/<name>/SKILL.md` · `commands/.md` · `agents/.md`	skills, commands, subagents
`hooks/hooks.json` · `.mcp.json` · `.lsp.json`	hooks, MCP servers, LSP servers

The single most common failure is putting skills//hooks/ inside .claude-plugin/ — don't; only the manifest lives there ¹³. Components are namespaced by the plugin name (my-plugin:hello) to avoid collisions, and at install time a second axis appears: plugin@marketplace. Precedence is safe by default — your project/user .claude/agents/ win over same-named plugin items, so a plugin never silently overrides your local conventions ³.

Marketplaces: add, then install¶

A marketplace is a git-hosted catalog of plugins — a two-step flow, add the catalog then install from it ²⁴.

flowchart LR
    A["/plugin marketplace add<br/>owner/repo (git-hosted catalog)"] --> B["browse the catalog"]
    B --> C["/plugin install name@marketplace<br/>(pick individual plugins)"]

"A marketplace is a catalog of plugins that someone else has created and shared" ². Two official ones: claude-plugins-official (curated by Anthropic, available automatically) and the community marketplace (anthropics/claude-plugins-community, added manually) ². A marketplace is just a marketplace.json listing each plugin's name + source — anyone can host one (a GitHub repo, GitLab, even a private/internal repo) ⁴.

Safety: trust + commit-pinning¶

Plugins run arbitrary code at your privileges — only add marketplaces you trust, and pin versions ²³.

"Plugins and marketplaces are highly trusted components that can execute arbitrary code on your machine with your user privileges. Only install plugins and add marketplaces from sources you trust" ².

This is a supply-chain trust boundary (Phase 7.4). The mitigations: community plugins are review-screened and pinned to a commit SHA; setting an explicit version means users only update when you bump it; and orgs can restrict allowed marketplaces via managed settings ²³.

🧠 Test Yourself: Why is adding a random marketplace riskier than installing a single npm package?
Answer
A plugin can ship hooks and MCP servers that execute arbitrary code on your machine at your privileges, and they run inside your agent's trusted context. Treat a marketplace like granting shell access — add only trusted sources and pin to a commit/version ²³.

Capstone: package THIS repo into a plugin¶

The whole tier in one box — bundle the skills (7.1), hooks (7.2), and subagent (7.5) we built ¹.

This repo already contains exactly the pieces a plugin bundles:

This repo has	Plugin slot
`.agents/`/`.claude/skills/` (author-curriculum, check-understanding, scaffold-agent-project)	`skills/<name>/SKILL.md`
`.agent/hooks/*.sh` wired via `.claude/settings.json`	`hooks/hooks.json` (move the `hooks` object verbatim)
`.claude/agents/lesson-reviewer.md`	`agents/lesson-reviewer.md`

The one caveat to teach: an installed plugin is copied to a cache and cannot reference files outside its own root — so the hook scripts must live inside the plugin and use the ${CLAUDE_PLUGIN_ROOT} variable in their paths, not .agent/hooks/... ¹³.

Agent-agnostic¶

Skills are portable (the open standard); the bundle/marketplace layer is richest in Claude Code; Cursor/Codex distribute conventions by committing rule/AGENTS.md files to git ⁵⁶⁷.

Ecosystem	Portable unit	How conventions are shared
Claude Code	Skill (`SKILL.md`)	Plugins bundle everything; marketplaces distribute + version ¹
Agent Skills (open std)	`SKILL.md` folder	portable as-is across Codex, Cursor, Gemini CLI… ⁵
Cursor	`.cursor/rules/*.mdc`	check rules into git "so your whole team benefits" ⁷
OpenAI Codex	`AGENTS.md`	a README-for-agents committed to the repo ⁶

Takeaway: the skills inside a plugin stay portable (open standard) — packaging as a plugin doesn't lock them to Claude; it just adds a bundling + catalog + versioning layer on top ⁵.

Your turn (exercise)¶

Package this repo's .claude/ into a plugin: mkdir -p afe-plugin/.claude-plugin, write plugin.json ({"name":"agent-first-engineering","version":"1.0.0"}), copy skills/ and agents/, move the settings.json hooks object into hooks/hooks.json (rewriting paths to ${CLAUDE_PLUGIN_ROOT}/hooks/…), and test with claude --plugin-dir ./afe-plugin. Then decide: which conventions belong in a team plugin, and which are personal and should stay in your ~/.claude/?

How this repo does it — generate, don't hand-maintain

A plugin is a copy of your canonical skills/hooks/agents, so a hand-maintained one drifts the moment the originals change. This repo treats plugin/ as a build artifact: it's git-ignored and regenerated with one command — sh scripts/build-plugin.sh — which copies .agents/skills/, .agent/hooks/, and .claude/agents/ into plugin/ and rewrites plugin.json + hooks/hooks.json + README.md. Never edit plugin/ by hand; edit the source and rebuild. (Only scripts/build-plugin.sh and the root .claude-plugin/marketplace.json are committed.)

← Lesson 8.2 · Phase 8 home · → Check your understanding

Create plugins — Anthropic (Claude Code docs) ↩↩↩↩↩↩↩↩
Discover and install plugins — Anthropic (Claude Code docs) ↩↩↩↩↩↩↩↩↩
Plugins reference — Anthropic (Claude Code docs) ↩↩↩↩↩↩↩↩↩↩↩
Create and distribute a plugin marketplace — Anthropic (Claude Code docs) ↩↩
Equipping agents for the real world with Agent Skills — Anthropic Engineering ↩↩↩
AGENTS.md — the open agent-instruction format — Agentic AI Foundation ↩↩
Cursor — Rules — Cursor ↩↩