In Lesson 2, you examined the SKILL.md: the intelligence layer of a Cowork plugin, written in plain English and owned by the knowledge worker. The SKILL.md tells the agent who it is, what it does, and how it behaves. But a SKILL.md without infrastructure is an expert locked in an empty room. The surrounding files (plugin.json, .mcp.json, and settings.json) provide the identity, data connections, and default configuration that make the agent operational.
These infrastructure components are owned by developers and IT, not by the knowledge worker. This is not a limitation; it is a design choice that reflects where the technical complexity actually sits. Your role with respect to these files is not to author them but to understand them well enough to verify that they match your intentions, and to detect when something is wrong. That combination (sufficient understanding without operational responsibility) is what this lesson will build.
There is a professional skill embedded in this lesson that does not have a widely used name but deserves one: infrastructure literacy. It means knowing enough about the systems you depend on to detect problems accurately, describe them precisely, and have productive conversations with the people who fix them. It is not about becoming a systems engineer. It is about being a competent professional user of complex infrastructure.
Before examining each file individually, it helps to see where they live in relation to each other. A Cowork plugin is a directory with a specific structure:
Notice the division of labour built into this structure. The skills/ directory is where your SKILL.md files live: the intelligence layer you author. Everything else is infrastructure that developers and IT maintain. Anthropic designed these as plain Markdown and JSON files so that anyone can contribute; but in enterprise environments, clear ownership of each component prevents governance gaps. This lesson covers the three infrastructure files that matter most for your understanding: plugin.json, .mcp.json, and settings.json.
The plugin.json file lives inside the .claude-plugin/ directory. It is the plugin's identity card: and it is deliberately minimal. Here is the complete plugin.json for a Financial Research Agent:
That is the entire file. Four fields: name, description, version, and author.
This minimalism surprises people. If you expected the manifest to be the "main configuration file" containing the agent's instructions, permissions, and data connections, that expectation is wrong: and the mismatch is worth understanding.
The name field is a machine-readable identifier. It determines how the Cowork platform references this plugin internally and how it appears in deployment systems. The description field tells the plugin manager (and anyone browsing the marketplace) what this plugin does. It is displayed in discovery interfaces and should clearly state the plugin's purpose. The version field matters for change management: when IT updates any file in the plugin, the version number makes it possible to trace which configuration was in effect at any point in time. The author field identifies ownership: useful for auditing and for knowing which team to contact when something needs to change.
What plugin.json does not contain is equally important. It does not contain the agent's instructions (that is the SKILL.md). It does not configure data connections (that is .mcp.json). It does not set governance policies like audit logging or shadow mode (those are configured in Cowork's organisation admin panel, not in any file within the plugin). The manifest identifies the plugin. Other components configure it.
The .mcp.json file is where the plugin's data connections are declared. It specifies which MCP (Model Context Protocol) servers the plugin connects to: and through those servers, which external systems the agent can access.
An MCP server is a small service that acts as a bridge between the agent and an external system. When the Financial Research Agent needs current market data, it does not connect to a financial data provider directly. It communicates with that provider's MCP server, which handles authentication, executes queries, translates data formats, and returns structured results. Each external system the agent connects to has its own MCP server.
The .mcp.json file declares which of these servers the plugin uses. For the Financial Research Agent, it might declare connections to a financial data server, a Snowflake analytics server, and a SharePoint document server. Each entry names the server and provides its connection configuration: the address, the protocol, and any parameters needed to establish the connection.
This design has several advantages. The agent does not need to know how to authenticate with each external system: that complexity lives in the MCP server. The agent does not need to handle different data formats from different sources: the server normalises them. And when external systems change their APIs or authentication protocols, only the MCP server needs to be updated, not the agent itself.
Who writes .mcp.json? Developers and IT. They configure the servers, manage the credentials, and maintain the connections. Your role as the knowledge worker is to understand what the .mcp.json enables (which data sources your agent can reach) and to verify that those connections match the requirements of your workflow.
The practical literacy question is not how MCP servers work internally: that is an IT concern; but what state a connector is in at any given moment. There are three states:
Working. The MCP server is running, the authentication is valid, and queries return live data from the external system. When a connector is working, the agent has access to current information. Research reflects today's data, not last week's cached snapshot.
Explicitly unavailable. The MCP server is not running or cannot authenticate. In a well-configured system, the agent detects this state and tells the user it cannot access that data source. "I was unable to retrieve current market data for this analysis. Please verify the connector status with your IT team." This is the correct failure mode: it is transparent about the limitation.
Fabricating data. This is the dangerous failure mode, and it must be named explicitly. In a poorly designed or misconfigured system, when a connector is unavailable, the agent may draw on its training data or internal knowledge to produce responses that appear to be live data but are not. The output looks like a real market data response. The numbers are plausible. The format is correct. But the information is invented.
The reason this is categorically different from the second state is that it is undetectable without external verification. An agent that says "I cannot access the financial data connector" gives you accurate information about its limitations. An agent that generates a plausible-looking market data table without access to that connector has produced a hallucination presented as fact: and in a financial context, acting on fabricated data can have serious consequences.
Cowork's architecture is designed to make the third state unlikely. The platform and connector design enforce explicit failure reporting rather than silent substitution. But no architecture eliminates the risk entirely, which is why infrastructure literacy includes knowing this risk exists and building the habit of verifying data provenance when stakes are high.
The settings.json file configures default plugin behaviour. Its current primary use is the agent key, which activates a custom agent definition as the plugin's main conversation thread. When a plugin includes a settings.json with an agent key pointing to an agent file, that agent becomes the entry point when a user starts a session with the plugin.
This scope is deliberately narrow today (settings.json may support additional configuration keys as the platform evolves) but even a single key carries architectural significance. It means the plugin developer decides which agent a user interacts with by default, while the organisation retains the ability to override that choice through the admin panel.
The distinction between settings.json and governance controls is important. Settings.json lives inside the plugin package and configures developer-chosen defaults for plugin behaviour. Governance controls (audit logging, output review requirements, shadow mode, escalation routing) are configured by organisation administrators in Cowork's admin panel. They sit above the plugin, applying organisation-wide policies that no individual plugin can override.
This separation is a security design: the people who build plugins cannot weaken the governance controls that the organisation applies to them.
If you are wondering where audit logging, permission scopes, shadow mode, and escalation routing are configured: the answer is: not inside the plugin. These governance settings live above the plugin layer entirely, managed by administrators who set policies that apply across all plugins in the organisation.
Anthropic ships enterprise admin controls that include organisation-wide skill provisioning, audit capabilities, and policy management. These controls sit above individual plugins, applying organisation-wide policies that no individual plugin can override.
This means governance is not something a plugin author decides. It is something the organisation enforces. A plugin author cannot disable audit logging for their plugin, and a knowledge worker cannot bypass review requirements. The governance layer wraps around the plugin from the outside, which is precisely how enterprise security should work.
You will examine governance in detail in Lesson 7 when the chapter covers shadow mode and compliance frameworks. For now, the key point is architectural: governance is organisational, not per-plugin.
With all three infrastructure files in view, the division of labour becomes clear:
Component
What It Does
Who Owns It
plugin.json
Identifies the plugin (name, description, version, author)
Developers
.mcp.json
Declares data connections to external systems
Developers / IT
settings.json
Configures default plugin behaviour (e.g., activating a custom agent)
Developers
SKILL.md
Defines the agent's expertise and behaviour
Knowledge worker
Governance settings
Enforces organisational policies (audit, review, shadow mode)
Org administrators
Your contribution: the SKILL.md: sits at the centre. It is the intelligence that makes the agent useful. But it operates within the environment that the infrastructure files create. A SKILL.md that instructs the agent to analyse financial market data only works if the .mcp.json declares the appropriate MCP server and IT has configured that server to be available. A SKILL.md that describes careful, audited research behaviour only matters if the organisation's governance settings actually enforce audit logging.
Understanding this relationship is what makes you an effective collaborator rather than someone who writes instructions in isolation and hopes the infrastructure team gets the rest right.
You do not need to build MCP servers, write plugin.json files, or manage settings.json. That work belongs to developers and IT. What you need is enough understanding to operate as a competent professional user of the infrastructure.
Capability
What It Looks Like in Practice
Verify connector alignment
Confirm that the MCP servers declared in .mcp.json match the data sources your workflow actually requires
Detect data quality issues
Recognise when an agent's output may be based on unavailable or stale data
Report problems accurately
Describe an infrastructure problem in terms IT can act on: "the Snowflake connector appears to be returning stale data, last updated three days ago" is more useful than "the agent seems off"
Understand the architecture
Know which file controls what, so you can direct questions to the right people
This is infrastructure literacy: not operational depth, but sufficient awareness to be a capable professional user and an effective collaborator with the people who maintain the infrastructure you depend on.
Use these prompts in Anthropic Cowork or your preferred AI assistant to practise reasoning about plugin infrastructure.
What you're learning: Understanding the plugin directory structure requires more than memorising file names: it requires knowing what each file controls and who is responsible for it. This prompt practises treating the infrastructure as a map of responsibilities, not just a list of files.
What you're learning: Infrastructure literacy includes knowing how to verify data provenance; not just trusting that the agent has access to what it is supposed to have access to. This prompt practises the reasoning process for high-stakes data verification, which is a core professional skill when working with AI-powered research tools.
What you're learning: Even though IT writes the .mcp.json and configures the MCP servers, the knowledge worker specifies the requirements. This prompt practises the communication skill of translating workflow needs into infrastructure requirements: clearly enough that IT can implement them correctly on the first pass.
The connectors (.mcp.json) and plugin infrastructure (manifest, commands, agents) are the IT-owned components of a Cowork plugin. The plugin manifest (plugin.json) configures the deployment environment (model, interface, permission scope, governance settings). MCP connectors are declared in .mcp.json and provide authenticated, continuously running connections that handle authentication and data translation from enterprise systems. The knowledge worker's role is not to author these components but to understand them well enough to verify and detect problems: a professional skill called infrastructure literacy.
📋Quick Reference
Access condensed key takeaways and quick reference notes for efficient review.
Free forever. No credit card required.
Ask