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.

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: