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?
npm install -g @promptscript/cliOr use npx without installing:
npx @promptscript/cli compileOr use Docker:
docker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript compileSee 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:
prs registry add @company https://github.com/your-org/promptscript-registry.gitSee the Registry guide for full setup instructions.
How do I integrate with CI/CD?
Add PromptScript to your pipeline:
prs validate --strict # Fail on any validation warningsprs compile --strict # Compile configured targets and fail on output conflictsSee 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/packagesyntax - Run
prs registry listto 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:
prs --versionnpm update -g @promptscript/cli # npm global installnpx @promptscript/cli@latest compile # npx, no install stepdocker pull ghcr.io/mrwogu/promptscript:latest # DockerFormatter 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:
- Add support for new AI tools (formatters)
- Report bugs and suggest features
- Improve documentation
- Share PromptScript with your team