The Small Architecture Behind a Large Promise
The knowledge-work-plugins repository is best understood as a set of layered software contracts, not as a directory of interchangeable prompt files. This chapter focuses on what each layer contributes before a workflow runs: how a package identifies itself, how it exposes specialist knowledge, how it reaches external systems, and where it can add control or autonomy. That distinction gives the reader a practical way to predict what a plugin can do—and what it cannot do—when one layer is missing.
Identity comes before behavior
Every plugin starts with a manifest. The repository’s creation guidance treats .claude-plugin/plugin.json as required and the name field as the minimum identity. Concrete packages add a version, description, and author. These fields may look administrative, but they establish the first boundary: they tell the host what package is being installed and give a user a compact statement of its intended purpose. They do not, by themselves, make the workflow capable of doing anything.
That separation matters when reading a marketplace. A description can say that a package helps with sales calls, financial analysis, or customer support, but the behavior is implemented by the components the package exposes. A version can help distinguish one revision from another, but it does not prove that a vendor’s current API still matches the instructions. A manifest is therefore a discovery and identity contract, not a guarantee of runtime quality.
The management plugin’s examples make this visible by showing three levels of package. A minimal plugin can have one manifest, one skill, and a README. A standard package can add several skills, references, and an MCP connection. A full-featured package can also include an agent, a hook, and a connector map. The point is not that the largest shape is the best shape. The point is that the package can add only the surfaces its work requires.
This is a useful design discipline. If a workflow is a self-contained transformation of an uploaded document, an MCP server may add needless dependency. If it must query a live CRM, a skill without a connector can only describe what the user should do manually. If it needs a deterministic check before a tool call, a hook may be relevant; if it only needs a structured answer, adding an autonomous agent may increase complexity without adding value. The manifest names the package, but the problem determines the layers.
Components are different interfaces
A skill is the central behavioral surface. It is a Markdown file with metadata that helps Claude recognize when the skill is relevant, followed by instructions for carrying out the work. The repository’s guidance emphasizes that the body is written for Claude, in imperative language, rather than as a user-facing brochure. A skill can specify how to gather evidence, what sequence to follow, how to handle missing inputs, and what output to produce. That makes it both domain knowledge and a procedure for applying that knowledge.
References sit behind the skill. They hold detailed material that does not need to be active in every interaction: advanced rules, schemas, troubleshooting guidance, examples, or domain-specific methods. This creates an interface between a concise workflow and a deeper body of knowledge. The skill decides when a reference matters; the reference supplies the detail. If the reference is removed, the skill may still trigger, but it loses depth or precision. If everything is placed in the main skill body, the workflow becomes harder to scan and more expensive to load.
The bio-research package illustrates why this separation matters. Its entry point describes several analysis skills, while the individual skills point to references for models, data preparation, environment setup, and troubleshooting. A reader does not need an inventory of every method to understand the architecture. The important relationship is that a compact task-specific instruction can lead to deeper material when the evidence or method requires it. Specialization is therefore not the same as putting an encyclopedia into every prompt.
Agents are a different interface again. The component schema describes them as specialized subagents with their own descriptions, model settings, and optional tool restrictions. They are suited to more autonomous multi-step analysis, such as examining a collection of tickets or producing a structured review. A skill can tell Claude how to perform a task in the current interaction; an agent can define a more distinct worker with a narrower role and tool surface. That distinction affects control and observability. An agent is not simply a longer skill, because it introduces another execution boundary.
Hooks operate at lifecycle events. The documented events include moments such as session start, before or after a tool use, a user prompt, or the end of a response. A hook can supply context, run a deterministic check, or ask for approval. Its position in the lifecycle is what makes it different from a skill: it may act because an event occurred, not because a user explicitly selected a domain workflow. That can be useful for validation, but it also makes scope important. A hook that observes every unrelated tool call has a different privacy and trust profile from one gated to a relevant project.
Legacy commands are an older single-file interface for slash commands. The repository’s management guidance says that they still work, but new plugins should generally use skills because the Cowork interface presents both concepts together and skills support progressive disclosure through references. This is a compatibility decision, not a claim that the two formats are identical. A command can be convenient when a workflow needs positional arguments or inline execution; a skill is the preferred shape for a new, reusable knowledge surface.
Finally, MCP configuration connects the package to an external service. The configuration says how a service can be reached—often through a remote HTTP endpoint or OAuth flow—but the skill still determines why and when that service is used. The MCP server is not the workflow’s reasoning layer. It is the boundary through which the workflow asks for data or requests an operation. This is why a plugin can be well-designed while still failing to produce its intended result when authentication is missing, a permission is denied, a field has changed, or a service is unavailable.
The interfaces can be summarized by the kind of question each layer answers. The manifest answers, “What package is this?” The skill answers, “What should happen for this kind of request?” A reference answers, “What deeper knowledge is needed?” A connector and MCP server answer, “Where can the workflow obtain or change external information?” An agent answers, “Which specialized worker should handle this multi-step analysis?” A hook answers, “What should happen at this lifecycle boundary?” Keeping those questions separate is what makes the architecture understandable.
It is useful to imagine those questions as a chain of checkpoints rather than as a stack of files. First, the host must identify a legitimate package. Then a request must match a skill’s description closely enough for the skill to be relevant. The skill may consult a reference when the task needs deeper rules or examples. If the task requires live information, the workflow crosses a connector boundary and reaches an MCP server. Only after that return path supplies usable evidence can the workflow produce a grounded result or request an operation. An agent or hook can intervene at a narrower point, but neither removes the need to know where the evidence came from or who owns the next decision.
Each checkpoint has a different failure mode. A missing manifest is a discovery failure: there is no stable package identity for the host to load. A vague skill description is a selection failure: the right knowledge may exist but never become active for the user’s wording. A missing reference is a depth failure: the workflow can start but may not contain the method needed for an unusual case. A broken connector is an access failure: the skill’s instructions remain, but the live evidence does not arrive. A poorly scoped hook is a control failure: it may observe or block work outside the plugin’s purpose. These are not interchangeable errors, so a useful diagnosis must say which boundary failed instead of reporting that “the plugin did not work.”
The component schemas also make a distinction between configuration and behavior. An MCP definition can specify an HTTP or server-sent-events transport, a URL, or an environment-variable expansion. That tells the runtime how to attempt a connection. It does not tell the skill which records are relevant, whether the returned fields mean what the skill expects, or whether a write should happen. Those decisions live in the workflow instructions and in the permissions of the connected service. Similarly, a hook can return an approval, block, or ask-user decision, but the value of that decision depends on which event it matches and what input it sees.
The three package examples in the management guidance make the same point at different scales. The minimal meeting-notes package has one clear transformation: read a transcript and produce structured notes. The standard code-quality package adds several skills, references, and a GitHub connection because its work involves both local conventions and external context. The full engineering-workflow example adds an agent, a hook, connectors, and multiple skills because it addresses coordination as well as analysis. The examples are not a maturity ladder in which every package should eventually become full-featured. They demonstrate that architecture should follow the number of distinct responsibilities and boundaries in the work.
That principle also protects the reader from a common category mistake. A reference is not a connector, because knowledge of a schema is not access to the system that implements it. An agent is not an authority grant, because a more autonomous worker still operates within the tools and permissions available to it. A hook is not a substitute for a domain workflow, because an event check may decide whether a tool call is acceptable without explaining how to answer the user’s underlying question. Treating the pieces as interchangeable makes a package look more capable on paper while hiding the conditions under which it can succeed.
Missing layers create predictable limits
A plugin without a reference layer may still be useful for a narrow task, but it cannot safely claim the same depth as one with detailed supporting material. A plugin without a connector can still work from pasted or uploaded information, but it cannot present a live view of a system it cannot query. A plugin with a connector but no validation guidance may retrieve data without knowing whether the result is complete, current, or interpreted with the right schema. A plugin with a hook can enforce a check, but the check’s scope and output determine whether it protects the user or merely adds friction.
The same logic applies to authority. The components can make an action technically possible without making every discovered instruction legitimate. A skill may know how to update a CRM, an MCP server may expose the update operation, and a connector may allow it. That chain still needs a rule for who initiated the action and what confirmation is required. Architecture is therefore not only a map of capabilities. It is a map of boundaries between identity, knowledge, access, autonomy, and permission.
This also explains why a component list is a poor evaluation method. “It has skills, agents, hooks, and MCP” says little about whether those parts compose coherently. The more useful questions are causal. Which component triggers? What information crosses its interface? Who owns the relevant state? What happens if the next service refuses the request? Is the resulting output a finding, a proposal, or an external change? The repository’s own examples are strongest when they answer those questions inside a concrete workflow.
Once the components are separated by responsibility, a further problem becomes visible. A skill can be deep enough to support a specialist domain while still needing a compact active surface. The repository addresses that problem by separating trigger metadata, core instructions, and detailed references. The next question is therefore not whether a plugin can contain more knowledge, but how it decides what knowledge to bring forward at the moment of work.