@a16njs/plugin-cursor

Cursor IDE plugin for a16n. Discovers and emits Cursor rules.

Stability

As of 1.0.0, the plugin's discover/emit behavior and supported-type contract are stable and follow semantic versioning: breaking changes to the public API bump the major version.

Installation

This plugin is bundled with the a16n CLI. For programmatic use:

npm install @a16njs/plugin-cursor

Supported Types

This plugin supports five customization types:

| Type | Format | Description | |------|--------|-------------| | GlobalPrompt | alwaysApply: true frontmatter | Always-active rules | | FileRule | globs: **/*.ts frontmatter | Triggered by file patterns | | SimpleAgentSkill | description: "..." frontmatter | Triggered by context matching | | AgentIgnore | .cursorignore file | Files/patterns to exclude | | AgentCommand | .cursor/commands/*.md files | Explicitly invoked slash commands |

Supported Files

Discovery

• .cursor/rules/**/*.mdc - MDC format rules with frontmatter (recursive)
• .cursor/skills/**/SKILL.md - Agent skills (recursive under category directories)
• .cursor/commands/**/*.md - Command files (recursive)
• .cursorignore - Gitignore-style patterns for files to exclude

Note: Legacy .cursorrules files are not supported. Use .cursor/rules/*.mdc instead.

Skills with paths: are refused at discovery (skipped). Cursor's paths: key scopes a skill to matching files and is not part of AgentSkills.io; a16n does not model it. Converting without that scoping would widen the skill's applicability, so the skill is not converted and a warning names the field.

Commands

Commands in .cursor/commands/*.md are prepackaged prompts invoked via /command-name.

Every command is discovered, and its content is preserved byte-for-byte. Commands are plain prompt text to Cursor — the filename is the command name and the whole file is the prompt — so nothing in a command file needs interpreting at discovery time.

Commands opening with a --- block get one approximated warning. Cursor commands do not support frontmatter, so such a block is prose the author wrote rather than configuration. a16n keeps it as body content and tells you it did, rather than stripping it or passing it through silently. This is common in half-migrated setups, since Claude Code commands do support frontmatter.

Emission

• Creates .cursor/rules/<name>.mdc files with appropriate frontmatter
• Creates .cursor/commands/<name>.md files for AgentCommand items
• Creates .cursorignore from AgentIgnore patterns

AgentSkills.io Spec Fields

Skills may carry license, compatibility, metadata, and allowed-tools. What happens to them depends on the surface being written and on whether Cursor acts on them:

| Field | .cursor/skills/*/SKILL.md | .cursor/rules/*.mdc | | --- | --- | --- | | license | Written | Dropped, approximated | | compatibility | Written | Dropped, approximated | | metadata | Written | Dropped, approximated | | allowed-tools | Written, but skipped | Dropped, skipped |

SKILL.md carries arbitrary frontmatter keys, so nothing is lost on disk. .mdc has a fixed schema and carries none of them.

allowed-tools warns even where it is written, because Cursor does not enforce tool restrictions: the emitted skill is more permissive than the source. That is a behavior change, not a formatting one, so it fails closed — and --delete-source will keep the original file as a result.

Exactly one warning is raised per skill per surface, naming the fields actually lost, rather than one warning per field.

MDC Format

Cursor uses MDC (Markdown Configuration) format with YAML frontmatter:

---
alwaysApply: true
---

Always-applied rule content.

---
globs: **/*.tsx,**/*.jsx
---

React-specific guidelines.

---
description: Authentication and authorization patterns
---

Auth-related guidelines.

Usage

import cursorPlugin from '@a16njs/plugin-cursor';
import { A16nEngine } from '@a16njs/engine';

const engine = new A16nEngine([cursorPlugin]);

// Discover Cursor rules
const result = await cursorPlugin.discover('./my-project');
console.log(`Found ${result.items.length} rules`);

// Emit to Cursor format
await cursorPlugin.emit(result.items, './my-project');

Documentation

Full documentation available at https://texarkanine.github.io/a16n/plugin-cursor.