Agent platform configuration as code
Define instructions, skills, agents, MCP servers, hooks, workflows, and policies once. Compile native configuration for 50 AI coding platforms.
Get started · Try the playground · Explore all features · View target matrix
PromptScript is an open-source language and compiler for AI agent configuration. .prs sources
define instructions, project standards, restrictions, skills, agents, MCP servers, hooks, and
workflows, while promptscript.yaml configures targets and extension-compliance policies. 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.
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.
- 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
- 50 Built-In Targets
- Built for Repositories and Organizations
- Adopt Without a Rewrite
- Tooling
- Documentation
- Contributing
npm install -g @promptscript/cli
prs init
# Edit .promptscript/project.prs
prs validate --strict
prs compileprs 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 --strictOr open the playground and compile in the browser.
.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: fullprs 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
| Capability | PromptScript source | Native result |
|---|---|---|
| Instructions and policy | @identity, @context, @standards, @restrictions, @guards |
Main instructions and scoped rules |
| Portable skills | @skills |
SKILL.md directories with references, assets, scripts, and contracts |
| Specialist agents | @agents |
Native Markdown, TOML, or droid definitions with models, tools, skills, and MCP access |
| User commands | @shortcuts |
Native prompts, slash commands, or documented shortcuts |
| Tool integrations | @mcpServers |
Platform-specific JSON or TOML MCP configuration |
| Capability bundles | @plugins |
Native plugin manifests where supported |
| Automation | @hooks, @workflows |
Lifecycle hook configuration and workflow files |
| Monorepo delivery | builds in promptscript.yaml |
Scoped output for packages, applications, and plugins |
Target support stays explicit. Unsupported platform-specific capabilities are omitted rather than approximated with incompatible configuration.
Build organization, team, and project layers with deterministic merge rules:
@inherit @company/platform
@use @team/backend
@use github.com/acme/agent-skills/[email protected]
@override standards.testing {
["Use Vitest", "Require 95% coverage"]
}
@extend standards {
testing: ["Run integration tests in CI"]
}
@inheritcreates a single-parent base chain.@usecomposes multiple local, registry, Git, or Markdown resources.@extendmerges selected paths and supports skill-specific overlays.@overrideatomically replaces one existing block or nested value.@headercustomizes 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-pathsto opt in to absolute paths. JSON includesversion,path,entries, anddiagnostics. 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.
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/[email protected]
prs skills updatePromptScript 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.
PromptScript ships 50 output 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.
- 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.
- 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
.prssource. - Scoped monorepo builds - compile one package with
prs build <name>, inspect it withprs diff --build <name>, or compile every profile withprs compile --all-builds. - CI-ready output - use
prs validate --strict --format json,prs compile --dry-run, andprs diff --format jsonfor deterministic machine-readable changes without generated-file writes.
prs import CLAUDE.md
prs migrate --static --dry-run
prs migrate --static
prs migrate --llmImport 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.
- 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 filesprs compile --watch- recompile after editor changesprs hooks install- integrate supported AI tools and protect generated files
| Resource | Description |
|---|---|
| Getting Started | First project from initialization to native output |
| Agent Platform | Skills, agents, MCP, plugins, hooks, workflows, and targets |
| Language Reference | Complete PromptScript syntax |
| CLI Reference | Commands and options |
| Configuration Reference | Targets, registries, builds, policies, and formatting |
| Anonymous Usage Telemetry | Collected fields, delivery, and opt-out controls |
| Upgrade 1.15 to 1.16 | Syntax, block shape, and hook migration guide |
| Enterprise Guide | Organization-wide adoption and governance |
See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and open issues.
PromptScript is available under the MIT License.