# 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](https://getpromptscript.dev/glossary/index.md).

## How many AI tools are supported?

PromptScript currently compiles to **50 AI coding agent targets**, plus two targets for
[application prompts](https://getpromptscript.dev/guides/application-prompts/index.md). See the full list in
[Target Platforms](https://getpromptscript.dev/features/target-platforms/index.md) or the
[formatter matrix](https://getpromptscript.dev/reference/formatters/index.md).

## 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](https://getpromptscript.dev/guides/import/index.md) and the
[Migration Guide](https://getpromptscript.dev/guides/migration/index.md).

## 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](https://getpromptscript.dev/reference/telemetry/index.md).

## 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?

```bash
npm install -g @promptscript/cli
```

Or use npx without installing:

```bash
npx @promptscript/cli compile
```

Or use Docker:

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

See the [Getting Started guide](https://getpromptscript.dev/getting-started/index.md) 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](https://getpromptscript.dev/guides/inheritance/index.md).

## How do I set up a private registry?

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

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

See the [Registry guide](https://getpromptscript.dev/guides/registry/index.md) for full setup instructions.

## How do I integrate with CI/CD?

Add PromptScript to your pipeline:

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

See the [CI/CD guide](https://getpromptscript.dev/guides/ci/index.md).

## 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](https://getpromptscript.dev/reference/language/index.md). 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](https://getpromptscript.dev/reference/language/index.md).

### Compiled output doesn't match expected format

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

```bash
prs --version
```

```bash
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](https://github.com/mrwogu/promptscript/blob/main/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