promptscript

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 is made of blocks. Order doesn't matter except @meta should come first by convention.

# 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
@examples { ... }       # Few-shot input/output examples (syntax 1.2.0+)
@params { ... }         # Template parameters
@guards { ... }         # File globs and priorities
@local { ... }          # Private config (not committed)
@extend path { ... }    # Modify imported blocks
@custom-name { ... }    # Arbitrary named blocks

Content Types

PromptScript has three content types 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]
  }
}

@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": "Review code for quality"
  "/test": {
    prompt: true
    description: "Write unit tests"
    content: (triple-quoted text with instructions)
  }
}

@commands is a backwards-compatible alias for @shortcuts — prefer @shortcuts in new files.

@skills

Reusable skill definitions with metadata:

@skills {
  commit: {
    description: "Create git commits"
    trigger: "commit, git commit"
    disableModelInvocation: true
    userInvocable: true
    allowedTools: ["Bash", "Read"]
    content: (triple-quoted text with skill instructions)
  }
}

Properties: description (required), content (required), trigger, disableModelInvocation, userInvocable, allowedTools, context ("fork" or "inherit"), agent, requires, references, inputs, outputs.

The references property attaches external files to the skill's context:

@skills {
  architecture-review: {
    description: "Review architecture decisions"
    references: [
      ./references/architecture.md
      ./references/modules.md
    ]
    content: (triple-quoted text)
  }
}

Allowed file types: .md, .json, .yaml, .yml, .txt, .csv. Paths are resolved relative to the .prs file. Formatters emit referenced files alongside SKILL.md in the output directory.

Parameterized Skills

Skills in .promptscript/skills/<name>/SKILL.md support template parameters via YAML frontmatter. Define params in frontmatter and use {{variable}} in content:

---
name: review
description: 'Review {{language}} code for {{standard}}'
params:
  language:
    type: string
  standard:
    type: string
    default: 'best practices'
references:
  - references/architecture.md
---
Review the code using {{language}} conventions following {{standard}}.

The references field in SKILL.md frontmatter lists files to attach to the skill's context. Paths are relative to the SKILL.md file.

Pass values in @skills block:

@skills {
  review: {
    description: "Review code"
    language: "typescript"
    standard: "strict mode"
  }
}

Non-reserved properties (anything other than description, content, trigger, userInvocable, allowedTools, disableModelInvocation, context, agent, requires, inputs, outputs) are treated as skill parameter arguments.

Skill Dependencies

Skills can declare dependencies on other skills via requires:

@skills {
  deploy: {
    description: "Deploy service"
    requires: ["lint-check", "test-suite"]
    content: (triple-quoted text)
  }
}

The validator (PS016) checks that required skills exist, detects self-references, and catches circular dependency chains.

Skill Contracts (Inputs/Outputs)

Skills can declare typed inputs and outputs in SKILL.md frontmatter:

---
name: security-scan
description: 'Scan for vulnerabilities'
inputs:
  files:
    description: 'Files to scan'
    type: string
  severity:
    description: 'Minimum severity'
    type: enum
    options: [low, medium, high]
    default: medium
outputs:
  report:
    description: 'Scan report'
    type: string
  passed:
    description: 'Whether scan passed'
    type: boolean
---

Field types: string, number, boolean, enum (with options list). The validator (PS017) checks field types, ensures enum fields have options, and warns if param names collide with input names.

Shared Resources

Skills in a folder can share common resources via .promptscript/shared/:

.promptscript/
  shared/
    templates.md         # Shared across all skills
    style-guide.md
  skills/
    review/
      SKILL.md           # Gets @shared/templates.md, @shared/style-guide.md
    deploy/
      SKILL.md           # Also gets shared resources

Files in shared/ are automatically included in every skill with @shared/ prefix.

@agents

Custom subagent definitions. Compiles to .claude/agents/ for Claude Code, .github/agents/ for GitHub Copilot, .factory/droids/ for Factory AI, etc.

@agents {
  code-reviewer: {
    description: "Reviews code quality"
    tools: ["Read", "Grep", "Glob", "Bash"]
    model: "sonnet"
    permissionMode: "default"
    content: (triple-quoted text with agent instructions)
  }
}

Supports mixed models per agent: specModel sets a different model for Specification/planning mode (GitHub, Factory), specReasoningEffort sets reasoning effort for the spec model (Factory only, values: "low", "medium", "high").

Factory AI droids support additional properties: model (any model ID or "inherit"), reasoningEffort ("low", "medium", "high"), and tools (category name like "read-only" or array of tool IDs).

@examples

Structured few-shot examples for AI assistants (requires syntax 1.2.0):

@meta {
  id: "commit-style"
  syntax: "1.2.0"
}

@examples {
  feat-commit: {
    description: "Feature commit with scope"
    input: "Added user authentication with JWT tokens"
    output: "feat(auth): add JWT-based user authentication"
  }
}

Each entry is a named example with input and output (both required), plus optional description. Multi-line content uses triple-quoted strings.

Examples can also be attached to skills via the examples property:

@skills {
  commit: {
    description: "Create conventional commits"
    examples: {
      basic: {
        input: "Added dark mode toggle"
        output: "feat(settings): add dark mode toggle"
      }
    }
    content: (triple-quoted text)
  }
}

@knowledge

Reference documentation as triple-quoted text. Used for command references, API docs, and other material that should appear in the output.

@params

Template parameter definitions with types: string, number, boolean, enum("a", "b"). Optional parameters use ? suffix. Defaults use = value.

@guards

File glob patterns and priority rules for path-specific instructions.

@local

Private local configuration. Not included in compiled output or committed to git.

Inheritance and Composition

@inherit (single, linear)

One per file. Child blocks merge on top of parent:

@inherit @company/frontend-team
@inherit ./parent
@inherit @stacks/react-app(projectName: "my-app", port: 3000)

@use (multiple, mixins)

Import and merge fragments:

@use @core/security
@use @core/quality
@use ./local-config
@use @core/typescript as ts   # alias enables @extend access

URL imports (Go-module style)

Import directly from any Git repository by host path - no alias required:

@use github.com/acme/shared-standards/@fragments/security
@use gitlab.com/myorg/prompts/@stacks/python

Version pinning with @:

@use github.com/acme/shared-standards/@org/base@1.2.0    # exact version
@use github.com/acme/shared-standards/@org/base@^1.0.0   # semver range
@use github.com/acme/shared-standards/@org/base@main     # branch

Registry aliases

Short names for Git repository URLs, configured in promptscript.yaml:

registries:
  company:
    url: github.com/acme/promptscript-registry

Then use the alias as scope prefix:

@use @company/security
@inherit @company/base-config

Merge rules:

• Text: concatenated with deduplication
• Objects: deep merged (target wins on conflicts)
• Arrays: unique concatenation

Block Filtering

Control which blocks are imported using the reserved only and exclude parameters:

@use ./shared-config(only: ["skills", "context"])
@use ./shared-config(exclude: ["knowledge"])
@use ./shared-config(exclude: ["knowledge"], mode: "strict")

Rules:

• only and exclude are mutually exclusive — using both is a validation error (PS021)
• Values are block type names: identity, context, standards, knowledge, skills, shortcuts, agents, etc.
• Block filtering does not apply to @inherit directives

Markdown Imports

Import skills directly from .md files (v1.8+). No external tools needed:

@use ./skills/frontend-design.md
@use ./shared/commit.md as commit
@use github.com/anthropics/skills/commit@1.0.0
@use github.com/repo/skills/gitnexus         # directory → SKILL.md

Content detection: PromptScript blocks in .md are parsed as a .prs fragment; YAML frontmatter with name/description is loaded as a skill definition; otherwise content is treated as free-form knowledge.

CLI management:

prs skills add github.com/anthropics/skills/commit@1.0.0
prs skills remove commit
prs skills list
prs skills update

@extend (modify existing or imported blocks)

Use a direct path for inherited or local blocks:

@extend standards.testing {
  coverage: 95
}

Use an alias when targeting a specific imported block:

@use @core/typescript as ts

@extend ts.standards {
  testing: { coverage: 95 }
}

Replacing regular block fields

Syntax 1.3.0 supports explicit replacement of complete regular block field values:

@meta { id: "project" syntax: "1.3.0" }

@inherit ./company-base

@extend standards {
  testing!: ["Use Vitest"]
  linting: ["Use ESLint"]
}

testing! replaces the inherited value. Fields without ! keep normal merge behavior. Replacement works after @inherit and @use, including aliases and nested target paths. A missing field is set. The modifier is rejected for @skills, which retain their dedicated merge and sealing semantics.

Skill-aware @extend semantics

When extending a skill definition via @extend, individual skill properties follow specific merge strategies rather than the generic block merge rules:

Example — extending a base skill to add references and override content:

@use @company/skills as skills

@extend skills.code-review {
  content: (triple-quoted text with overridden instructions)
  references: [
    ./extra-context.md
  ]
}

The references array from the base skill and the overlay are combined (append). The content field from the overlay replaces the base (replace).

Reference negation

Use ! prefix in @extend to remove entries from a lower layer's append-strategy arrays:

@extend skills.code-review {
  references: [
    "!references/deprecated.md"
    "references/replacement.md"
  ]
}

Path matching is normalized ("!./foo.md" matches "foo.md"). Only works in @extend blocks on references and requires. Validator PS028 warns about ! in base definitions.

Overlay consistency warnings

The resolver emits warnings during compile when an overlay drifts from its base. Always shown (not gated by --verbose):

• Orphaned extend — @extend target "X" not found — overlay will be ignored. Triggered when the targeted block doesn't exist (base removed or renamed).
• Stale skill target — @extend creates new skill "X" — base does not define it. Triggered when an @extend inside @skills would create a new skill instead of extending an existing one.
• Negation orphan — Negation "!path" did not match any base entry — it may be stale. Triggered when a !entry in references/requires doesn't match anything in the base.

These come from the resolver, not the validator (PS0XX rules). They appear during prs compile, not prs validate.

Sealed properties

Prevent @extend from overriding specified replace-strategy properties:

@skills {
  deploy: {
    content: (triple-quoted text with critical workflow)
    sealed: ["content", "description"]
  }
}

sealed: true seals all replace-strategy properties. Attempting to override a sealed property is a hard compilation error. Only the base skill author can set sealed — overlays cannot add or modify it. Append-strategy properties remain extendable. Validator PS029 warns about invalid entries in sealed.

Skill composition (inline @use)

Import sub-skills within a @skills block to compose multi-phase workflows:

@skills {
  ops: {
    description: "Production triage"
    content: (triple-quoted text with orchestrator instructions)
  }
  @use ./phases/health-scan
  @use ./phases/triage
  @use ./phases/code-fix as autofix
}

Each @use resolves the referenced .prs file, extracts its skill definition and context blocks, and flattens them as numbered phase sections into the parent skill's content. The as alias form controls the phase display name. Validator PS027 checks composition validity.

Parameterized Inheritance (Template Variables)

Use {{variable}} placeholders in a parent/template file, and pass values from the child file via @inherit or @use with (key: value) syntax.

IMPORTANT: Variables are NOT set from promptscript.yaml or CLI. They are passed from one .prs file to another through @inherit or @use.

Step 1: Create the template (parent file with params in @meta):

# base.prs - reusable template
@meta {
  id: "service-template"
  syntax: "1.0.0"
  params: {
    serviceName: string
    port?: number = 3000
  }
}

@identity {
  """
  You are working on {{serviceName}} running on port {{port}}.
  """
}

Step 2: Inherit with values (child file passes params):

# project.prs - concrete project
@meta { id: "user-api" syntax: "1.0.0" }

@inherit ./base(serviceName: "user-api", port: 8080)

After compilation, {{serviceName}} becomes user-api and {{port}} becomes 8080.

The same works with @use:

@use ./base(serviceName: "auth-service") as auth

Parameter types: string, number, boolean, enum("a", "b"). Optional params use ? suffix. Defaults use = value. Missing required params produce a compile error.

Multi-service pattern - reuse one template across many projects:

services/
  base.prs                          # template with params
  user-api/
    promptscript.yaml               # source: project.prs
    project.prs                     # @inherit ../base(serviceName: "user-api")
  auth-service/
    promptscript.yaml
    project.prs                     # @inherit ../base(serviceName: "auth-service")

Configuration: promptscript.yaml

Auto-injection

This skill is automatically included when compiling with prs compile. No manual copying needed. To disable, set includePromptScriptSkill: false in your promptscript.yaml.

id: my-project
syntax: "1.1.0"
description: "My project description"
input:
  entry: .promptscript/project.prs
  include: ['.promptscript/**/*.prs']
targets:
  github:
    version: full      # simple | multifile | full
  claude:
    version: full
  cursor:
    version: standard
  antigravity:
    version: frontmatter
  factory:
    version: full
  windsurf:             # 41 additional targets supported
    version: simple
  cline:
    version: simple
registry:
  git: https://github.com/org/registry.git
  ref: main
registries:
  company:
    url: github.com/acme/promptscript-registry
  oss:
    url: github.com/prscrpt/community-registry
    ref: v2
policies:
  - name: adjacent-layers-only
    kind: layer-boundary
    severity: error
    layers: ['@core', '@team', '@project']
    maxDistance: 1

Lockfile: promptscript.lock

When remote imports are used, prs compile automatically generates a lockfile recording the exact resolved commit for each dependency. Integrity hashes (SHA-256) are included for registry references to detect tampering or drift. This enables reproducible builds across machines and CI. Commit promptscript.lock to version control.

Use --ignore-hashes on prs compile or prs validate to skip integrity hash verification when needed.

Policy Engine

Define organizational policies in promptscript.yaml to validate skill extensions:

policies:
  - name: adjacent-layers-only
    kind: layer-boundary
    description: 'Only adjacent layers can extend each other'
    severity: error
    layers: ['@core', '@team', '@project']
    maxDistance: 1

  - name: protect-content
    kind: property-protection
    description: 'Content override requires explicit approval'
    severity: warning
    properties: ['content', 'description']

  - name: approved-registries
    kind: registry-allowlist
    description: 'Extensions must come from approved registries'
    severity: error
    allowed: ['@core', '@team']

Policy kinds: layer-boundary (controls layer distance), property-protection (prevents overriding specific properties), registry-allowlist (restricts extension sources). Severity: error (fails validation) or warning (reported only). Skip with --skip-policies during development (never in CI).

Syntax Version Validation

The syntax field in @meta declares the PromptScript language version (semver).

Known Versions

Block Version Requirements

All other built-in blocks are available from 1.0.0. Regular block field replacement with field!: value requires syntax 1.3.0.

Validation Rules

• PS018 (syntax-version-compat): warns when resolved blocks or syntax features require a higher version than declared. Requirements from inheritance, imports, and skill composition are included. Suggestion: run prs validate --fix.
• PS019 (unknown-block-name): warns when a block name is not a known PromptScript type, with fuzzy-match suggestions for typos.
• PS021 (use-block-filter): errors when only and exclude are both specified in @use parameters.
• PS025 (valid-skill-references): errors when a references entry points to a file with a disallowed extension or a path that cannot be resolved.
• PS026 (safe-reference-content): warns when a referenced file contains potentially sensitive content (e.g., secrets, credentials).
• PS027 (valid-skill-composition): warns about conflicting phase names or excessive phases in composed skills.
• PS028 (valid-append-negation): warns when negation prefix ! appears in base skill definitions (only effective in @extend).
• PS029 (valid-sealed-property): warns when sealed contains non-replace-strategy property names.
• PS030 (policy-compliance): validates skill extensions against organizational policies defined in promptscript.yaml.

Fixing Syntax Versions

prs validate --fix          # Auto-fix syntax versions in .prs files
prs upgrade                 # Upgrade all .prs files to the latest version

--fix rewrites the syntax: "..." line in each file's @meta block to match the minimum version required by resolved blocks and syntax features. It follows inheritance, imports, and skill composition. It only upgrades, never downgrades.

prs upgrade upgrades all files to the latest known syntax version regardless of what blocks they use.

CLI Commands

prs init                    # Initialize project (auto-detects existing files)
prs init --auto-import      # Initialize + static import of existing files
prs migrate                 # Interactive migration flow
prs migrate --static        # Non-interactive static import
prs migrate --llm           # Generate AI-assisted migration prompt
prs compile                 # Compile to all targets
prs compile --watch         # Watch mode
prs compile --ignore-hashes # Skip integrity hash verification
prs build <name>            # Compile a named build profile
prs validate --strict       # Validate syntax
prs validate --fix          # Auto-fix syntax version declarations
prs validate --skip-policies # Skip policy engine evaluation
prs upgrade                 # Upgrade all .prs files to latest syntax version
prs import CLAUDE.md        # Import existing AI instructions
prs import CLAUDE.md --dry-run # Preview import conversion
prs inspect <skill>         # Show skill composition provenance
prs inspect <skill> --layers # Show layer-level breakdown
prs hooks install           # Install auto-compilation hooks for AI tools
prs hooks install claude    # Install hooks for a specific tool
prs skills add <source>     # Add a remote skill (@use + lock update + SKILL.md validation)
prs skills add <source> --strict          # Treat validation warnings as errors
prs skills add <source> --skip-validation # Bypass Agent Skills spec checks (not recommended)
prs skills remove <name>    # Remove a skill (@use line + lock entry)
prs skills list             # List all imported skills
prs skills update           # Re-resolve markdown-imported skills (re-validates + re-hashes)
prs pull                    # Update registry
prs diff --target claude    # Show compilation diff
prs lock                    # Generate/update promptscript.lock
prs lock --dry-run          # Preview lockfile changes
prs update                  # Re-resolve all remote imports to latest
prs update <url>            # Update a specific registry
prs vendor sync             # Copy cached deps to .promptscript/vendor/
prs vendor check            # Verify vendor matches lockfile
prs resolve @alias/path     # Debug: show how an import resolves
prs registry list           # Show configured registries and aliases
prs registry add <alias> <url>  # Add a registry alias

Output Targets

48 supported targets. Key examples:

Formatter Documentation

For detailed information about each formatter's output paths, supported features, quirks, and example outputs:

• Full formatter reference: docs/reference/formatters/ (7 dedicated pages + index of all 48)
• llms-full.txt: Available at the docs site root - contains all documentation in a single file for LLM consumption
• Dedicated pages exist for: Claude Code, GitHub Copilot, Cursor, Antigravity, Factory AI, Gemini CLI, OpenCode
• All 48 formatters indexed at: docs/reference/formatters/index.md with output paths, tier, and feature flags

Auto-Compilation Hooks

Instead of running prs compile --watch manually, install hooks so your AI tool triggers compilation automatically when you edit .prs files:

prs hooks install          # Auto-detect and install for all detected tools
prs hooks install claude   # Install for a specific tool

Hooks also protect generated files from direct edits — when an AI agent tries to edit a compiled output (e.g., CLAUDE.md), the write is blocked with a message pointing to the source .prs file. Supported tools: Claude Code, Factory AI, Cursor, Windsurf, Cline, GitHub Copilot, Gemini CLI.

Project Organization

Typical modular structure:

.promptscript/
  project.prs      # Entry: @meta, @inherit, @use, @identity, @agents
  context.prs      # @context (architecture, tech stack)
  standards.prs    # @standards (coding conventions)
  restrictions.prs # @restrictions (hard rules)
  commands.prs     # @shortcuts and @knowledge

The entry file uses @use ./context, @use ./standards, etc. to compose them.

Common Mistakes

1. Missing @meta block - every .prs file needs @meta with id and syntax
2. Multiple @inherit - only one per file; use @use for additional imports
3. Extending an unknown path - target an inherited or local block, or use an imported alias
4. Unquoted strings with special chars - quote strings containing :, #, {, }
5. Forgetting to compile - .prs changes need prs compile to take effect
6. Triple quotes inside triple quotes - not supported; describe content textually instead
7. Using {{var}} in the root file without @inherit - template variables only work in a parent file that defines params in @meta, with values passed by the child via @inherit ./parent(key: value) or @use ./fragment(key: value). They are NOT set from promptscript.yaml or CLI flags
8. Using @examples with syntax: "1.0.0" or "1.1.0" - @examples requires syntax version 1.2.0. Run prs validate --fix to auto-upgrade

Migrating Existing AI Instructions to PromptScript

Automated: prs import

The fastest way to convert existing AI instructions to PromptScript:

prs import CLAUDE.md                    # Convert a single file
prs import .github/copilot-instructions.md
prs import AGENTS.md --output ./imported.prs
prs import --dry-run CLAUDE.md          # Preview without writing

prs import automatically:

• Detects the source format (Claude, GitHub Copilot, Cursor, Factory, etc.)
• Maps content to appropriate PromptScript blocks (@identity, @standards, etc.)
• Generates a valid .prs file with @meta block
• Preserves the original intent and structure

Supported source formats:

• CLAUDE.md (Claude Code)
• .github/copilot-instructions.md (GitHub Copilot)
• .cursorrules or .cursor/rules/*.mdc (Cursor)
• AGENTS.md (Factory AI / Codex)
• .clinerules (Cline), .roorules (Roo Code)
• .windsurf/rules/*.md (Windsurf)
• Any Markdown-based AI instruction file

Manual Migration

For complex migrations or when prs import needs refinement:

After import, split into modular files (context.prs, standards.prs, etc.) and compose with @use in project.prs. Run prs validate --strict then prs compile to verify output matches the original.