# Managing Plugin Manifests and Component Metadata with Quality Gates in Cursor

> Effectively manage plugin manifests and component metadata with quality gates. Cursor's repository enforces strict validation blocking broken metadata before publication.

- Repository: [Cursor/plugins](https://github.com/cursor/plugins)
- Tags: how-to-guide
- Published: 2026-05-25

---

**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`](https://github.com/cursor/plugins/blob/main/.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`](https://github.com/cursor/plugins/blob/main/.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`](https://github.com/cursor/plugins/blob/main/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`](https://github.com/cursor/plugins/blob/main/hooks/hooks.json) with valid JSON structure
- **MCP configurations**: [`mcp.json`](https://github.com/cursor/plugins/blob/main/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`](https://github.com/cursor/plugins/blob/main/.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`](https://github.com/cursor/plugins/blob/main/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`](https://github.com/cursor/plugins/blob/main/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`](https://github.com/cursor/plugins/blob/main/.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`](https://github.com/cursor/plugins/blob/main/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:

```bash

# 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:

```javascript
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:

```markdown
---
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`](https://github.com/cursor/plugins/blob/main/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`](https://github.com/cursor/plugins/blob/main/.cursor-plugin/marketplace.json)), per-plugin configuration ([`.cursor-plugin/plugin.json`](https://github.com/cursor/plugins/blob/main/.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`](https://github.com/cursor/plugins/blob/main/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`](https://github.com/cursor/plugins/blob/main/SKILL.md) file or an unregistered entry in [`marketplace.json`](https://github.com/cursor/plugins/blob/main/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`](https://github.com/cursor/plugins/blob/main/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`](https://github.com/cursor/plugins/blob/main/SKILL.md) file containing YAML front-matter with `name:` and `description:` fields. Update your [`.cursor-plugin/plugin.json`](https://github.com/cursor/plugins/blob/main/.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`](https://github.com/cursor/plugins/blob/main/.cursor-plugin/marketplace.json) serves as the central discovery mechanism for the Cursor platform. While [`plugin.json`](https://github.com/cursor/plugins/blob/main/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.