DOCSEARCHbyAlgolia
Submit Docs

PromptScript Documentation

repository·main·Indexed 20 days ago

https://github.com/mrwogu/promptscript

An agent platform configuration-as-code tool for defining instructions, skills, agents, and workflows in a single source. PromptScript compiles .prs files into native configurations for over 48 AI coding platforms, including Claude, Cursor, and GitHub Copilot. The ecosystem includes a CLI for project management, a VS Code extension for syntax highlighting and language support, and a browser-compiler for client-side compilation using a virtual in-memory file system.

Tokens
294K
Snippets
830
Records
1.2K
Agent score
66%

What's inside PromptScript

  1. Overview of Supported PromptScript Formatters

    main

    PromptScript compiles a single agent platform definition into native files for 48 AI coding agent targets. These targets are categorized into three tiers based on their output complexity:

    1. Rich Native (9 targets): These use hand-crafted output logic to support unique file formats, skills, agents, and commands. They provide the highest level of integration with specific agent ecosystems.
    2. AGENTS.md (10 targets): Targets that primarily utilize the AGENTS.md format.
    3. Markdown (29 targets): Standard Markdown-based targets.

    PromptScript treats instructions, skills, agents, commands, MCP servers, hooks, workflows, and plugins as platform capabilities that are mapped to these targets.

  2. What is @promptscript/playground?

    main

    The @promptscript/playground is a web-based interactive editor designed for writing and previewing PromptScript (.prs) code in real time. It allows developers to see the compiled output directly in the browser without needing a local development environment or CLI setup.

    Note: This is a private internal package and is not published to npm. It is part of the PromptScript monorepo.

  3. Use @promptscript/parser for PromptScript language parsing

    main

    The @promptscript/parser package is a Chevrotain-based parser for the PromptScript language. It is an internal package bundled into @promptscript/cli and is not published to npm separately.

    It follows a three-stage architecture:

    1. Lexer (PSLexer): Tokenizes source text into a token stream.
    2. Parser (PromptScriptParser): Uses a Chevrotain grammar to generate a Concrete Syntax Tree (CST).
    3. Visitor (visitor): Transforms the CST into an immutable, source-ordered canonical AST (CanonicalProgram).

    For new integrations that require exact top-level and block-body source order, you should use the parseCanonical or parseCanonicalOrThrow functions.

  4. Features of PromptScript for VS Code

    main

    The extension provides the following editor enhancements for .prs files:

    • Syntax Highlighting: Full support for all PromptScript constructs.
    • Bracket Support: Bracket matching and auto-closing for {}, [], (), "", '', and {{}}.
    • Code Folding: Ability to fold code blocks using @block { } directives.
    • Comment Management: Toggle comments using Cmd+/ (macOS) or Ctrl+/ (Windows/Linux).
    • Auto-indentation: Automatic indentation when working inside blocks.
    • File Icons: Dedicated file icons for .prs files in the VS Code explorer.

  5. Import AI instruction files with @promptscript/importer

    main
    The @promptscript/importer package allows you to convert existing AI instruction files (like CLAUDE.md, .cursorrules, or copilot-instructions.md) into PromptScript (.prs) format. It uses heuristic section classification to map markdown content to PromptScript blocks like @identity, @restrictions, and @knowledge, providing a confidence score for each mapping.

  6. Available PromptScript ecosystem tools

    main

    Beyond the CLI, you can use the following tools to work with PromptScript:

    • Online Playground: An interactive browser-based editor to write source and inspect generated output (getpromptscript.dev/playground/).
    • VS Code Extension: Provides syntax highlighting, bracket matching, folding, and file icons.
    • Docker Image: A portable version of the CLI suitable for local development or CI environments.
    • prs serve: A command to bridge the online playground with your local filesystem.

  8. How composition and order work in PromptScript

    main

    PromptScript resolves values by applying layers of modifications in a specific sequence. When multiple files or blocks modify the same data structure, the final value is determined by the order of operations: inheritance, imports, local definitions, overrides, and extensions.

    Resolution Order

    1. @inherit <path>: Pulls in base values from another file.
    2. @use <path>: Imports values. In same-shape conflicts (e.g., two files defining the same key), the imported value typically wins.
    3. Local Blocks: Local definitions (e.g., a @standards block defined directly in the file) add new keys or values to the existing set.
    4. @override <path.key>: Replaces a specific existing value with a new one. Note: The target must already exist before the @override is called.
    5. @extend <path>: Appends new values to an existing collection (like an array) rather than replacing the whole structure.

    Example Scenario

    If base.prs defines coverage: 80 and quality.prs defines coverage: 90, using @use ./quality in a project file will result in coverage: 90 due to the import winning the conflict.

    # project.prs
@meta { id: "project" syntax: "1.6.0" }
@inherit ./base
@use ./quality
@standards {
  local: ["Run smoke tests"]
}
@override standards.coverage { 95 }
@extend standards {
  testing: ["Require integration tests"]
}

  9. How directory imports work

    main

    When you use @use on a path that points to a directory, the PromptScript resolver scans the directory for skills.

    Scanning Rules

    1. It looks for SKILL.md in immediate subdirectories.
    2. It looks for <dirname>.md in immediate subdirectories (where the filename matches the directory name).
    3. It ignores other .md files like README.md or CHANGELOG.md.
    4. It scans up to a depth of 3 subdirectories.

    Example

    If you import github.com/repo/skills/gitnexus, the resolver might find:

    • gitnexus/exploring/SKILL.md $\rightarrow$ skill exploring
    • gitnexus/debugging/SKILL.md $\rightarrow$ skill debugging

    You can use aliases to access these sub-skills: @use github.com/repo/skills/gitnexus as gn allows you to call gn.exploring.

  10. How @inherit differs from @use

    main

    PromptScript provides two primary ways to bring in external configuration: @inherit and @use. They serve different semantic purposes:

    Feature@inherit@use
    QuantitySingle parent onlyMultiple allowed
    Semantics"IS-A" (this project IS a TypeScript library)"HAS-A" (this project HAS security standards)
    PurposeDefine fundamental project typeAdd optional capabilities
    Merge precedenceChild overrides parentLater @use overrides earlier
    @extend supportAlways availableOnly with alias

    When to use @inherit

    Use @inherit for defining the fundamental type of your project (e.g., library, backend, frontend) or building organizational hierarchies (base → team → project). It is intended for a single, clear inheritance chain.

    # This project IS a TypeScript library
@inherit @stacks/typescript-lib

    When to use @use

    Use @use for adding optional capabilities, mixing in reusable fragments, or when you need to import multiple distinct sources.

    # This project HAS these capabilities
@use @core/security
@use @core/quality
@use @fragments/testing

  11. Manage skill dependencies and shared resources

    main

    Skills can be organized and interconnected using the following mechanisms:

    • Shared Resources: Place cross-skill resources in the .promptscript/shared/ directory and reference them using the @shared/ prefix.
    • Skill Dependencies: Declare dependencies using the requires field in the skill definition. The compiler performs PS016 validation to detect circular dependencies.
    • Skill Overlays (@extend): Use the references property in SKILL.md frontmatter to implement skill-aware @extend semantics. This allows for replacing, appending, or shallow-merging properties.

  12. Automatic discovery of resource files in directory imports

    main

    When a markdown import points to a directory (e.g., @use ./skills/my-tool), PromptScript treats it as a skill bundle. It automatically loads SKILL.md and discovers all sibling files in that directory tree (such as .csv data files, .py scripts, or .json templates).

    All discovered files are copied to every compilation target alongside the skill, mirroring the behavior of locally installed skills in .promptscript/skills/.

    my-tool/
├── SKILL.md          # main skill definition
├── data/
│   └── repos.csv     # discovered automatically
└── scripts/
    └── query.py      # discovered automatically