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 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": "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, model (Claude Code and Grok Build, mapped through the model catalog), 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.

Imported SKILL.md frontmatter is bounded: 256 KiB per document, 10,000 YAML nodes, 32 nesting levels, 2,000 entries per mapping or sequence, and 64 KiB per string value. Documents over any limit are rejected before their YAML values are converted.

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, model) 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)
  }
}

Imported agent definitions are qualified by an aliased @use:

@use ./frontend-team as frontend
@use ./backend-team as backend

If both imports define reviewer, the resolved names are frontend.reviewer and backend.reviewer. Unique unaliased imports keep their original names. Conflicting unaliased definitions stop compilation with source and import diagnostics instead of silently overwriting one another. Native targets map dots to hyphens, so frontend.reviewer becomes frontend-reviewer.

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).

Agent model/specModel and skill model values resolve against the model catalog (built-in profiles plus models.profiles in promptscript.yaml). Write a floating alias (sonnet, opus, haiku, fable - newest Claude release), a pinned model (profile id, alias, API id, or display name such as claude-opus-5-5 or Claude Opus 5.5), or inherit. Each target gets its native name: Claude Code keeps aliases and uses API ids for pinned Claude models, GitHub Copilot gets display names (Claude Sonnet 5), Factory AI and Codex get API ids, and Cursor gets dateless ids. Names outside the catalog pass through unchanged, unless the target has its own spelling for them (GitHub Copilot writes auto as Auto). A model from a provider the target cannot run (a GPT model on Claude Code, a Claude model on Codex), or a name with a line break or control character, is omitted with a PS4004 warning.

@workflows

Repeatable multi-step agent procedures. Requires syntax 1.1.0.

@workflows {
  release: {
    description: "Prepare a validated release"
    content: """
      1. Run formatting, linting, type checks, and tests.
      2. Validate compiled output.
      3. Stop before publishing and request approval.
    """
  }
}

Targets with native workflow discovery emit dedicated workflow files. Other targets retain workflow instructions in their main output when supported.

@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.

@hooks

Portable lifecycle hooks. Requires syntax 1.4.0. Each hook needs exactly one of command or script.

@hooks {
  validate-types: {
    event: "post-tool-use"
    matcher: "Edit|Write"
    script: {
      path: ".promptscript/scripts/validate.py"
      interpreter: "python3"
      args: ["--strict"]
    }
    cwd: "project"
    timeoutMs: 120000
    statusMessage: "Checking TypeScript"
    continueOnFailure: false
    enabled: true
    targets: {
      factory: { matcher: "Execute" }
      vscode: { matcher: "run_in_terminal" }
      github: { enabled: false }
    }
  }
}

Portable events:

command is a non-empty string array. Shell interpolation ($(), backticks, ${...}) is forbidden. script requires:

• path under .promptscript/scripts/, using forward slashes.
• Existing regular file at compile time.
• No traversal, absolute path, invalid segment, or symlink escape.
• Explicit interpreter: python3, python, node, deno, bun, ruby, php, perl, bash, sh, zsh, pwsh, or powershell.
• Optional args string array; each argument remains one argument.

cwd: "project" runs from project root. Other values are portable forward-slash paths relative to project root. Hook config file location does not set command cwd. Environment-root and Git-root wrappers exit before script or command execution when the required root is unavailable. Native-cwd and workspace-cwd targets retain host cwd fields and report PS4002 when PromptScript cannot verify that cwd. timeoutMs range is 100-600000. matcher uses target-native tool names, so a matcher valid for one target may match nothing on another.

pre-terminal-command supplies native defaults: Factory Execute, Claude and Codex Bash, Windsurf pre_run_command, Cursor run_terminal_cmd, Gemini run_shell_command, and VS Code run_in_terminal. Override a native tool name with targets.<name>.matcher. Cursor, Gemini, and VS Code report best-effort PS4002 warnings. GitHub and Grok omit the event with PS4002.

Target overrides may change event, matcher, timeoutMs, statusMessage, continueOnFailure, enabled, or cwd. Native hook files are emitted only in target modes that support additional files:

OpenCode starts generated hook commands asynchronously. It enforces authored timeouts or a 30-second default, then escalates from SIGTERM to SIGKILL. Payloads are bounded by UTF-8 byte length. OpenCode tool hooks expose tool arguments, session ID, and call ID, but no model or agent context; compilation reports that limitation with PS4002.

Simple mode and targets without native project hooks report PS4002 instead of silently dropping hooks. Use prs compile --watch as fallback. Plugin-only and agent-scoped integrations are not emitted as universal project hooks.

Each generated command carries a PromptScript ownership marker. CLI cleanup removes only marked entries and preserves user hooks/settings. Removing @hooks removes a fully owned generated hook file and prunes directories left empty. prs hooks install factory migrates unambiguous legacy hooks from .factory/settings.json; ambiguous entries remain for manual review.

Factory compilation performs the same migration when .factory/hooks.json is absent. Use prs compile --dry-run to preview the changes or --no-migrate-factory-hooks to keep warning-only behavior. Unknown events, malformed entries, and mixed ownership abort without a partial migration.

@hooks compilation is separate from prs hooks install. The latter installs auto-compilation and generated-output protection for supported AI tools. Copilot VS Code Agent hooks use promptscript-vscode.json; GitHub Copilot repository hooks use promptscript.json.

@mcpServers

Project-local Model Context Protocol servers. Requires syntax 1.4.0.

@mcpServers {
  issue-tracker: {
    transport: "stdio"
    command: ["node", "./tools/issues.mjs"]
    env: { LOG_LEVEL: "info" }
  }
}

Use stdio with command, or http/sse with url. Keep credentials out of .prs files and provide them through target-native secret management.

@plugins

Portable capability bundles. Requires syntax 1.4.0.

@plugins {
  security-suite: {
    description: "Security review tooling"
    version: "1.0.0"
    skills: ["security-review"]
    hooks: ["validate-types"]
    mcpServers: ["issue-tracker"]
  }
}

@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 (imported source wins same-shape conflicts)
• Arrays: unique concatenation
• Shape mismatch: existing target body wins

Under syntax 1.5.0, later local blocks, @extend, and @override operations apply to the accumulated import result in declaration order.

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.

Replacing complete targets with @override

Syntax 1.5.0 adds atomic replacement for an existing block or nested value:

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

@standards {
  testing: ["Use Jest", "Use Mocha"]
}

@override standards.testing {
  ["Use Vitest"]
}

@override requires the complete target path to exist, applies in declaration order, and cannot bypass sealed skill properties. Later @extend declarations merge into the replacement. Use @extend for additive changes, field! for compatibility replacement of one direct regular field, and @override for intentional complete replacement.

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.