Managing Plugin Manifests and Component Metadata with Quality Gates in Cursor

The cursor/plugins repository enforces strict validation through a hierarchical manifest architecture that automatically discovers components and blocks broken metadata before publication.

The cursor/plugins repository operates as a multi-plugin marketplace where each extension lives in its own top-level directory and carries self-contained metadata files. By implementing automated quality gates through the scripts/validate-plugins.mjs validation script, the platform ensures every plugin can be safely discovered, rendered in the Cursor UI, and shipped to users without broken links or ambiguous metadata.

Manifest Architecture

The repository uses a three-tier metadata system that separates marketplace registration from individual plugin configuration and component-level documentation.

Central Marketplace Registry

The root-level .cursor-plugin/marketplace.json serves as the authoritative index for all plugins in the repository. This file enumerates every plugin with three critical fields:

• name: The unique identifier for the plugin
• source: The directory name where the plugin code resides
• description: A short summary displayed in the marketplace UI

For a plugin to be discoverable by the Cursor platform, it must appear in this central registry regardless of how complete its local metadata might be.

Per-Plugin Configuration

Each plugin directory contains a .cursor-plugin/plugin.json file that defines the extension's identity, runtime assets, and component locations. According to the source files, this manifest must include:

• Identity fields: name (kebab-case), displayName, version, description
• Attribution fields: author, license, logo
• Component pointers: skills, rules, agents (paths to component directories)
• Categorization fields: category, tags

The create-plugin/.cursor-plugin/plugin.json example demonstrates how these fields map to actual directory structures within the plugin folder.

Component-Level Metadata

Individual components—whether skills, rules, agents, or hooks—must contain embedded metadata so the platform can surface them correctly. Each component follows specific formatting requirements:

• Skills: skills/*/SKILL.md files containing YAML front-matter with name: and description: fields
• Rules: rules/*/*.mdc files with required front-matter metadata
• Agents: agents/*/*.md files with valid YAML headers
• Hooks: hooks/hooks.json with valid JSON structure
• MCP configurations: mcp.json for Model Context Protocol integrations

Quality Gates Implementation

The scripts/validate-plugins.mjs validation script enforces five critical quality gates before any plugin can be published to the marketplace.

Manifest Validity Checks

The validator ensures that every .cursor-plugin/plugin.json is well-formed JSON containing a kebab-case name field. It verifies that all declared component directories (skills/, rules/, agents/) actually exist and are reachable via relative paths. The script rejects any manifest containing absolute paths or ../ traversal sequences that could break the sandbox.

Component Discoverability Verification

For every component declared in a plugin manifest, the validator confirms the physical file exists at the specified path. This gate catches stale references where a developer might have moved or deleted a skill directory without updating the corresponding plugin.json entry.

Metadata Completeness Enforcement

Each markdown component must start with a YAML front-matter block containing at minimum a name: and description: field. The validator parses SKILL.md, .mdc files, and agent markdown to flag any missing front-matter as a hard failure, ensuring the UI can display human-readable labels for every component.

Marketplace Registration

The validator cross-references every plugin directory against the central .cursor-plugin/marketplace.json registry. It verifies that the source field matches the actual directory name and that the name field is unique across the entire repository.

Documentation Quality Standards

Every plugin must include a top-level README.md describing the plugin's purpose, installation steps, and component coverage. Optional assets such as logo files are checked for existence and correct relative referencing to prevent broken image links in the marketplace.

Running the Validation Script

Execute the quality gates locally before submitting a plugin to ensure compliance:

# From the repository root

node scripts/validate-plugins.mjs

The script outputs a structured report indicating pass/fail status for each gate:

✔ manifest.json is valid (create-plugin)
✔ all skill front‑matter present (docs-canvas)
✖ missing logo file (pr-review-canvas)
✖ plugin entry missing in marketplace.json (pstack)

Programmatic Manifest Access

You can integrate manifest validation into custom build pipelines using Node.js:

import fs from 'fs';
import path from 'path';

function loadPluginManifest(pluginDir) {
  const manifestPath = path.join(pluginDir, '.cursor-plugin', 'plugin.json');
  return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
}

// Example: verify that the `skills` field points to an existing folder
const manifest = loadPluginManifest('docs-canvas');
if (!fs.existsSync(path.join('docs-canvas', manifest.skills))) {
  throw new Error('Skills folder missing for docs-canvas');
}

This pattern allows CI/CD systems to fail builds immediately when component paths drift out of sync with the manifest declarations.

Adding New Components

When creating new skills that pass the quality gates, structure your markdown with standard YAML front-matter:

---
name: your-skill
description: Explain what the skill does in detail.
---

# Your Skill

Content that implements the functionality...

Place this file under skills/your-skill/SKILL.md within your plugin directory. The validator automatically detects any new markdown files in the skills directory and verifies they contain the required front-matter fields.

Summary

• The cursor/plugins repository uses a three-tier manifest system: central marketplace registry (.cursor-plugin/marketplace.json), per-plugin configuration (.cursor-plugin/plugin.json), and component-level metadata (front-matter in markdown files).
• The scripts/validate-plugins.mjs validation script enforces five quality gates: JSON validity, component discoverability, metadata completeness, marketplace registration, and documentation standards.
• Every component must include YAML front-matter with name and description fields to be surfaced in the Cursor UI.
• All paths must be relative; absolute paths and parent directory traversals are rejected by the validator.
• The human-readable checklist in create-plugin/skills/review-plugin-submission/SKILL.md provides additional guidance for reviewers.

Frequently Asked Questions

What happens if a plugin passes local tests but fails the quality gates?

The validator in scripts/validate-plugins.mjs runs independently of any plugin-specific test suites. Even if your code functions correctly, missing front-matter in a SKILL.md file or an unregistered entry in marketplace.json will block publication. Run the validation script locally before opening a pull request to catch these structural issues early.

Can I use absolute file paths in my plugin manifest?

No. The quality gates explicitly reject absolute paths or ../ traversals in the skills, rules, and agents fields of plugin.json. All component references must use relative paths from the plugin directory root to ensure portability and security within the Cursor platform's sandboxed environment.

How do I add a new skill to an existing plugin?

Create a new directory under your plugin's skills/ folder and add a SKILL.md file containing YAML front-matter with name: and description: fields. Update your .cursor-plugin/plugin.json to include the new skill path if required, then run node scripts/validate-plugins.mjs to verify the front-matter passes the metadata completeness gate.

Why does my plugin need an entry in marketplace.json if it already has a plugin.json?

The .cursor-plugin/marketplace.json serves as the central discovery mechanism for the Cursor platform. While plugin.json describes the plugin's internal structure, the marketplace registry tells the platform which directories contain valid plugins and provides the top-level description shown in the UI. Without this registration, automated discovery systems cannot locate your plugin regardless of how complete its local manifest may be.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}