@promptscript/cli

Write your AI rules once. Every agent follows them.

One source for Claude Code, GitHub Copilot, Cursor, and 47 more tools. Define instructions, skills, agents, MCP servers, hooks, and policies once, inherit them like code, and compile native files for every tool.

Get started · Documentation · Playground · GitHub

What is PromptScript?

PromptScript is an open-source compiler for AI coding agent rules. .prs sources define instructions, project standards, restrictions, skills, agents, MCP servers, hooks, and workflows, while promptscript.yaml configures targets and the policies for skill extensions and prompts. PromptScript compiles them into the native files each AI tool already reads, including CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, and output for 47 more targets.

Every AI coding tool uses its own file names, formats, and paths. Teams using several tools end up maintaining several copies of the same rules. Those copies drift, and a change made for one tool may never reach the others.

PromptScript fixes the source instead of patching each generated file:

.promptscript/project.prs
    -> resolve inheritance, imports, and policies
    -> validate language and capabilities
    -> compile deterministic native files

No runtime proxy and no hosted service. PromptScript runs on your machine and in CI, and each selected platform keeps consuming its own native configuration.

Why maintain native files by hand?

Even a few tools create copies that need the same manual updates. Errors stay hidden until an agent reads the broken file. Policy changes become separate edits across every repository and tool.

With PromptScript, you change one source, review the generated diff, and validate it in CI. Git records each change. Remote dependencies stay pinned in promptscript.lock, so builds remain reproducible. Adding or switching tools does not require rewriting the source. See the full comparison.

Install

Requires Node.js 22.22 or later.

npm install -g @promptscript/cli

Also available through pnpm or yarn:

pnpm add -g @promptscript/cli
yarn global add @promptscript/cli

Verify installation:

prs --version

Running under Deno

The CLI also runs on Deno 2.9 or later. Install it globally from npm:

deno install -g --allow-env --allow-sys --allow-read --allow-write --allow-net --allow-run npm:@promptscript/cli

It can also run straight from the installed package or be compiled into a standalone binary that needs no other runtime.

In any project that has @promptscript/cli in its dependencies, point Deno at the installed bin shim:

deno run --allow-env --allow-sys --allow-read --allow-write --allow-net --allow-run node_modules/@promptscript/cli/bin/prs.js init

An npm:@promptscript/cli specifier resolves the published registry release instead of the version installed in node_modules, so use the path above whenever the project's own dependency is what should run.

Compile a self-contained prs binary, for example for CI images or machines without Node:

deno compile --allow-env --allow-sys --allow-read --allow-write --allow-net --allow-run -o prs node_modules/@promptscript/cli/bin/prs.js
./prs --version

Add --target x86_64-unknown-linux-gnu (or aarch64-unknown-linux-gnu, x86_64-pc-windows-msvc) to cross-compile for another platform.

What the permissions are for:

| Flag | Used for | | ------------------------------- | ----------------------------------------------------- | | --allow-env, --allow-sys | runtime detection, configuration, telemetry | | --allow-read, --allow-write | project files, caches, vendored dependencies | | --allow-net | registries, update checks, telemetry delivery | | --allow-run | git subprocesses, pagers, clipboard, guarded cleanups |

Guarded managed-output cleanup re-executes the CLI through a hidden worker command: under deno run the worker is spawned with read and write access scoped to the output directory, and a compiled binary re-executes itself. Telemetry reports runtime: deno and is disabled with DO_NOT_TRACK=1. Node.js 22.22+ remains fully supported with unchanged behavior.

60-Second Quick Start

prs init
# Edit .promptscript/project.prs
prs validate --strict
prs compile

prs init detects the project stack and installed AI tools, then creates a clean promptscript.yaml and .promptscript/project.prs. Detected targets are preselected, while other targets remain explicit choices. For automation, use prs init --yes --targets claude factory. Pass --no-hooks to skip hook installation or --dry-run to preview all writes.

Generated output can include:

.github/copilot-instructions.md
.github/prompts/review.prompt.md
CLAUDE.md
.claude/agents/reviewer.md
.claude/skills/security-review/SKILL.md
.cursor/rules/project.mdc
.cursor/agents/reviewer.md
.opencode/agents/reviewer.md

Define the Platform

.promptscript/project.prs:

@meta {
  id: "checkout-service"
  syntax: "1.5.0"
}

@identity {
  """
  You are working on the checkout service.
  Preserve transaction integrity and auditability.
  """
}

@standards {
  @header "Engineering Standards"
  code: ["Use strict TypeScript", "Test every business rule"]
}

@shortcuts {
  "/review": {
    prompt: true
    description: "Review current changes"
    content: "Review correctness, security, tests, and operational impact."
  }
}

@skills {
  security-review: {
    description: "Review payment changes for security risks"
    allowedTools: ["Read", "Grep", "Bash"]
    content: "Inspect authentication, authorization, secrets, and payment data handling."
    inputs: {
      targetPath: {
        description: "Path to review"
        type: "string"
      }
    }
    outputs: {
      report: {
        description: "Review report"
        type: "string"
      }
      highestSeverity: {
        description: "Highest detected severity"
        type: "enum"
        options: [low, medium, high, critical]
      }
    }
  }
}

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

@agents {
  reviewer: {
    description: "Review changes before merge"
    tools: ["Read", "Grep", "Glob", "Bash"]
    skills: ["security-review"]
    mcpServers: ["issue-tracker"]
    content: "Review changed code, tests, and operational impact."
  }
}

@hooks {
  validate-changes: {
    event: "post-tool-use"
    matcher: "Edit|Write"
    command: ["npm", "run", "typecheck"]
  }
}

@workflows {
  release: {
    description: "Prepare a validated release"
    content: "Run quality gates, summarize changes, and prepare release metadata."
  }
}

promptscript.yaml:

id: checkout-service
syntax: '1.5.0'

input:
  entry: .promptscript/project.prs

targets:
  - github:
      version: multifile
  - claude:
      version: full
  - cursor:
      version: full
  - opencode:
      version: full
  - gemini:
      version: full

Run prs compile. Formatters map each supported capability to native target files and omit unsupported platform-specific features.

What PromptScript Manages

| Capability | Source | Result | | :---------------------- | :---------------------------------------------------------------- | :------------------------------------------------------------------------------- | | Instructions and policy | @identity, @context, @standards, @restrictions, @guards | Main instructions and scoped rules | | Portable skills | @skills | Native skill directories with references, assets, scripts, and contracts | | Specialist agents | @agents | Native Markdown, TOML, or droid files with models, tools, skills, and MCP access | | User commands | @shortcuts | Native prompts, commands, or documented shortcuts | | Tool integrations | @mcpServers | Platform-specific MCP configuration | | Capability bundles | @plugins | Native plugin manifests where supported | | Automation | @hooks, @workflows | Lifecycle hooks and repeatable workflow files | | Prompt definitions | @prompts | Typed inputs (syntax 1.6.0). bundle and prompt-text compile them | | Monorepo delivery | builds in promptscript.yaml | Scoped output for packages and applications |

Built-In Targets

PromptScript ships 50 coding agent targets and two prompt targets.

| Platform | Primary and rich output | | :------------- | :--------------------------------------------------------------- | | GitHub Copilot | .github/copilot-instructions.md, agents, skills, prompts | | Claude Code | CLAUDE.md, .claude/agents/, .claude/skills/<name>/SKILL.md | | Cursor | .cursor/rules/, .cursor/agents/, commands, MCP and hooks | | Factory AI | AGENTS.md, .factory/droids/, skills, MCP, hooks and plugins | | Codex | AGENTS.md, .codex/agents/*.toml, skills and config | | OpenCode | OPENCODE.md, agents, skills and commands | | Gemini CLI | GEMINI.md, commands and interoperable skills | | Antigravity | .agent/rules/, workflows and MCP configuration | | Grok | AGENTS.md, agents, skills, commands and integrations |

PromptScript also supports 11 AGENTS.md targets and 30 Markdown instruction targets, including Windsurf, Cline, Roo Code, Continue, Aider, Amazon Q, Warp, Zed, OpenHands, Qwen Code, Kimi, Mimo, Deep Agents, ForgeCode, and Hermes Agent.

See the complete target and capability matrix.

Prompts for applications

Two more targets are not coding agent targets. With syntax 1.6.0, bundle compiles the @prompts entries of a program to content-hashed JSON files under prompts/, and prompt-text writes a Markdown preview of each composed system message. Both are opt-in: name them in targets. They write nothing for a program without prompts. PromptScript does not escape, delimit or filter the values an application puts into a prompt, and it does not enforce output schemas. Read the application prompts guide before you ship a bundle. Four runnable application prompt examples show typed inputs, enum outputs, defaults and citations.

prs release stores bundles under their content hash in .promptscript/releases/ and promotes them through the environments you list in releases.environments, such as staging then prod. Every promotion is a Git change you review, and prs release status --base refs/remotes/origin/main checks the label changes of a pull request with the rules of the base branch. See the releases guide.

prs eval run runs a prompt over a dataset and checks every answer with assertions and, if you want, an LLM judge. The default cache mode replays recorded answers, so a pull request check needs no key and no network. prs eval compare --fail-on-regression fails when a later report is worse than an earlier one. Without the flag it only prints the regression. See the evals guide.

prs approve records that a person approved one exact bundle hash in a role from governance.roles, as a JSON file under .promptscript/approvals/. The record is a claim; the review of the pull request that adds it is what binds it. See approvals. Promote, rollback and status --base run the prompt policies as release gates: a required-approvals policy refuses a version until a committed record approves that hash for the environment. A record binds only with code owner review of its role directory. See release gates.

prs governance codeowners writes the governance section of promptscript.yaml into CODEOWNERS: prompt files go to their owners, approval directories to their role teams, and the config and release files to the admins. See CODEOWNERS from Governance.

prs audit log reads who changed, approved, promoted, rolled back or split a prompt from the Git history, as text, JSON or CEF for a SIEM. See Audit log.

Applications read the released bundles with @promptscript/runtime, which checks the content hash on every load. It is not published to npm yet. See Read a release in your application.

Skills from Local Files, Registries, or Git

@use ./skills/security-review.md
@use @company/skills/release@^2.0.0
@use github.com/acme/agent-skills/[email protected]

Skill directories can bundle SKILL.md, references, scripts, assets, and licenses while preserving their directory structure:

security-review/
├── SKILL.md
├── references/threat-model.md
├── scripts/scan.sh
└── assets/report-template.md

Manage remote skills from the CLI:

prs skills add github.com/acme/agent-skills/[email protected]
prs skills list
prs skills update
prs skills remove security-review

Remote imports are recorded in promptscript.lock with commit and SHA-256 integrity data.

Composition and Governance

@inherit @company/platform
@use @team/backend

@override standards.testing {
  ["Use Vitest", "Require 95% coverage"]
}

@extend standards {
  testing: ["Run integration tests in CI"]
}

• Inherit organization, team, and project layers.
• Compose local files, Markdown skills, aliases, and direct Git imports.
• Extend selected paths with deterministic merges, negation, and sealed properties.
• Replace complete existing blocks or nested values with @override.
• Customize generated section titles with @header.
• Pass typed parameters to reusable templates.
• Enforce layer boundaries, protected properties, and registry allowlists with policies.
• Inspect skill provenance with prs inspect <skill>.
• Build reproducibly with version pins, lockfile integrity, and vendor mode.

Configuration Layers

Settings merge in this order, highest first:

1. CLI flags and environment variables
2. Project promptscript.yaml
3. User config at ~/.promptscript/config.yaml
4. System config, provisioned by IT: /etc/promptscript/config.yaml on macOS and Linux, %ProgramData%\promptscript\config.yaml on Windows

The user config wins over the system config. Between those two, registries, defaults, and registry merge one level deep, and a user registry.url without git drops the system git backend. Only registry, registries, and telemetry from the user and system layers reach a project's effective config. defaults (team, targets) are read by prs init only. telemetry: false at any layer is a hard opt-out: a higher-priority telemetry: true cannot turn it back on.

Extending a Config File

Share settings across projects with extends:

# shared/base.config.yaml
targets:
  - claude
registries:
  '@company': github.com/acme/promptscript-base

# app/promptscript.yaml
id: app
extends: ../shared/base.config.yaml
targets:
  - github

The path is relative to the declaring file and chains are allowed, but a cycle is an error. Objects merge deeply and arrays are replaced, so app compiles only github. The exception is policies: base policies are kept and the extending file's policies are appended, and a policy that reuses a base policy name is an error. governance.admins, each owner list under governance.roles and governance.codeowners.protect are joined too, so an extending file can add entries but not remove them. A different registry backend in the extending file drops the base one.

See the configuration reference and the enterprise guide for details.

Monorepo Build Profiles

Create scoped builds in promptscript.yaml:

builds:
  api:
    entry: .promptscript/packages/api.prs
    output: packages/api
    targets:
      - factory
  codex-api:
    entry: .promptscript/packages/api.prs
    output: packages/api
    targets:
      - codex:
          output: AGENTS.override.md
          agentsFile: AGENTS.override.md
  web:
    entry: .promptscript/packages/web.prs
    output: packages/web
    targets:
      - cursor:
          version: full

prs build api
prs build codex-api
prs compile --build web
prs compile --all-builds

Migrate Existing Instructions

prs import CLAUDE.md
prs import .github/copilot-instructions.md
prs migrate --static --dry-run
prs migrate --static
prs migrate --llm

Static migration deterministically imports detected instruction files. AI-assisted migration generates a migration prompt and installs the PromptScript skill. Existing source instructions remain untouched, and existing PromptScript configuration is preserved byte-for-byte. Static output is isolated under .promptscript/migrated/; no detected candidates means no writes.

Projects upgrading from PromptScript 1.15 should preview syntax changes with prs upgrade --dry-run, then run prs validate --strict. Factory targets also preview legacy hook migration through prs compile --dry-run; use --no-migrate-factory-hooks only when migration must remain manual.

Preview before writing:

prs compile --dry-run
prs diff --all
prs diff --format json

prs diff --format json emits a versioned report with target, path, source provenance, ownership, change kind, deterministic content hashes, warnings, and unsupported capability entries. Content is omitted by default; add --include-content when automation needs canonical output text. Reports with changes exit 0; compilation and report errors emit success: false and exit 1. See the diff schema. The JSON output of prs diff, prs release, prs approve, prs audit log, prs eval run, prs eval compare and prs validate is stable; the rules are on the JSON Output page. Diff uses the complete configured target when --target selects one, never writes generated files or registry cache metadata, and requires Git registries to already exist in vendor mode or a valid local cache.

Built-In Security Scanner

prs validate scans the instructions and skills in your entry file and everything it imports for prompt injection, before anything is written. Encoded payloads are decoded first, so an attack hidden in hex or Base64 does not get through:

$ prs validate --strict
✖ Validation failed
✗ Blocked pattern detected:
  ignore\s+(all\s+)?previous\s+instructions
  at project.prs:8:1
✗ PS012: Malicious content detected
  in raw hex (spaced): Prompt injection
  Decoded: "IGNORE SAFETY RULES"
  at project.prs:16:14
✗ PS010: URL shortener detected:
  http://bit.ly/deploy-help
  at project.prs:16:14

| Rule | Catches | | :---- | :----------------------------------------------------------------------------- | | PS005 | Injection phrases like "ignore previous instructions" | | PS011 | Fake authority overrides and "bypass all safety checks" instructions | | PS012 | Payloads hidden in Base64, hex, URL encoding, HTML entities, ROT13, and 4 more | | PS013 | Path traversal in @use declarations | | PS014 | Right-to-left overrides, zero-width characters, and homoglyphs | | PS010 | Plain HTTP links, link shorteners, and credentials in URLs |

--strict turns warnings into errors. Run prs validate --strict in CI so a poisoned skill fails the build, not the agent. See the security guide.

prs validate --format json prints one versioned report, see JSON Output.

CLI Commands

| Command | Purpose | | :-------------------------------------------------- | :-------------------------------------------------------- | | prs init | Detect project context and initialize PromptScript | | prs compile | Compile all configured targets | | prs compile --watch | Recompile when source changes | | prs build <name> | Compile one named build profile | | prs compile --all-builds | Compile every named profile | | prs validate --strict | Validate source, references, policies, and capabilities | | prs validate --fix | Upgrade outdated syntax declarations when possible | | prs fmt [paths...] | Rewrite .prs files in canonical form (--check for CI) | | prs check | Check config, entries, lockfile, registry, and imports | | prs diff --all | Preview compiled output differences | | prs inspect <skill> | Show skill layers and property provenance | | prs explain <path> | Show source and composition provenance | | prs hooks install [tool] | Integrate supported AI tools and protect generated files | | prs hook <action> | Low-level handler called by AI tool hooks | | prs skills <add\|remove\|list\|update> | Manage remote and local skills | | prs registry <init\|validate\|publish\|list\|add> | Manage registries and aliases | | prs pull | Pull updates from the registry | | prs release <build\|promote\|rollback\|status> | Release prompt bundles through environments | | prs eval <run\|compare\|import> | Run eval suites, compare reports, import samples | | prs approve <id>@<hash> / prs approve --list | Record or list approvals of one prompt version | | prs governance codeowners | Write CODEOWNERS lines from the governance config | | prs audit log | List approvals, promotions, experiments and changes | | prs lock / prs update | Pin or refresh remote dependencies | | prs vendor sync / prs vendor check | Prepare and verify offline dependencies | | prs resolve <import> | Explain import resolution | | prs import <file> / prs migrate | Adopt existing instruction files | | prs upgrade | Upgrade .prs syntax versions | | prs update-check | Check npm for a newer CLI version | | prs telemetry <status\|enable\|disable> | Inspect or change anonymous telemetry settings | | prs serve | Connect local files to the online playground |

prs explain emits project-relative source paths by default. Pass --absolute-paths to opt in to host filesystem paths. JSON output contains version, path, entries, and diagnostics. The command exits nonzero for missing paths, resolution failures, or fatal diagnostics; warning-only diagnostics keep exit status 0.

prs fmt rewrites .prs files atomically and keeps comments and declaration order. A blank line between entries is kept, several become one, and blank lines at the start or end of a block, object, array or file are dropped. Arrays that do not fit in 100 characters print one element per line. Blank lines inside @meta and inside @use and @inherit parameter lists are dropped. Comments inside @meta move before its closing brace, and comments in @use and @inherit parameter lists move to their own line. Directory walks skip node_modules, vendor and .cache. Files without the .prs extension and symbolic links (to files or directories) are skipped, and read-only files are reported and not written. It exits 1 for a missing path, a named path that is not a regular file, a directory or file that cannot be read, a file that cannot be parsed or written, or (with --check) files that would change. --quiet hides the --check file list.

See the complete CLI reference for every option.

Hooks and Generated-File Protection

PromptScript has two separate automation layers:

• @hooks compiles portable lifecycle events to native target hook configuration.
• prs hooks install integrates supported AI tools, recompiles after their .prs edit events, and redirects direct edits of generated files back to PromptScript source.

Use prs compile --watch for changes made in a general-purpose editor.

Targets with native skill support can receive the bundled PromptScript language skill, allowing compatible agents to work with .prs source. Disable it with includePromptScriptSkill: false.

Privacy and Telemetry

PromptScript is a compiler, not a service. Compiling needs no hosted backend, and the output is plain files in your repository. Anonymous usage telemetry never includes source, prompts, or file paths. Turn it off with prs telemetry disable or DO_NOT_TRACK=1. See what is collected.

Docker

docker run --rm -v "$(pwd):/workspace" ghcr.io/mrwogu/promptscript:latest compile

Editor Support

Install the PromptScript VS Code extension for syntax highlighting, bracket matching, code folding, and file icons.

Documentation

• Getting Started
• Agent Platform
• Language Reference
• Configuration Reference
• JSON Output
• Target Matrix
• Security Guide
• Model Catalog
• Glossary
• FAQ
• Enterprise Guide
• Playground

License

MIT