Skip to content

CursorFormatter

PromptScript API


Defined in: formatters/src/formatters/cursor.ts:145

Formatter for Cursor rules and commands.

Supports four versions:

  • modern (default): .cursor/rules/project.mdc with YAML frontmatter
    • .cursor/commands/*.md for multi-line shortcuts
  • multifile: Multiple MDC files with glob-based targeting + commands
  • legacy: .cursorrules plain text (deprecated, no commands)
  • agents-md: Plain markdown at AGENTS.md (Cursor 2.4+) — no frontmatter

Slash Commands (Cursor 1.6+)

Multi-line @shortcuts are automatically converted to executable slash commands in .cursor/commands/:

@shortcuts {
// Single-line → stays in rules as documentation
"/review": "Review code quality"
// Multi-line → becomes .cursor/commands/test.md
"/test": \"""
Write unit tests using:
- Vitest as the test runner
- AAA pattern
\"""
}

Example

# Modern format (default)
targets:
- cursor
# Legacy format for older Cursor versions
targets:
- cursor:
version: legacy

See

Extends

Constructors

Constructor

new CursorFormatter(): CursorFormatter

Returns

CursorFormatter

Inherited from

BaseFormatter.constructor

Properties

defaultConvention

readonly defaultConvention: "markdown" = 'markdown'

Defined in: formatters/src/formatters/cursor.ts:149

Default convention for this formatter

Overrides

BaseFormatter.defaultConvention


description

readonly description: "Cursor rules (MDC with frontmatter)" = 'Cursor rules (MDC with frontmatter)'

Defined in: formatters/src/formatters/cursor.ts:148

Human-readable description

Overrides

BaseFormatter.description


name

readonly name: "cursor" = 'cursor'

Defined in: formatters/src/formatters/cursor.ts:146

Unique formatter identifier

Overrides

BaseFormatter.name


outputPath

readonly outputPath: ".cursor/rules/project.mdc" = CURSOR_VERSIONS.modern.outputPath

Defined in: formatters/src/formatters/cursor.ts:147

Default output file path

Overrides

BaseFormatter.outputPath


standardsExtractor

protected readonly standardsExtractor: StandardsExtractor

Defined in: formatters/src/base-formatter.ts:62

Shared standards extractor for consistent extraction across all formatters.

Inherited from

BaseFormatter.standardsExtractor


CONTEXT_RENDERED_KEYS

protected readonly static CONTEXT_RENDERED_KEYS: ReadonlySet<string>

Defined in: formatters/src/base-formatter.ts:288

@context keys that already have a dedicated rendering path. Anything outside this set is generic and must be surfaced by the context section.

Inherited from

BaseFormatter.CONTEXT_RENDERED_KEYS

Methods

appendGenericStandardItems()

protected appendGenericStandardItems(items, props, knownKeys): void

Defined in: formatters/src/base-formatter.ts:407

Append generic Label: value items for standards keys not handled by the known-key rendering in a section method. Keeps custom

Parameters

items

string[]

props

Record<string, Value>

knownKeys

ReadonlySet<string>

Returns

void

Standards

keys (git/config/documentation/diagrams) visible in monolith output. Skips null/undefined/false; renders bare labels for true.

Inherited from

BaseFormatter.appendGenericStandardItems


contextArchitectureProperty()

protected contextArchitectureProperty(ast): string | null

Defined in: formatters/src/base-formatter.ts:308

Read the architecture property of @context. Used as a fallback for sources that declare architecture as a property rather than as an ## Architecture heading inside the block text.

Parameters

ast

Program

Returns

string | null

Inherited from

BaseFormatter.contextArchitectureProperty


contextPropertyItems()

protected contextPropertyItems(ast, alsoRenderedKeys?): string[]

Defined in: formatters/src/base-formatter.ts:321

Render @context properties that no dedicated section consumes as Label: value items, so structured context is never silently dropped.

Parameters

ast

Program

alsoRenderedKeys?

readonly string[] = []

Returns

string[]

Inherited from

BaseFormatter.contextPropertyItems


contextTextConsumedByProject()

protected contextTextConsumedByProject(ast): boolean

Defined in: formatters/src/base-formatter.ts:274

Whether the @context block’s text is consumed by the project/intro fallback. Must mirror the project() and intro() consumption conditions exactly, otherwise the context section would either duplicate the text (predicate too narrow) or drop it entirely (predicate too wide).

Parameters

ast

Program

Returns

boolean

Inherited from

BaseFormatter.contextTextConsumedByProject


createRenderer()

protected createRenderer(options?): ConventionRenderer

Defined in: formatters/src/base-formatter.ts:68

Create a convention renderer for this formatter. Uses the provided convention from options or falls back to the default.

Parameters

options?

FormatOptions

Returns

ConventionRenderer

Inherited from

BaseFormatter.createRenderer


dedent()

protected dedent(text): string

Defined in: formatters/src/base-formatter.ts:863

Remove common leading whitespace from all lines (dedent). Handles the case where trim() was already called, causing the first line to lose its indentation while subsequent lines retain theirs. Calculates minimum indent from lines 2+ only.

Parameters

text

string

Returns

string

Inherited from

BaseFormatter.dedent


documentationItem()

protected documentationItem(value, defaultText): string | null

Defined in: formatters/src/base-formatter.ts:392

Resolve a documentation-standard entry that accepts either a boolean flag or author-supplied prose. A string value is authoritative and replaces the target’s default phrasing, so authored text is never silently discarded.

Parameters

value

Value | undefined

defaultText

string

Returns

string | null

Inherited from

BaseFormatter.documentationItem


extractContextTechStackItems()

protected extractContextTechStackItems(props): string[]

Defined in: formatters/src/base-formatter.ts:354

Collect @context tech-stack entries from every supported shape: an explicit techStack list plus the languages/runtime/monorepo properties.

Parameters

props

Record<string, Value>

Returns

string[]

Inherited from

BaseFormatter.extractContextTechStackItems


extractExamples()

protected extractExamples(ast): object[]

Defined in: formatters/src/base-formatter.ts:1036

Extract examples from the

Parameters

ast

Program

Returns

object[]

Examples

block. Returns an array of example definitions with name, input, output, and optional description.

Inherited from

BaseFormatter.extractExamples


extractSectionWithCodeBlock()

protected extractSectionWithCodeBlock(text, header): string | null

Defined in: formatters/src/base-formatter.ts:441

Safe extraction of a section that contains a header + content + code block + content Avoids ReDoS by using string search instead of backtracking regex. Matches pattern: Header … ...

Parameters

text

string

string

Returns

string | null

Inherited from

BaseFormatter.extractSectionWithCodeBlock


extractSkillExamples()

protected extractSkillExamples(skillProps): object[]

Defined in: formatters/src/base-formatter.ts:1049

Extract examples from a skill’s nested examples property. Returns the same shape as extractExamples.

Parameters

skillProps

Record<string, Value>

Returns

object[]

Inherited from

BaseFormatter.extractSkillExamples


extractSkills()

protected extractSkills(ast, options?): SkillFileConfig[]

Defined in: formatters/src/base-formatter.ts:1297

Extract skills from the

Parameters

ast

Program

options?

FormatOptions

Returns

SkillFileConfig[]

Skills

block, skipping unsafe names and skills excluded by the target’s skill filter.

Inherited from

BaseFormatter.extractSkills


extractText()

protected extractText(content): string

Defined in: formatters/src/base-formatter.ts:104

Extract text from block content.

Parameters

content

BlockContent

Returns

string

Inherited from

BaseFormatter.extractText


findBlock()

protected findBlock(ast, name): Block | undefined

Defined in: formatters/src/base-formatter.ts:97

Find a block by name, ignoring internal blocks (starting with __).

Parameters

ast

Program

name

string

Returns

Block | undefined

Inherited from

BaseFormatter.findBlock


format()

format(input, options?): FormatterOutput

Defined in: formatters/src/formatters/cursor.ts:174

Transform AST to target format

Parameters

input

Program

options?

FormatOptions

Returns

FormatterOutput

Overrides

BaseFormatter.format


formatArray()

protected formatArray(arr): string

Defined in: formatters/src/base-formatter.ts:155

Format an array as comma-separated string.

Parameters

arr

unknown[]

Returns

string

Inherited from

BaseFormatter.formatArray


formatCanonical()

formatCanonical(ast, options?): FormatterOutput

Defined in: formatters/src/base-formatter.ts:41

Canonical entry point for legacy implementations.

Subclasses can override this method to consume ordered canonical entries directly. Until then, keep the compatibility projection isolated here.

Parameters

ast

CanonicalProgram

options?

FormatOptions

Returns

FormatterOutput

Inherited from

BaseFormatter.formatCanonical


formatStandardsList()

protected formatStandardsList(items): string[]

Defined in: formatters/src/base-formatter.ts:147

Format standards list from array of values (pass-through). Returns array of strings for rendering as bullet list.

Parameters

items

Value

Returns

string[]

Inherited from

BaseFormatter.formatStandardsList


generateSkillFile()

protected generateSkillFile(config, options?): FormatterOutput | null

Defined in: formatters/src/base-formatter.ts:1337

Render a skill file at the target’s skill base path. Returns null when the target declares no skill support.

Parameters

config

SkillFileConfig

options?

FormatOptions

Returns

FormatterOutput | null

Inherited from

BaseFormatter.generateSkillFile


getArrayElements()

protected getArrayElements(content): Value[]

Defined in: formatters/src/base-formatter.ts:179

Extract array elements from block content.

Parameters

content

BlockContent

Returns

Value[]

Inherited from

BaseFormatter.getArrayElements


getBlockArrayElements()

protected getBlockArrayElements(block): Value[]

Defined in: formatters/src/base-formatter.ts:202

Parameters

block

Block

Returns

Value[]

Inherited from

BaseFormatter.getBlockArrayElements


getDotDir()

getDotDir(): string | null

Defined in: formatters/src/formatters/cursor.ts:162

Dot directory of the target, by default the parent of a <dir>/skills skill base path, or null when there is none.

Returns

string | null

Overrides

BaseFormatter.getDotDir


getMetaField()

protected getMetaField(ast, key): string | undefined

Defined in: formatters/src/base-formatter.ts:169

Get meta field value as string.

Parameters

ast

Program

key

string

Returns

string | undefined

Inherited from

BaseFormatter.getMetaField


getNativeAgentName()

protected getNativeAgentName(ast, name): string

Defined in: formatters/src/base-formatter.ts:1183

Return the deterministic native identifier for one agent.

Parameters

ast

Program

name

string

Returns

string

Inherited from

BaseFormatter.getNativeAgentName


getNativeAgentNameMap()

protected getNativeAgentNameMap(ast): ReadonlyMap<string, string>

Defined in: formatters/src/base-formatter.ts:1173

Map all agent names consistently for a target’s native files.

Parameters

ast

Program

Returns

ReadonlyMap<string, string>

Inherited from

BaseFormatter.getNativeAgentNameMap


getOutputPath()

protected getOutputPath(options?): string

Defined in: formatters/src/base-formatter.ts:90

Get the output path, respecting options override.

Parameters

options?

FormatOptions

Returns

string

Inherited from

BaseFormatter.getOutputPath


getPrettierOptions()

protected getPrettierOptions(options?): Required<PrettierMarkdownOptions>

Defined in: formatters/src/base-formatter.ts:80

Get resolved Prettier options, merging provided options with defaults.

Parameters

options?

FormatOptions

Returns

Required<PrettierMarkdownOptions>

Inherited from

BaseFormatter.getPrettierOptions


getProp()

protected getProp(content, key): Value | undefined

Defined in: formatters/src/base-formatter.ts:118

Get a specific property from block content.

Parameters

content

BlockContent

key

string

Returns

Value | undefined

Inherited from

BaseFormatter.getProp


getProps()

protected getProps(content): Record<string, Value>

Defined in: formatters/src/base-formatter.ts:132

Get all properties from block content.

Parameters

content

BlockContent

Returns

Record<string, Value>

Inherited from

BaseFormatter.getProps


getSkillBasePath()

getSkillBasePath(): string | null

Defined in: formatters/src/formatters/cursor.ts:166

Base path for skills, or null if formatter has no skill support.

Returns

string | null

Overrides

BaseFormatter.getSkillBasePath


getSkillFileName()

getSkillFileName(): string | null

Defined in: formatters/src/formatters/cursor.ts:170

Skill file name, or null if formatter has no skill support.

Returns

string | null

Overrides

BaseFormatter.getSkillFileName


humanizeLabel()

protected humanizeLabel(value): string

Defined in: formatters/src/base-formatter.ts:427

Convert a camelCase/kebab-case key into a human-readable label.

Parameters

value

string

Returns

string

Inherited from

BaseFormatter.humanizeLabel


isSafeAgentName()

protected isSafeAgentName(name): boolean

Defined in: formatters/src/base-formatter.ts:1166

Check if an agent name is safe for use in file paths.

Parameters

name

string

Returns

boolean

Inherited from

BaseFormatter.isSafeAgentName


isSafeName()

protected isSafeName(name): boolean

Defined in: formatters/src/base-formatter.ts:1146

Check if a name is safe for use in file paths. Rejects path traversal sequences and path separators.

Parameters

name

string

Returns

boolean

Inherited from

BaseFormatter.isSafeName


isSafeSkillName()

protected isSafeSkillName(name): boolean

Defined in: formatters/src/base-formatter.ts:1159

Check if a skill name is safe for use in file paths.

Parameters

name

string

Returns

boolean

Inherited from

BaseFormatter.isSafeSkillName


mergeRequiredSkillFrontmatter()

protected mergeRequiredSkillFrontmatter(rawFrontmatter, name, description): string

Defined in: formatters/src/base-formatter.ts:1265

Preserve raw skill frontmatter while supplying mandatory skill fields.

Parameters

rawFrontmatter

string

name

string

description

string

Returns

string

Inherited from

BaseFormatter.mergeRequiredSkillFrontmatter


normalizeMarkdownForPrettier()

protected normalizeMarkdownForPrettier(content): string

Defined in: formatters/src/base-formatter.ts:501

Normalize markdown content to match Prettier formatting.

  • Strips common leading indentation from lines
  • Trims trailing whitespace from lines
  • Normalizes markdown table formatting
  • Adds blank lines before lists when preceded by text
  • Adds blank lines before code blocks when preceded by text
  • Escapes markdown special characters in paths

The result must keep the meaning of the input: table cells, code spans and list nesting (including tight lists) are never changed.

With verbatimMarkdown (formatting.postFormat: false) only the common indentation is removed and the text stays as written.

Parameters

content

string

Returns

string

Inherited from

BaseFormatter.normalizeMarkdownForPrettier


normalizeOutputDir()

protected normalizeOutputDir(dir): string

Defined in: formatters/src/base-formatter.ts:896

Normalize a user-provided output directory (from @use ... into "<path>" or skillTargets config) to a safe forward-slash relative path. Rejects .., . and leading slashes so the result can be appended to a target’s dot-directory without escaping it.

Parameters

dir

string

Returns

string

Inherited from

BaseFormatter.normalizeOutputDir


normalizeResourcePath()

protected normalizeResourcePath(relativePath): string | null

Defined in: formatters/src/base-formatter.ts:963

Normalize a resource path to a safe, portable relative path.

Parameters

relativePath

string

Returns

string | null

Inherited from

BaseFormatter.normalizeResourcePath


referenceProvenance()

protected referenceProvenance(sourcePath): string

Defined in: formatters/src/base-formatter.ts:1138

Generate a provenance comment for a reference file.

Parameters

sourcePath

string

Returns

string

Inherited from

BaseFormatter.referenceProvenance


referencesMode()

referencesMode(): "none" | "directory" | "inline"

Defined in: formatters/src/formatters/cursor.ts:158

How this formatter handles skill references.

  • ‘directory’: emit as separate files in references/ subdirectory
  • ‘inline’: append as sections in the main output file
  • ‘none’: references not supported

Returns

"none" | "directory" | "inline"

Overrides

BaseFormatter.referencesMode


removeRawFrontmatterKeys()

protected removeRawFrontmatterKeys(rawFrontmatter, keys): string

Defined in: formatters/src/base-formatter.ts:1233

Remove top-level keys (with their nested lines) from raw SKILL.md frontmatter. Used for PromptScript-only keys such as params, which are resolved at compile time and mean nothing to the target tool.

Parameters

rawFrontmatter

string

keys

ReadonlySet<string>

Returns

string

Inherited from

BaseFormatter.removeRawFrontmatterKeys


renderCodeFence()

protected renderCodeFence(content, lang?): string

Defined in: formatters/src/base-formatter.ts:1409

Render content inside a code fence, using a longer fence if the content itself contains triple backticks (prevents code fence injection).

Parameters

content

string

lang?

string = ''

Returns

string

Inherited from

BaseFormatter.renderCodeFence


renderExamplesSection()

protected renderExamplesSection(ast, renderer, sectionName?): string | null

Defined in: formatters/src/base-formatter.ts:1065

Render an examples section from the

Parameters

ast

Program

renderer

ConventionRenderer

sectionName?

string = 'Examples'

Custom section heading name (default: ‘Examples’)

Returns

string | null

Examples

block. Shared rendering logic used by Claude, GitHub, and MarkdownInstructionFormatter.

Inherited from

BaseFormatter.renderExamplesSection


resolveSkillDir()

protected resolveSkillDir(defaultSkillBasePath, skillName, outputDir?, options?): string

Defined in: formatters/src/base-formatter.ts:926

Resolve the directory for a generated skill, respecting per-target skill base overrides while preserving existing @use ... into behavior.

Parameters

defaultSkillBasePath

string

skillName

string

outputDir?

string

options?

FormatOptions

Returns

string

Inherited from

BaseFormatter.resolveSkillDir


sanitizeResourceFiles()

protected sanitizeResourceFiles(resources, targetDir): FormatterOutput[]

Defined in: formatters/src/base-formatter.ts:982

Filter resource files to only include safe canonical paths.

Parameters

resources

object[] | undefined

targetDir

string

Returns

FormatterOutput[]

Inherited from

BaseFormatter.sanitizeResourceFiles


shiftContextHeadings()

protected shiftContextHeadings(text): string

Defined in: formatters/src/base-formatter.ts:846

Shift

Parameters

text

string

Returns

string

Context

headings so none of them reaches the formatter’s own h1 and h2 levels. All headings move by the same amount, so their relative levels stay as written. Text that already starts at h3 or deeper is kept as is.

Inherited from

BaseFormatter.shiftContextHeadings


shiftHeadingsToMinLevel()

protected shiftHeadingsToMinLevel(text, targetLevel): string

Defined in: formatters/src/base-formatter.ts:807

Shift all ATX headings by the same amount so the shallowest heading lands at targetLevel. Levels clamp to h1-h6 and fenced code blocks are ignored.

Parameters

text

string

targetLevel

number

Returns

string

Inherited from

BaseFormatter.shiftHeadingsToMinLevel


shortcutSummary()

protected shortcutSummary(value, fallback?): string

Defined in: formatters/src/base-formatter.ts:249

Extract a stable one-line summary from any supported shortcut value.

Parameters

value

Value

fallback?

string = ''

Returns

string

Inherited from

BaseFormatter.shortcutSummary


shouldIncludeSkill()

protected shouldIncludeSkill(name, options?): boolean

Defined in: formatters/src/base-formatter.ts:915

Return true when the target configuration allows emitting the given skill.

Parameters

name

string

options?

FormatOptions

Returns

boolean

Inherited from

BaseFormatter.shouldIncludeSkill


startFormat()

protected startFormat(options?): void

Defined in: formatters/src/base-formatter.ts:55

Call first in format, so markdown helpers know whether to keep the text as written. The state is reset on every call.

Parameters

options?

FormatOptions

Returns

void

Inherited from

BaseFormatter.startFormat


stripAllIndent()

protected stripAllIndent(content): string

Defined in: formatters/src/base-formatter.ts:673

Strip all leading indentation from markdown content. Used for AGENTS.md where content from multiple sources has inconsistent indentation. Preserves indentation inside code blocks.

With verbatimMarkdown only the common indentation is removed.

Parameters

content

string

Returns

string

Inherited from

BaseFormatter.stripAllIndent


transformInjectedSkillContent()

transformInjectedSkillContent(content): string

Defined in: formatters/src/base-formatter.ts:1131

Default pass-through for injected skill content. Formatters whose target tools restrict skill frontmatter (e.g. Factory AI) override this hook to filter unsupported fields before the compiler writes the file.

Parameters

content

string

Returns

string

Inherited from

BaseFormatter.transformInjectedSkillContent


truncate()

protected truncate(str, max): string

Defined in: formatters/src/base-formatter.ts:162

Truncate string to max length with ellipsis.

Parameters

str

string

max

number

Returns

string

Inherited from

BaseFormatter.truncate


valueToString()

protected valueToString(value): string

Defined in: formatters/src/base-formatter.ts:229

Convert value to string representation.

Parameters

value

Value

Returns

string

Inherited from

BaseFormatter.valueToString


yamlQuoted()

protected yamlQuoted(value): string

Defined in: formatters/src/base-formatter.ts:299

Escape a value for use inside a double-quoted YAML scalar.

Parameters

value

string

Returns

string

Inherited from

BaseFormatter.yamlQuoted


yamlString()

protected yamlString(value): string

Defined in: formatters/src/base-formatter.ts:1202

Serialize a string as a YAML scalar, quoting only when required.

Parameters

value

string

Returns

string

Inherited from

BaseFormatter.yamlString


getSupportedVersions()

static getSupportedVersions(): object

Defined in: formatters/src/formatters/cursor.ts:154

Get supported versions for this formatter.

Returns

object

agents-md

readonly agents-md: object

agents-md.cursorVersion

readonly cursorVersion: "2.4+" = '2.4+'

agents-md.description

readonly description: "Plain markdown at AGENTS.md (Cursor 2.4+) — no frontmatter required" = 'Plain markdown at AGENTS.md (Cursor 2.4+) — no frontmatter required'

agents-md.introduced

readonly introduced: "2025-06" = '2025-06'

agents-md.name

readonly name: "agents-md" = 'agents-md'

agents-md.outputPath

readonly outputPath: "AGENTS.md" = 'AGENTS.md'

full

readonly full: object

full.cursorVersion

readonly cursorVersion: "2.5+" = '2.5+'

full.description

readonly description: "MDC + skills (.agents/skills/<name>/SKILL.md) + subagents (.cursor/agents/<name>.md)" = 'MDC + skills (.agents/skills/<name>/SKILL.md) + subagents (.cursor/agents/<name>.md)'

full.introduced

readonly introduced: "2025-06" = '2025-06'

full.name

readonly name: "full" = 'full'

full.outputPath

readonly outputPath: ".cursor/rules/project.mdc" = '.cursor/rules/project.mdc'

legacy

readonly legacy: object

legacy.cursorVersion

readonly cursorVersion: "< 0.45" = '< 0.45'

legacy.deprecated

readonly deprecated: true = true

legacy.deprecatedSince

readonly deprecatedSince: "2024-12" = '2024-12'

legacy.description

readonly description: "Plain text format (.cursorrules) - DEPRECATED" = 'Plain text format (.cursorrules) - DEPRECATED'

legacy.name

readonly name: "legacy" = 'legacy'

legacy.outputPath

readonly outputPath: ".cursorrules" = '.cursorrules'

modern

readonly modern: object

modern.cursorVersion

readonly cursorVersion: "0.45+" = '0.45+'

modern.description

readonly description: "MDC format with YAML frontmatter (.cursor/rules/project.mdc) + slash commands (.cursor/commands/)" = 'MDC format with YAML frontmatter (.cursor/rules/project.mdc) + slash commands (.cursor/commands/)'

modern.introduced

readonly introduced: "2024-12" = '2024-12'

modern.name

readonly name: "modern" = 'modern'

modern.outputPath

readonly outputPath: ".cursor/rules/project.mdc" = '.cursor/rules/project.mdc'

multifile

readonly multifile: object

multifile.cursorVersion

readonly cursorVersion: "0.45+" = '0.45+'

multifile.description

readonly description: "Multiple MDC files with glob-based targeting + slash commands" = 'Multiple MDC files with glob-based targeting + slash commands'

multifile.introduced

readonly introduced: "2024-12" = '2024-12'

multifile.name

readonly name: "multifile" = 'multifile'

multifile.outputPath

readonly outputPath: ".cursor/rules/project.mdc" = '.cursor/rules/project.mdc'