[DOCS] Plugins reference missing `monitors` manifest key and auto-arm lifecycle

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/plugins-reference

Section/Topic

Plugin manifest schema (.claude-plugin/plugin.json) and plugin/skill monitor lifecycle behavior

Current Documentation

The docs currently describe plugin components and manifest fields without any monitors entry.

From plugins-reference:

A plugin is a self-contained directory of components that extends Claude Code with custom functionality. Plugin components include skills, agents, hooks, MCP servers, and LSP servers.

{ "name": "plugin-name", "version": "1.2.0", "description": "Brief plugin description", ... "skills": "./custom/skills/", "commands": ["./custom/commands/special.md"], "agents": "./custom/agents/", "hooks": "./config/hooks.json", "mcpServers": "./mcp-config.json", "outputStyles": "./styles/", "lspServers": "./.lsp.json" }

| skills | string\|array | Custom skill directories containing <name>/SKILL.md (replaces default skills/) | | commands | string\|array | Custom flat .md skill files or directories (replaces default commands/) | | agents | string\|array | Custom agent files (replaces default agents/) | | hooks | string\|array\|object | Hook config paths or inline config | | mcpServers | string\|array\|object | MCP config paths or inline config | | outputStyles | string\|array | Custom output style files/directories (replaces default output-styles/) | | lspServers | string\|array\|object | Language Server Protocol configs | | userConfig | object | User-configurable values prompted at enable time | | channels | array | Channel declarations for message injection |

From skills:

In a regular session, skill descriptions are loaded into context so Claude knows what's available, but full skill content only loads when invoked.

From features-overview:

By default, descriptions load at session start and full content loads when used. For user-only skills (disable-model-invocation: true), nothing loads until you invoke them.

No code.claude.com page currently documents a plugin monitors manifest key or explains how plugin-provided background monitors auto-arm at session start or when a skill is invoked.

What's Wrong or Missing?

Changelog v2.1.105 added background monitor support for plugins via a top-level monitors manifest key, but the plugin docs still present the manifest as if monitors do not exist.

That leaves several user-visible questions unanswered:

• what the monitors schema looks like in .claude-plugin/plugin.json
• whether monitor definitions are inline, path-based, or both
• how monitor declarations relate to the existing Monitor tool
• when monitors start automatically at session start versus only after a skill is invoked
• how plugin authors should reason about permissions, provider support, and stopping monitor tasks

Because the feature is completely undocumented, plugin authors cannot discover or implement it from the official docs.

Suggested Improvement

Add a dedicated monitors section to plugins-reference and include it in the manifest schema example/table.

At minimum, document:

1. The supported monitors manifest shape, with one concrete JSON example
2. The lifecycle rules for auto-arming:

• which monitors start at session start
• which monitors wait for skill invocation
• what happens on /reload-plugins, session end, and monitor stop

1. How monitor behavior maps to the existing Monitor tool, including permission inheritance and provider limitations
2. Where plugin authors should mention monitor-backed behavior in plugin skills so users understand what starts automatically

Also add short cross-references from plugins, agent-sdk/plugins, and skills so readers looking at plugin creation or skill lifecycle docs can discover this feature.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/plugins-reference | Plugin component list and manifest schema need a monitors entry |
| https://code.claude.com/docs/en/plugins | Plugin authoring guide should mention monitor support when describing plugin components |
| https://code.claude.com/docs/en/agent-sdk/plugins | SDK plugin docs currently list skills, agents, hooks, and MCP servers, but not monitor support |
| https://code.claude.com/docs/en/skills | Skill lifecycle docs should explain the skill-invocation side of monitor auto-arming |
| https://code.claude.com/docs/en/features-overview | Loading-strategy docs should cross-reference monitor-backed plugin behavior |
| https://code.claude.com/docs/en/tools-reference | Monitor tool page should be linked from plugin monitor docs for permissions/provider behavior |

Total scope: 6 pages affected

Source: Changelog v2.1.105

Exact changelog entry:

Added background monitor support for plugins via a top-level monitors manifest key that auto-arms at session start or on skill invoke