Mastering Claude Code · ~7 min
One command scaffolds a plugin in your skills directory; one manifest key arms a watcher that runs itself every session. No marketplace round-trip.
SKILL.md can't carry that.
The plugin is the bundle — and since v2.1.157 you no longer need a marketplace to run one locally.A plugin is distribution packaging, not a separate logic layer. So the question is never "should this be a plugin?" in the abstract — it's "does this bundle now carry more than one skill, or need to ship, or need a watcher armed for me?" When the answer is yes, three moves get you from nothing to a running plugin.
Claude Code 2.1.157 (shipped 2026-05-29) auto-loads any folder under a skills directory that contains a
.claude-plugin/plugin.json manifest — no marketplace, no install step. claude plugin init
writes that layout for you:
That produces a .claude/skills/repo-helper/ tree: the manifest (name, description, and author pulled from
git config user.name/user.email), a starter skill under skills/, and — because of
--with hooks — a hooks/hooks.json with a sample handler ready to edit. On the next session it
loads as repo-helper@skills-dir, discovered in place rather than copied into the plugin cache.
foo/SKILL.md is a plain skill (/foo); foo/.claude-plugin/plugin.json is a plugin
(foo@skills-dir); and foo/skills/bar/SKILL.md is a skill packaged inside that plugin,
invoked as /foo:bar.For a single skill in a single repo, loose .claude/skills/<name>/SKILL.md stays the cheaper
default — it's shorter to invoke (/deploy, not /my-plugin:deploy) and it walks up to
the repo root from any subdirectory. A project-scope @skills-dir plugin does not walk
up: launch from apps/api/ and a plugin at the root is silently missed. Launch from the root, or run
/reload-plugins after you cd.
Where you scaffold sets who sees the plugin and what its components may do. Personal scope carries no restrictions; project scope is treated as repo-supplied content and runs under extra guards.
| Skills directory | Scope | What's restricted |
|---|---|---|
~/.claude/skills/ | personal | Nothing — loads in every project, it's yours |
<cwd>/.claude/skills/ | project | Loads only after the workspace trust dialog |
At project scope the bundled pieces inherit the same suspicion as any repo content: MCP servers face the per-server
approval a project .mcp.json gets, LSP servers start only after you trust the workspace, and
background monitors do not load at all. That last one is the trap of the next section — if your plugin's
whole point is a watcher, project scope ships dead code.
SKILL.md edit takes effect immediately, but changes to hooks/,
.mcp.json, agents/, and output-styles/ need /reload-plugins or a
restart. Iterating on the skill is hot; iterating on the wiring is not.v2.1.105 added a top-level monitors manifest key. Each entry is one persistent background process whose
every stdout line becomes a notification to Claude — and the harness arms it automatically at session
start or on skill invoke. The consumer writes no boilerplate.
This is the third declarative supervision primitive, distinct from the other two. The optional when field
is "always" by default, or "on-skill-invoke:<skill-name>" to defer the spawn until a named
skill first runs.
| Primitive | Trigger | Can block? |
|---|---|---|
| Hook | Tool-call boundary (PreToolUse, PostToolUse…) | Yes (PreToolUse) |
| Monitor tool | Claude calls it imperatively in-session | No |
| Plugin monitor | Auto-armed at session start / on skill invoke | No |
Monitors are session-scoped — torn down at session end, so they're no substitute for systemd or
cron when enforcement must survive a reboot. They run unsandboxed at hook trust level — vet a
marketplace monitor like any shell script. Only stdout is forwarded: a watcher that errors to stderr
or exits non-zero looks healthy. Chatty monitors are auto-killed, so pipe through grep --line-buffered.
And Bedrock, Vertex AI, and Foundry skip monitors entirely.
claude plugin init <name> --with hooks scaffolds manifest + skill + components, auto-loaded as <name>@skills-dir next session.~/.claude/skills/) runs free; project scope is gated — trust dialog, MCP approval, and no background monitors.monitors key and the harness arms the watcher for you — no SessionStart hook, no remembered /loop.Retrieval practice — recall, don't peek
Question 1What turns a folder under a skills directory into an auto-loaded plugin?
Question 2A skill packaged inside the plugin foo as foo/skills/bar/SKILL.md is invoked as…
Question 3At project scope, what does a plugin's background monitor do?
Question 4The chief value of the monitors key over a Monitor-tool call is that it…
Question 5 · spaced recall from an earlier lessonFrom the hooks lesson: behavior that must happen 100% of the time belongs in a hook because hooks are…