Skip to content

FAQ & Troubleshooting

What is PromptScript?

PromptScript is an open-source compiler for AI coding agent configuration. You write instructions, skills, agents, MCP servers, hooks, and plugins in .prs files, and it generates the native files for 50 tools, such as CLAUDE.md, .github/copilot-instructions.md, and Cursor rules. New to the terms? See the Glossary.

How many AI tools are supported?

PromptScript currently compiles to 50 AI coding agent targets, plus two targets for application prompts. See the full list in Target Platforms or the formatter matrix.

How is it different from a shared AGENTS.md file?

AGENTS.md is one file that some tools read. PromptScript is the source behind it. It adds inheritance across repositories, parameters, skills, agents, MCP servers, validation, and a security scan, and it writes AGENTS.md together with the formats of every other tool.

Can I start from the instruction files I already have?

Yes. prs import converts an existing CLAUDE.md, Copilot, Cursor, or AGENTS.md file, prs migrate imports a whole project, and the built-in promptscript skill lets your AI agent do the migration for you. See Import Existing Instructions and the Migration Guide.

Does PromptScript send my prompts anywhere?

No. Compilation runs on your machine or in your CI. Anonymous usage telemetry is on by default and never includes source, prompts, compiled output, file paths, or project names. Turn it off with prs telemetry disable or DO_NOT_TRACK=1. See Telemetry.

Is PromptScript free?

Yes. PromptScript is open source under the MIT license. The CLI is published on npm as @promptscript/cli.

How do I install PromptScript?

Terminal window
npm install -g @promptscript/cli

Or use npx without installing:

Terminal window
npx @promptscript/cli compile

Or use Docker:

Terminal window
docker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript compile

See the Getting Started guide for details.

How does inheritance work?

PromptScript supports hierarchical inheritance with @inherit and @use directives:

  • @inherit - Extend a base configuration (single inheritance)
  • @use - Import and merge additional rule sets (multiple imports)

Sources can be local files (./base) or registry packages (@company/standards). See the Inheritance guide.

How do I set up a private registry?

A registry is just a Git repository with .prs files. Configure it in your project:

Terminal window
prs registry add @company https://github.com/your-org/promptscript-registry.git

See the Registry guide for full setup instructions.

How do I integrate with CI/CD?

Add PromptScript to your pipeline:

Terminal window
prs validate --strict # Fail on any validation warnings
prs compile --strict # Compile configured targets and fail on output conflicts

See the CI/CD guide.

Common Errors

PS2001: File not found

The @inherit or @use target cannot be resolved. Check:

  • The file path is correct relative to the current file
  • The registry is configured if using @scope/package syntax
  • Run prs registry list to verify configured registries

PS2000: Expecting token ...

The parser found invalid syntax, such as a missing closing brace or a misplaced token, for example Expecting token of type --> RBrace <-- but found --> '?' <--. The resolver reports every parse error with the code PS2000, which you see in prs validate --format json. The parser code, for example PS1000, stays in the optional cause field of that error. Check the reported location and compare it with the Language Reference. A parse error that has no position reports line and column -1.

PS001: @meta block is required

The file has no @meta block. Add one with at least an id and a syntax version, as in the Language Reference.

Compiled output doesn’t match expected format

Check your CLI version first, then update through the same method you used to install:

Terminal window
prs --version
Terminal window
npm update -g @promptscript/cli # npm global install
npx @promptscript/cli@latest compile # npx, no install step
docker pull ghcr.io/mrwogu/promptscript:latest # Docker

Formatter behavior can change between versions, so teams that pin the CLI version in CI should upgrade the pin deliberately.

How do I contribute?

See CONTRIBUTING.md for guidelines. Ways to help:

  1. Add support for new AI tools (formatters)
  2. Report bugs and suggest features
  3. Improve documentation
  4. Share PromptScript with your team