/promptscript

name: promptscript
description: >-
  PromptScript language expert for reading, writing, modifying, and
  troubleshooting .prs files. Use when working with PromptScript syntax,
  creating or editing .prs files, adding blocks like @identity, @standards,
  @restrictions, @shortcuts, @skills, or @agents, configuring
  promptscript.yaml, resolving compilation errors, understanding inheritance
  (@inherit), composition (@use, @extend, @override), contextual @header
  metadata, or migrating AI instructions
  to PromptScript. Also use when asked about the 48 built-in compilation
  targets, including GitHub Copilot, Claude Code, Cursor, Antigravity,
  Factory AI, and AGENTS.md-based platforms.
license: MIT
metadata:
  author: PromptScript
  homepage: https://getpromptscript.dev
compatibility:
  - claude-code
  - github-copilot
  - cursor
  - factory-ai
  - gemini-cli
  - opencode
  - windsurf
  - cline
  - roo
  - codex
  - continue
  - augment
  - goose
  - kilo
  - amp
  - trae
  - junie
  - kiro-cli
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Bash
user-invocable: true

PromptScript Language Guide

PromptScript is a domain-specific language that compiles `.prs` files into native instruction formats for AI coding assistants (GitHub Copilot, Claude Code, Cursor, Antigravity, Factory AI, OpenCode, Gemini CLI). One source of truth, multiple outputs.

File Structure

A `.prs` file contains ordered declarations. Syntax `1.5.0` applies `@inherit`, `@use`, local blocks, `@extend`, and `@override` in source order. Put `@meta` first.

# Comments start with #

@meta { ... }           # Required metadata
@inherit @path          # Single inheritance (optional)
@use @path [as alias]   # Imports/mixins (optional, multiple)

@identity { ... }       # AI persona
@context { ... }        # Project context
@standards { ... }      # Coding conventions
@restrictions { ... }   # Hard rules
@shortcuts { ... }      # Command aliases
@knowledge { ... }      # Reference documentation
@skills { ... }         # Reusable skill definitions
@agents { ... }         # Subagent definitions
@workflows { ... }      # Repeatable agent procedures
@examples { ... }       # Few-shot input/output examples (syntax 1.2.0+)
@params { ... }         # Template parameters
@guards { ... }         # File globs and priorities
@hooks { ... }          # Portable lifecycle hooks (syntax 1.4.0+)
@mcpServers { ... }     # MCP server configurations (syntax 1.4.0+)
@plugins { ... }        # Capability bundles (syntax 1.4.0+)
@local { ... }          # Private config (not committed)
@extend path { ... }    # Modify imported blocks
@override path { ... }  # Replace one complete existing target (syntax 1.5.0+)
@custom-name { ... }    # Arbitrary named blocks

Contextual `@header` entries appear inside supported owner blocks, not at the top level.

Content Types

PromptScript has four canonical content shapes inside blocks:

Text Content

Use triple quotes (three double-quote characters) to wrap multiline text. Text is automatically dedented - leading whitespace from source indentation is stripped. Use for prose, markdown, or freeform content.

Example: `@identity` with a text block describing an AI persona starting with "You are..."

Object Content (key-value pairs)

@context {
  project: "My App"
  team: "Frontend"
  monorepo: {
    tool: "Nx"
    packageManager: "pnpm"
  }
}

Values can be strings (quoted or unquoted), numbers, booleans, nested objects, or arrays.

Array Content

@standards {
  code: [
    "Use strict TypeScript",
    "Named exports only"
  ]
}

@restrictions {
  - "Never use any type"
  - "Never commit secrets"
}

Mixed Content

Blocks can contain both object properties and text in the same block. Place the triple-quoted text block alongside key-value pairs.

Block Reference

@meta (required)

@meta {
  id: "project-id"        # Required: unique identifier
  syntax: "1.0.0"         # Required: syntax version (semver)
  org: "Company Name"     # Optional
  team: "Frontend"        # Optional
  tags: [react, ts]       # Optional
  params: {               # Optional: template parameters
    projectName: string
    port: number = 3000
    debug?: boolean
    framework: enum("react", "vue") = "react"
  }
}

@identity

Defines AI persona. Start with "You are..." for consistent output across all formatters. Contains a triple-quoted text block with the persona description.

@context

Project context with structured properties (project, team, languages, runtime) plus optional triple-quoted text for architecture details, diagrams, etc.

@standards

Category-based conventions. Any category name is valid:

@standards {
  typescript: ["Strict mode", "No any type"]
  naming: ["Files: kebab-case.ts", "Classes: PascalCase"]
  git: {
    format: "Conventional Commits"
    types: [feat, fix, docs, refactor, test, chore]
  }
}

Category names are arbitrary. `@standards` can also contain free-form text:

@standards {
  """
  ## Formatting
  Preserve heading structure and use four-space indentation.

  ## Testing
  Add regression coverage for every behavior change.
  """
  typescript: ["Strict mode", "Named exports only"]
  git: {
    format: "Conventional Commits"
  }
}

Free-form text is dedented and rendered with its Markdown heading structure. Factory monolith output nests it under `Conventions & Patterns`; split Factory rules adjust heading levels relative to the generated section. Custom structured categories remain available to formatters that support them.

@restrictions

Hard rules as a list of dash-prefixed strings:

@restrictions {
  - "Never expose API keys"
  - "Never commit secrets to version control"
  - "Always validate user input"
}

@shortcuts

Simple strings appear as documentation. Objects with `prompt: true` generate executable prompt/command files for GitHub Copilot and Cursor:

@shortcuts {
  "/review": "R