improve cursor rulesFrontmatter Extensions: Priority, Linked Examples, Parent Rule, Example Types

Feature Requests
1

Feature request for product/service

– Other –

Describe the request

Frontmatter Extensions: Priority, Linked Examples, Parent Rule, Example Types (New Feature)

To align with common usage patterns and improve rule organization and discoverability, add official support for the following frontmatter fields with well-defined semantics and UI/CLI behavior.

Fields and Semantics

---
# Rule metadata
priority: 100            # number; lower runs/attaches earlier; default 100
linkedExamples: "001-core-python-rules-example.mdc"  # path or array of paths
parentRule: "001-core-python-rules.mdc"  # for example/example-collections only
exampleTypes: ["good", "bad", "explanation"]  # examples-only; recognized types
---

  • priority:

    • Purpose: deterministic ordering when multiple rules auto-attach.
    • Behavior: lower values attach earlier; ties broken by path then filename.
    • Scope: applicable to any rule; optional; default 100.

  • linkedExamples:

    • Purpose: attach curated example files to the rule for quick reference.
    • Behavior: UI surfaces an “Examples” panel with links; CLI can print paths.
    • Types: string (single) or string (multiple); relative to workspace root.

  • parentRule:

    • Purpose: allow example packs to declare their parent canonical rule.
    • Behavior: when a parent rule is attached, its children with matching parentRule become discoverable via “Examples” (manual opt-in to attach).
    • Scope: examples-only; ignored on canonical rules.

  • exampleTypes:

    • Purpose: label examples for rendering and testing (good vs bad vs explanation).
    • Behavior: UI badges; optional filters; CLI flag --example-type for selection.
    • Allowed values (extensible): good, bad, explanation, pattern, anti-pattern.

UI/CLI Additions

  • UI

    • Sort attached rules by priority.
    • Show “Examples” section sourced from linkedExamples or children with parentRule.
    • Badges for exampleTypes and filters in the Examples view.

  • CLI

    • cursor rules list --sort priority
    • cursor rules examples --rule <id> [--example-type good|bad|explanation]

Validation

  • priority: must be an integer between 0 and 10000 (configurable thresholds).
  • linkedExamples: must resolve to existing files in the workspace.
  • parentRule: must resolve to an existing rule file; warn if missing.
  • exampleTypes: values must be from the allowed set; warn on unknown values.