The Four Ways a Plugin Changes the Conversation
A Claude Code plugin can change a session in several fundamentally different ways. This chapter compares skills, commands, agents, hooks, and MCP integrations by the questions that matter at runtime: who or what triggers the behavior, what context it receives, what authority it has, and where its work happens. The result is a practical way to choose the right extension surface without treating every Markdown file or configuration entry as the same kind of capability.
The distinctions are important because a plugin’s file layout can hide different relationships with the user. One component may quietly add relevant guidance when a request matches. Another waits for an explicit slash command. A third is delegated a task and returns a structured review. A fourth runs because a tool event occurred. An MCP integration can expose a tool whose action is carried out by a local process or a remote service. These are not just different packaging styles; they are different control and trust models.
Skills and commands: context versus explicit intent
A skill is primarily contextual expertise. Its frontmatter gives Claude Code a name and a description that explains when the skill should apply. The plugin-dev guidance recommends concrete trigger phrases, a focused description, and a lean SKILL.md body. When the skill matches a task, its core instructions can provide specialized knowledge, workflow guidance, or domain-specific procedures. References, examples, and scripts can remain in the skill directory and be loaded or executed when they are actually needed.
This progressive-disclosure design solves a specific problem: a general agent can have access to many specialties without carrying every detailed guide into every request. The metadata acts as a small routing layer. The body supplies the essential operating model after activation. Supporting references supply depth only when the task requires it. A skill is therefore well suited to questions such as how to structure a plugin, how to integrate an MCP server, or how to follow a framework’s conventions when the request itself makes that expertise relevant.
The trade-off is that a skill depends on a good description and a good match between the user’s request and the skill’s trigger conditions. A vague description can activate too broadly or fail to activate when needed. Overlapping descriptions can make it unclear which guidance should influence the response. The repository’s evidence supports progressive disclosure as a design pattern, but it does not establish a production-level accuracy rate for skill triggering. The description is part of the runtime behavior and should be reviewed like any other interface.
A command is more explicit. It is a Markdown prompt that the user invokes through a slash command, often with arguments. The command-development guidance describes frontmatter for a human-facing description, argument hints, allowed tools, model selection, and invocation policy. A command can use the whole argument string or positional values, reference files, and gather context through permitted shell commands. Its central advantage is visible intent: the user chooses the entry point and can see what kind of workflow they are requesting.
Explicit invocation does not make a command harmless. The command body becomes instructions for Claude, and its allowed tools determine what it can ask the runtime to do. A command that only reads a file has a different authority profile from one that can write files, call GitHub, or invoke a remote MCP tool. Arguments can also change the target or scope of the action, so a command should explain its expected inputs and handle missing or invalid values. The interface is visible, but the body and tool permissions still require inspection.
The example plugin captures a transition in the repository’s own conventions. The commands/ layout remains supported, but the README calls it a legacy format and recommends the skills/<name>/SKILL.md layout for new plugins, including user-invoked capabilities. The important lesson is not that commands have become useless. It is that the same user-facing behavior can be represented through a newer packaging convention, while older installations continue to load the earlier form. Compatibility and design preference can coexist.
The useful comparison is therefore not “skills are automatic and commands are safe.” It is more precise:
- Use a skill when the capability should add contextual knowledge or a reusable way of thinking when the task makes it relevant.
- Use a command when the user should choose a named workflow, supply arguments, or receive a clear entry point.
- In both cases, inspect the instructions, references, scripts, and allowed tools that determine what happens after the trigger.
Agents and hooks: delegated work versus ambient control
An agent is more than a longer command because it represents a delegated role with its own triggering conditions, model choice, tools, process, and output contract. The agent-development guidance describes a Markdown file with frontmatter for an identifier, description, model, color, and optional tool restrictions. Its body becomes a system prompt that defines responsibilities, analysis steps, quality standards, edge cases, and the format of the result.
That structure changes how work is divided. A command can tell the main agent to perform a sequence. An agent can be asked to investigate a bounded problem and return findings in a defined form. The feature-development plugin uses this distinction with code explorers, architects, and reviewers. The explorer traces an existing feature and returns essential files. The architect turns patterns into an implementation blueprint. The reviewer checks bugs, guidelines, and quality. The value is not simply parallelism; it is the separation of roles and evidence. Each agent has a narrower job than an undifferentiated request to “look at the code.”
Tool restrictions matter here. The guidance recommends limiting an agent to the minimum tools it needs, such as read-only tools for analysis or a controlled set for generation. This is a least-privilege decision. An agent that only needs to inspect code should not receive write or shell authority by default. Model selection is another trade-off: inheriting the parent model provides consistency, while a faster or more capable model can be chosen for a specific role. The repository documents these fields, but the right choice depends on the task’s complexity, cost, and risk.
A hook changes the timing more dramatically. It runs in response to a Claude Code event such as a prompt submission, a tool call, a tool result, a session start, or an attempted stop. A hook can add context, return feedback, approve or deny a tool call, modify input where supported, or block completion. The user may not have invoked a named command at the moment the hook runs. That makes hooks useful for policy enforcement and automatic checks, but it also gives them an ambient position in the session.
The distinction between an agent and a hook is therefore about control ownership. An agent usually receives a delegated task and returns an answer. A hook is attached to an event controlled by the runtime and can observe or influence that event. The hook-development guidance recommends matchers so a hook applies only to relevant tools or events, input validation, quoted variables, timeouts, structured output, and no reliance on execution order. These are not stylistic preferences. They are ways to limit what the hook sees and to keep a failure from becoming an unexplained session-wide behavior.
The security-guidance plugin illustrates the range of this surface. Its hook configuration binds a launcher at session start and prompt submission, attaches review behavior after edits and writes, adds conditions for commit and push commands, and triggers a review when the agent stops. The plugin’s README explains what those reviews send through the configured model path and how they can be disabled or redirected. The configuration is useful precisely because it is active at several lifecycle points; the same fact is why its scope and disclosure deserve more attention than a passive skill’s.
Hookify shows a different control pattern. It lets users create local Markdown rules that watch for patterns in Bash commands, file operations, prompts, or stopping behavior. A rule can warn or block, and conditions can narrow the match. This gives the user a direct way to add a guard without editing a complex hook configuration. It also demonstrates that “automatic” does not have to mean “uninspectable”: a rule file can state its event, pattern, action, and message in a form the user can read and change.
MCP: the boundary where a component becomes a service
An MCP integration is not simply a prompt with more instructions. It exposes structured tools from a local process, a bundled server, or an external service. The plugin-dev guidance describes stdio for local processes, SSE for hosted services and OAuth, HTTP for REST-style token authentication, and WebSocket for real-time connections. Configuration can live in .mcp.json or in the plugin manifest, and tool names are namespaced so the runtime can identify their plugin and server origin.
The key change is the location of the action. A skill or command primarily changes what Claude is instructed to do. An MCP tool provides an interface through which Claude can ask another process or service to do something. That service may read records, create tasks, query a database, manage a repository, or return documentation. The user must therefore reason about endpoint identity, authentication, tool scope, and the data that crosses the boundary. An environment variable holding a token and an OAuth consent screen are not implementation trivia; they are part of the capability’s authority.
The repository’s examples make the difference concrete. The GitHub plugin declares an HTTP endpoint and takes a personal access token from the environment. Context7 points to a hosted HTTP endpoint for documentation lookup. Asana’s README requires the user to create an OAuth app, configure a local callback, store the secret through the CLI’s secure flow, and consent in a browser. These integrations can be valuable because they connect the agent to current, structured systems. They also depend on remote availability and on the service operator’s handling of requests and credentials.
The plugin-dev guidance recommends pre-allowing specific MCP tools rather than using a broad wildcard. That recommendation applies the same principle as an agent’s tool restriction to an external boundary: grant the workflow the operations it needs, not every operation a server happens to expose. It also recommends secure transports, environment variables instead of hard-coded tokens, documented setup, and explicit handling of connection and tool errors. A reachable endpoint can still be the wrong endpoint, and a successful authentication flow can still grant more authority than the task needs.
Choosing by behavior, not by label
No single extension surface dominates. The right choice depends on the behavior the plugin should create and the consequences of getting it wrong. Five criteria make the comparison useful.
Trigger asks who starts the work. A skill responds to task context; a command responds to an explicit user request; an agent may be selected or delegated; a hook responds to a lifecycle event; an MCP tool is called as part of a workflow. The less visible the trigger, the more important clear scope and disclosure become.
Authority asks what the component can change. A skill can shape reasoning without directly granting a new tool. A command may be limited by allowed tools. An agent may have read-only or write access. A hook may influence tool permission or stopping behavior. An MCP server may expose operations that change state in another system. Authority should be matched to the job, not assumed from the plugin’s category.
Context and state ask what information the component needs and where state persists. A skill may load references. A command may receive arguments and files. An agent may read a codebase. A hook may see prompt or tool-event data. An MCP service may retain or act on records outside the local project. The answer determines what must be disclosed and what a user should avoid placing in configuration or prompts.
Failure behavior asks what happens when the component cannot operate. A skill may simply be irrelevant. A command can return an argument or tool error. An agent can produce an incomplete analysis. A hook can slow, block, or fail a lifecycle event. An MCP server can be unavailable, unauthorized, rate-limited, or return a remote error. A design that handles only the happy path can turn a small dependency failure into a confusing session failure.
Reversibility asks how easily a user can stop or undo the behavior. A command can be left uninvoked. A skill can be disabled or its files changed. A hook may require configuration changes or a restart, except where a plugin such as hookify provides a rule path designed for immediate changes. An external action may already have changed a project-management record or code-host state by the time the user notices a problem. This is why explicit approval and narrow permissions matter most near irreversible boundaries.
The practical mental model is simple: skills add context, commands expose intent, agents divide work, hooks control timing, and MCP connects the session to tools and services. A real plugin can combine all five. Combination is where the directory becomes powerful—and where the user should stop asking which label applies and start tracing the complete path from trigger to authority to data. Hooks make that path especially visible because they can intervene before or after tool use without waiting for a separate command.