mrwogu/promptscript

---

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/[email protected]

@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 shows property and layer provenance.
• prs explain 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/[email protected]
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.

49 Built-In Targets

PromptScript ships 49 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
• 29 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.

Built for Repositories and Organizations

• 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 .prs source.
• Scoped monorepo builds - compile one package with prs build , inspect it with prs diff --build , or compile every profile with prs compile --all-builds.
• CI-ready output - use prs validate --strict --format json, prs compile --dry-run, and prs diff --format json for deterministic machine-readable changes 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.