From directory to contract
The cursor/plugins repository solves a deceptively basic problem: how can a client discover many independent plugins without treating every folder as an unverified mystery? This chapter follows the path from the marketplace index to a plugin’s manifest and then through the checks that keep those two records aligned. The practical result is a way to tell structural validity from deeper trust.
The distinction matters because a marketplace is a coordination surface. A user needs a name to search for, a source to install, and enough metadata to know what kind of capability is being added. A contributor needs the same information to remain consistent after files move, versions change, or a plugin gains another component. The repository’s answer is to give the catalog and the plugin separate jobs, then connect them with schemas and validation.
Two records, two jobs
The marketplace manifest is the catalog’s index. It gives a marketplace a name, identifies its owner, and lists plugins by name and source. The source is the path that connects a catalog entry to a directory in the repository. The entry may also carry a short description or a client-version requirement. This is the information needed before a client opens the plugin itself.
The per-plugin manifest describes the unit found at that source. It gives the plugin its identifier and can add a display name, description, version, author, license, homepage, repository, keywords, category, and tags. More importantly, it declares the component surfaces that the host should discover. A plugin may point to skills, agents, rules, hooks, variables, or MCP servers. The marketplace says where to look. The plugin says what is there.
That separation prevents two common mistakes. The catalog description is not a substitute for the plugin manifest. A short sentence such as “search and update records” does not tell the host where the connection is configured or what setup it requires. The manifest is not a substitute for the catalog either. A perfectly formed local directory is not discoverable through this marketplace unless an entry points to it.
The relationship can be expressed as a simple chain. The marketplace entry names a source. The source contains a plugin manifest. The manifest declares components. A host can then resolve those declarations according to its own discovery rules. Each link has an owner, and each link can fail independently. A wrong source path breaks resolution before the plugin’s behavior is relevant. A missing component path breaks discovery inside an otherwise valid source. A remote connection can remain unavailable even when both metadata records are correct.
What the manifest contract carries
The schemas make several distinctions explicit. A plugin name must follow a constrained identifier pattern. A source must be present in a marketplace entry. Component declarations can be a single path or a collection of paths. MCP servers can be represented by a path, an inline object, or an array of either. Variables have an object-shaped schema and can declare required inputs. Client-version requirements can express a minimum version or never, which means that a client must not list or install the plugin.
These fields are not decorative. A component path determines what the host can discover. A variable declaration determines what configuration a user or administrator is expected to provide. A client gate prevents a capability from appearing in a runtime that cannot support it or should not expose it. A version gives maintainers a way to identify the state of the unit over time. The contract is therefore a small model of the plugin’s relationship with both the repository and the host.
The model is intentionally permissive about composition. A plugin does not have to contain every component type. The authoring workflow asks for the component set that fits a concrete use case. A focused skill plugin can remain a skill plugin. An integration can expose an MCP server without adding a large workflow layer. A more involved unit can combine a connection with guidance, as Google Docs does, or use a routing rule to decide between two kinds of Shopify work. The manifest provides the vocabulary without forcing every plugin into the same shape.
That flexibility creates a maintenance obligation. The more a plugin relies on explicit paths and multiple component types, the more ways it can drift. The repository addresses that obligation with checks that operate on the relationship between records rather than on either record in isolation.
The diagram is not a runtime call graph. It is a responsibility map. The Entry does not execute a skill. The PluginManifest does not itself validate a remote server. The Validator does not become part of the installed plugin. Keeping those roles separate is what lets the repository change one layer without pretending that the others have changed with it.
Validation is a path, not a stamp
The repository’s validation script begins with the marketplace file. It loads the marketplace schema and checks that the marketplace document is present and structurally valid. It then visits each indexed entry. For each source, it checks that the directory exists and that the expected .cursor-plugin/plugin.json file is present. It parses that manifest, validates it against the plugin schema, and compares the manifest name with the marketplace name.
The name comparison is a small check with a large consequence. If a catalog entry says one thing while the plugin declares another, a client or contributor has no stable identifier to use when referring to the unit. The validator turns that ambiguity into a visible failure instead of allowing two names to coexist until a user encounters the mismatch.
The script also checks version consistency across retained manifest forms. That matters when a plugin participates in more than one host or compatibility surface. A version that changes in one manifest but not another can make an update appear complete from one perspective and stale from another. The check does not decide which version should win. It prevents the repository from silently presenting inconsistent versions as if they were one fact.
After the repository-level validator, the pull-request workflow runs the validation command and a generated-harness check for pstack. The exact commands are less important than the timing. These checks run while a change is being proposed, when the source diff is still reviewable. The marketplace is maintained as a set of relationships, so the maintenance process must check relationships whenever the files that define them change.
The authoring plugin encodes a similar discipline before CI. Its quality rule requires relative paths inside the plugin directory, matching declared component paths to real files and folders, frontmatter for agent-facing components, focused scope, and installation or usage documentation. Its submission review checks the manifest, discoverability, metadata, marketplace registration, and README. The repository is therefore using the same idea at two scales. The authoring workflow helps a plugin become coherent. The repository validator helps the catalog remain coherent.
What each check can see
The checks form layers of confidence rather than one universal approval. Schema validation can see whether a document has the right shape, required fields, and permitted value types. Repository validation can see whether a marketplace source exists, whether a manifest is present, whether names match, and whether versions disagree. The pull-request workflow can see whether those checks pass for a proposed change and whether a generated pstack harness has drifted from its source.
Those layers answer different failure questions. A schema catches an invalid client-version value. A source check catches a path that points nowhere. A name check catches two records that identify the same location differently. A generated-copy check catches an artifact that no longer matches what the generator would produce. None of these checks needs to infer whether a skill is wise. Their strength comes from keeping the questions narrow enough to answer mechanically.
The next layer is outside the repository. A remote MCP server may be unavailable or may expose tool schemas that have changed. A client may implement a declared component differently from another client. A provider may apply permissions that the manifest cannot inspect. This is not a failure of schema validation. It is a boundary in the system. The correct response is to carry the structural result forward while asking for runtime and provider evidence where it matters.
A contributor can follow the same contract
Consider the path taken by a new plugin. The author first chooses a focused use case and a component mix. The scaffold workflow creates the manifest and the basic documentation, then records the component paths the plugin actually intends to expose. The author adds the plugin to the marketplace with a source path. At that point, two kinds of truth exist. The files say what the plugin contains. The index says where a client should find it. Neither is useful if the other is wrong.
The validator checks the join between them. It does not need to understand the plugin’s business purpose to find a missing source directory or a manifest whose name differs from the catalog entry. It can also catch a manifest that contains a value outside the schema, such as an invalid client-version requirement. This is a productive division of labor. The author and reviewer decide whether the component mix makes sense. The validator checks whether the declared relationships are internally consistent.
The pull-request workflow extends that path to generated artifacts. Pstack maintains a runtime-specific harness tree generated from source skills, agents, documentation, and an adapter. The generation check compares what is on disk with what the generator would produce. If the source changes but the copy is not regenerated, the failure is not that the new skill is necessarily wrong. The failure is that two distribution surfaces no longer agree about the same source. The check gives the maintainer a precise repair rather than leaving a future user to discover drift.
This is why the repository’s contract is best understood as a boundary around uncertainty. It narrows the questions that can be answered mechanically and makes the remaining questions visible. The process is not trying to turn every judgment into a Boolean. It is trying to ensure that a judgment begins with the right object, the right source, and the right version of the object.
Why small metadata errors become system errors
A broken path is not merely a documentation typo. It stops the host from finding the component the manifest claims to expose. An absolute path makes the package depend on the author’s machine rather than the plugin’s own location. Parent traversal breaks the assumption that a plugin owns the files it declares. Missing frontmatter leaves an agent-facing component without the metadata that helps the host or a reviewer understand it. A duplicate or mismatched name weakens the identity that the marketplace uses for discovery.
These failures are mechanical, but their effects are conceptual. They blur ownership. If a source path is wrong, it is unclear which directory a catalog entry means. If a component declaration is stale, it is unclear whether the advertised behavior exists. If versions diverge, it is unclear which runtime state a user has installed. The schemas and validator turn those questions into a narrow set of conditions that can be checked without asking a model to infer intent from prose.
That is the value of a contract surface. It does not make the plugin wise or secure. It makes certain classes of disagreement hard to ignore. The check can establish that a source exists, that a manifest parses, that names align, and that declared versions do not conflict. It cannot establish that a skill gives good advice, that a remote MCP server is available, or that a provider will enforce the least privilege a README recommends.
The boundary is especially important for fields that look authoritative. A description is still a description. A category is still a classification. A client gate can hide a plugin from one client, but it does not grant or revoke the account permissions used by an external service. A declared MCP server tells the host how to attempt a connection; it does not prove what tools the server exposes after the connection succeeds.
The contract makes the next question possible
The marketplace and manifest do more than prevent broken installation. They establish a stable place to ask what a plugin contributes. Once the source and identity are aligned, the reader can inspect the declared component mix without first wondering whether the catalog points to the right unit. Once the component paths are validated, the reader can ask which parts teach behavior, which parts route decisions, which parts trigger lifecycle work, and which parts connect to an external system.
That is the limit and the achievement of the contract. It creates a reliable doorway, not a guarantee about everything beyond the doorway. The next question is therefore behavioral rather than structural. Once a plugin is validly identified and installed, what can its different components teach, trigger, and connect?