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

@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

---

Content truncated.