From Catalog Entry to Running Capability
A marketplace entry is the first visible part of a Claude Code plugin, not the plugin’s whole behavior. This chapter follows the lifecycle from a catalog record through source retrieval, manifest loading, component discovery, and runtime registration. The practical goal is to read a plugin as an installation contract: identify what is being installed, what may change later, and where the declared metadata ends and the executable or model-facing payload begins.
The distinction matters because a directory entry often looks static while the installed system is dynamic. A name can determine how an existing installation is found. A source field can determine which repository or subdirectory supplies the payload. A manifest can determine what Claude Code discovers. A hook or MCP configuration can then create behavior that is not obvious from the name alone. Reading these stages in order gives a more reliable picture than starting with a plugin’s marketing description or a familiar category label.
Read the catalog entry as a lifecycle contract
The marketplace record answers the first question a user has: what is this thing, and where does it come from? The official manifest stores a plugin name, description, category, author information when supplied, a homepage in many entries, and a source declaration. For local plugins, the source may point into the official worktree. For an external plugin, the source can describe an upstream repository, a subdirectory within it, a reference, and a commit SHA. These fields are not equally important, but together they define the route from discovery to a particular payload.
Start with the name. The repository calls the marketplace name an immutable slug because installed users depend on it. Changing the slug can cause an existing installation to fail with a plugin-not-found error. If the way a plugin is labeled in the user interface needs to change, the README recommends changing displayName instead. If a rename cannot be avoided, the marketplace can carry a renames map so the loader can migrate an old slug to a new one. This is a compatibility contract: the name is not just a heading in a catalog; it is part of how the runtime identifies the installed capability.
Next examine the source. A local path makes the official worktree itself the retained source for that entry. An object-style source can identify a remote repository or a subdirectory inside it. The marketplace snapshot includes both git-subdir and url forms, and many external entries record a SHA. A pinned revision is valuable because it makes the selected input reproducible: a user or maintainer can point to a particular upstream state instead of silently consuming whatever happens to be at the head of a branch.
But reproducibility is narrower than suitability. A SHA says which revision was selected; it does not say that the revision fits a user’s project, that its dependencies are acceptable, or that a remote service referenced inside it has an appropriate privacy policy. It also does not make future updates risk-free. An update changes the selected payload, and a repository may change its integration behavior, required credentials, or network dependencies at that later revision. The source field therefore answers “which input?” more reliably than it answers “is this input right for me?”
The category is useful for discovery but weak as evidence about behavior. A plugin listed under development could provide a language server, a multi-agent feature workflow, a plugin-building toolkit, or an MCP server development path. A security category can contain a local pattern checker, a networked review service, or an in-session scanning workflow. Categories help a reader narrow a search; they do not replace reading the description and payload. The same category label can contain very different authority and data-flow profiles.
The author and homepage add provenance and a place to continue inspection. They can tell the reader which organization claims responsibility and where the plugin’s own documentation or source context lives. They do not establish that the plugin’s behavior is limited to the short description. That is why the repository’s root README directs users to each plugin’s homepage and relevant license while also warning them to trust a plugin before use.
A marketplace entry can also describe a plugin whose source repository has a different shape from the standard manifest-centered package. The root README documents a skill-bundle form using strict: false and an explicit skills array when a source repository ships SKILL.md files without a .claude-plugin/plugin.json manifest. Each declared path points to a skill directory and is registered under the marketplace plugin name. This is a compatibility bridge: the marketplace can expose a curated subset of an existing repository without pretending that the upstream repository was authored in the official plugin layout.
The lifecycle consequence is straightforward. Before installation, read the slug, source form, revision or path, author, homepage, category, and description as separate signals. Ask which of them is stable, which can change, and which points to evidence that still needs inspection. A record that looks complete can still be only a map to a payload; the next stage is to inspect what that payload tells Claude Code to load.
The manifest registers behavior; the package supplies it
The standard plugin package puts its required manifest at .claude-plugin/plugin.json. The manifest can be minimal: the example plugin’s real manifest declares a name, description, and author. A fuller manifest may provide version, homepage, repository, license, keywords, or explicit component paths. The important distinction is that the manifest identifies and configures the package. It is not a complete description of every instruction, script, hook, or server shipped alongside it.
The conventional component locations sit at the plugin root. commands/ contains Markdown command definitions. agents/ contains agent definitions. skills/ contains subdirectories with SKILL.md files. hooks/ contains hook configuration when the plugin uses lifecycle automation. .mcp.json declares MCP servers, and scripts or supporting resources can provide the implementation or reference material those components use. The repository’s structure guidance describes these locations as an auto-discovery contract: when the plugin is enabled, Claude Code can find components by their expected location rather than requiring every one to be listed manually in the manifest.
That convention reduces configuration work, but it does not eliminate the need to inspect the package. Auto-discovery answers what can be registered, not what the registered component will do. A command file can contain instructions that call tools or pass arguments. An agent file can grant a delegated role and restrict or expand its tool set. A skill’s description can influence when its guidance is loaded. A hook configuration can bind a script or prompt to a lifecycle event. An MCP file can establish a local process or a connection to a remote endpoint. The same package layout can therefore contain components with very different runtime effects.
The example plugin makes this layered model concrete. It includes a manifest, an MCP configuration, two skill forms, and a legacy command file. Its README explains that skills are now the preferred format for both model-invoked capabilities and user-invoked slash commands, while the commands/ layout remains supported as a legacy reference. That is not merely a documentation preference. It tells a maintainer that the file layout itself has a lifecycle: a format can remain loadable while a newer format becomes the recommended path for future work.
The manifest can also supplement the conventional locations with custom paths. The structure guidance warns that custom paths supplement rather than replace the defaults. This matters when estimating the package’s surface. Looking only for one explicit path in plugin.json can miss components that are discovered by convention; looking only at conventional directories can miss additional configured locations. A careful inspection follows both routes, then checks the referenced files exist and match the declared purpose.
Portable paths are another part of the package contract. Plugin files are installed in locations that depend on the user’s installation method and operating system. The guidance therefore recommends ${CLAUDE_PLUGIN_ROOT} for hook commands, MCP server arguments, scripts, and bundled resources. A hard-coded path may work for the author and fail for the first user who installs the plugin elsewhere. A path relative to the current working directory may work in one project and resolve to the wrong place in another. Portability is therefore not cosmetic polish; it determines whether a component reaches the intended file at runtime.
A useful way to see the transition is as a sequence of ownership changes. The marketplace owns the published record and its declared source relationship. The selected source supplies the package at a particular revision or path. The plugin manifest tells Claude Code how to identify and configure that package. Auto-discovery finds the component definitions. The runtime then registers capabilities in a user session, where the project’s permissions, environment variables, credentials, and network conditions take over. At each transition, some information persists and some new uncertainty appears.
The sequence does not imply that every runtime detail is visible in the marketplace record. It shows where inspection should move. If the question is whether a plugin exists, the entry may be enough. If the question is what it can do, inspect the package. If the question is what it will do in a particular project, inspect the component instructions, scripts, hooks, environment requirements, and external endpoints under the conditions in which Claude Code will run.
Where metadata stops being enough
A reader should stop treating metadata as sufficient when the decision depends on behavior rather than identity. A short description such as “development kit,” “security review,” or “project management integration” tells us a purpose class, not the full operating surface. The package may contain a read-only analyzer, an agent that can write files, a hook that observes every prompt, or an MCP server that can change records in an outside system. Those differences matter more than the shared category name.
The point is not to demand an exhaustive audit for every low-risk experiment. It is to match inspection depth to authority and data flow. A plugin that supplies a narrowly scoped skill can often be evaluated by reading its manifest, skill description, and README. A plugin with hooks deserves attention to event matchers and handler scripts. A plugin with MCP configuration deserves attention to endpoint, transport, authentication, tool scope, and the service’s own terms. A plugin that ships scripts or bundled code deserves inspection beyond the first Markdown file because the shipped payload can contain behavior that the loader does not display as a description.
This layered reading also clarifies what governance can reasonably promise. The official repository can validate structure, record source information, check certain policy conditions, and preserve compatibility rules such as immutable names. Those controls make the lifecycle more legible and reduce avoidable failures. They do not make a source path equivalent to a security review, a live endpoint equivalent to a trusted endpoint, or a version pin equivalent to a guarantee of future compatibility.
The result is an installation habit with three passes. First, read the catalog record to understand identity, source, and stated purpose. Second, read the package to find the actual extension surfaces and dependencies. Third, judge the runtime conditions: what will trigger the behavior, what it can access, which state it can change, and where information can leave the session. The next question is how these surfaces differ once they are running—whether they supply context, wait for an explicit command, perform delegated work, intervene at an event, or expose a tool backed by another service.