@promptscript/cli

Agent platform configuration as code

Define instructions, skills, agents, MCP servers, hooks, workflows, and policies once. Compile native configuration for 49 AI coding platforms.

Get started · Documentation · Playground · GitHub

AI coding platforms use different files for instructions, skills, agents, commands, MCP integrations, hooks, and settings. PromptScript replaces hand-maintained copies with one validated, composable, Git-native source and target-specific compilers.

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

No runtime proxy. Each selected platform keeps consuming its own native configuration.

Install

Requires Node.js 20 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

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
.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 | | Monorepo delivery | builds in promptscript.yaml | Scoped output for packages and applications |

49 Built-In 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 29 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.

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.

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

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 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 skills <add\|remove\|list\|update> | Manage remote Markdown skills | | prs registry <init\|validate\|publish\|list\|add> | Manage registries and aliases | | 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 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.

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.

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
• Target Matrix
• Upgrade 1.15 to 1.16
• Enterprise Guide
• Playground

License

MIT