promptscript

PromptScript

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

AI coding tools no longer consume one instruction file. They discover skills, specialist agents, commands, MCP integrations, hooks, workflows, and platform-specific settings from different paths and schemas. Managing these files by hand creates drift between tools, repositories, and teams.

PromptScript turns that surface area into one validated, composable, Git-native source:

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

No runtime proxy. No lowest-common-denominator output. Each formatter emits the richest native representation its platform supports.

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