promptscript

PromptScript

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.

[CI] [codecov] [npm version] [Node.js 20+] [Deno 2.9+] [Docker] [License: MIT] [VS Code]

Get started · Try the playground · Explore all features · View target matrix

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. The compiler turns them into the native files each AI tool already knows: CLAUDE.md for Claude Code, .github/copilot-instructions.md for GitHub Copilot, .cursor/rules for Cursor, and 47 more targets.

Why does this matter? Every AI coding tool reads its own instruction files, in its own format, from its own paths. A team using Claude Code, Copilot, and Cursor keeps three copies of the same rules. They drift. A standard changes in one file but not the others, and nobody notices until an agent breaks something.

PromptScript fixes the source, not the symptoms:

PromptScript source
    -> resolve inheritance, imports, and policies
    -> validate language and capabilities
    -> compile deterministic target-native files

One source of truth, Git-native review, validation in CI, deterministic output. No runtime proxy between developers and their tools. Each formatter emits the richest native representation its platform supports - if a target cannot express something, it is omitted, not approximated.

It fits one developer with two tools, and it fits an organization where a platform team ships standards to hundreds of repositories through inheritance and a Git registry.

Why maintain the files by hand?

Each tool wants its own file, schema, and path. Even a few tools means copies that drift. A policy change becomes manual edits everywhere, and errors sit undetected until an agent hits them at runtime.

With PromptScript you change the source once, review the generated diff in the pull request, and let CI validate it. Git history records what changed and why. Remote dependencies are pinned in a lockfile, so builds are reproducible. Switching tools, or adding a new one, never rewrites the source. See the full comparison.

Contents

• What is PromptScript?
• Why maintain the files by hand?
• Quick Start
• Define a Complete Agent Platform
• One Language, Complete Platform
• Compose Instead of Copying
• Portable Skills, Native Agents
• Name a Model Once
• Built-In Security Scanner
• Built-In Targets
• Prompts for Applications
• Built for Repositories and Organizations
• Adopt Without a Rewrite
• Tooling
• Documentation
• Contributing

Quick Start

npm install -g @promptscript/cli

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. Hooks are installed by default. Use --no-hooks to skip hook installation or --dry-run to preview all writes.

Prefer no local installation?

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

Or open the playground and compile in the browser.

Define a Complete Agent 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."
  }
}

@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: ["pnpm", "run", "typecheck"]
  }
}

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

@plugins {
  engineering: {
    description: "Shared engineering capabilities"
    version: "1.0.0"
    skills: ["security-review"]
    hooks: ["validate-changes"]
    mcpServers: ["issue-tracker"]
  }
}

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

prs compile maps supported capabilities to files each platform already understands:

.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

One Language, Complete Platform

Target support stays explicit. Unsupported platform-specific capabilities are omitted rather than approximated with incompatible configuration.

Compose Instead of Copying

Build organization, team, and project layers with deterministic merge rules:

@inherit @company/platform
@use @team/backend
@use github.com/acme/agent-skills/database-review@1.3.0

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

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

• @inherit creates a single-parent base chain.
• @use composes multiple local, registry, Git, or Markdown resources.
• @extend merges selected paths and supports skill-specific overlays.
• @override atomically replaces one existing block or nested value.
• @header customizes generated section titles without changing native schemas.
• Typed parameters turn shared stacks into reusable templates.
• Sealed properties, reference negation, and overlay drift warnings keep extension layers safe.
• prs inspect <skill> shows property and layer provenance.
• prs explain <path> shows source locations and composition history for any resolved path. Text and JSON paths are project-relative by default; use --absolute-paths to opt in to absolute paths. JSON includes version, path, entries, and diagnostics. The command exits nonzero for fatal resolution diagnostics or missing paths, but warning-only diagnostics succeed.

Remote imports are pinned in promptscript.lock with commit and integrity data. Vendor mode mirrors resolved dependencies into .promptscript/vendor/ for offline and air-gapped builds.

Portable Skills, Native Agents

PromptScript accepts inline skills, standalone Markdown skills, and complete skill directories:

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

Import versioned skills without copy-paste:

@use github.com/acme/agent-skills/security-review@^2.0.0

prs skills add github.com/acme/agent-skills/security-review@2.1.0
prs skills update

PromptScript validates Agent Skills metadata, resolves dependencies and resources, then emits the native skill path for each selected platform. Agents can reference those skills and receive target-native model, reasoning, sandbox, tool, permission, and MCP settings.

Name a Model Once

Each tool spells model names differently. Write an alias like opus or a full model id, and PromptScript writes the name each target expects:

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

@agents {
  reviewer: {
    description: "Review pull requests"
    model: "opus"
    content: "Review changed code, tests, and operational impact."
  }
}

When a target cannot run the model, the compiler warns instead of writing a value the tool would reject. Claude Code picks the release for an alias itself. Other targets get the current release from the catalog and move on when you upgrade PromptScript and compile again. See the model catalog and aliases.

Built-In Security Scanner

Instruction files and imported skills are a prompt injection surface. prs validate scans the instructions and skills in your entry file and everything it imports, before anything is written. Encoded payloads are decoded first, so hiding an attack in hex or Base64 does not get it 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

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

Built-In Targets

PromptScript ships 50 coding agent targets and two prompt targets:

• 9 rich native formatters - Claude Code, GitHub Copilot, Cursor, Factory AI, Codex, Gemini CLI, OpenCode, Antigravity, and Grok
• 11 AGENTS.md targets - Aider, Amazon Q, Warp, Zed, Jules, Devin, Kimi, Mimo, Deep Agents, ForgeCode, and Hermes Agent
• 30 Markdown instruction targets - Windsurf, Cline, Roo Code, Continue, Augment, Goose, Kilo Code, OpenHands, Qwen Code, and more

See exact output paths and feature support in the formatter 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. A prompt can compose blocks such as @identity and @restrictions into its system message. 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 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 or rolled back a prompt from the Git history, as text, JSON or CEF for a SIEM. See Audit log.

The @promptscript/runtime package in this repository loads, verifies and renders the released bundles in an application, with no dependencies. It is not published to npm yet and its API can still change. See the releases guide.

Built for Repositories and Organizations

• Runs locally - PromptScript is a compiler, not a service. No hosted backend and no proxy between your team and its tools, the output is plain files you review and commit.
• Your prompts stay yours - 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.
• Git-native governance - review source and deterministic generated diffs in pull requests.
• Private registries - share versioned standards through local, HTTP, or Git registries with SSH and token-based authentication.
• Policy engine - enforce layer boundaries, property protection, and registry allowlists after resolution.
• Layered configuration - IT provisions a system config, developers keep a user config, and a project promptscript.yaml can extends a shared base file. Base policies are kept. See user configuration.
• Governed prompt releases - prs release promote and prs release rollback move application prompt labels through environments. prs approve records approvals that the release gates check, and prs governance codeowners writes CODEOWNERS lines that route prompt files, approvals and release labels to the right teams. Turn on required code-owner review in branch protection. See enterprise setup.
• Reproducible builds - lockfile hashes, version pins, vendor mode, and strict validation.
• Safe automation - lifecycle hook commands use arrays, while generated-file protection keeps agents pointed at .prs source.
• Scoped monorepo builds - compile one package with prs build <name>, inspect it with prs diff --build <name>, or compile every profile with prs compile --all-builds.
• CI-ready output - use prs validate --strict --format json, prs compile --dry-run, prs diff --format json, and prs fmt --check for deterministic machine-readable changes and formatting checks without generated-file writes.

Adopt Without a Rewrite

prs import CLAUDE.md
prs migrate --static --dry-run
prs migrate --static
prs migrate --llm

Import existing Claude Code, GitHub Copilot, Cursor, AGENTS.md, and other instruction files. Review the generated .prs source, preview output with prs compile --dry-run, then migrate targets at your own pace. Migration preserves existing PromptScript configuration and source instructions; if no candidates are detected, it changes nothing.

Targets with native skill support can also receive the bundled PromptScript language skill. This lets compatible agents read and maintain .prs files from plain-language requests. Disable it with includePromptScriptSkill: false.

Tooling

• Online playground - edit source and inspect generated output in the browser
• VS Code extension - syntax highlighting, bracket matching, folding, and file icons
• Docker image - portable CLI for local use and CI
• prs serve - connect the online playground to local files
• prs compile --watch - recompile after editor changes
• prs hooks install - integrate supported AI tools and protect generated files

Documentation

Contributing

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and open issues.

PromptScript is available under the MIT License.