Configuration¶

Complete reference for promptscript.yaml.

File Location¶

The CLI looks for configuration in this order:

--config command line option
promptscript.yaml in current directory
promptscript.config.yml in current directory
.promptscriptrc.yaml in current directory

Schema Version¶

The configuration file requires a version field at the root level:

version: '1'

project:
  id: 'my-project'
# ...

This version refers to the configuration schema version, not the PromptScript language version. It allows the CLI to handle different configuration formats as the tooling evolves.

version vs syntax

Don't confuse version in promptscript.yaml with syntax in .prs files:

| File | Field | Purpose |
|------|-------|---------|
| `promptscript.yaml` | `version: '1'` | Configuration schema version |
| `project.prs` | `syntax: "1.0.0"` | PromptScript language syntax version |

The `syntax` field in `.prs` files uses full semver and indicates which version of the PromptScript language grammar the file uses. See [Language Reference](language.md#meta-block-required) for details.

Full Configuration¶

# Schema version (required)
version: '1'

# ===================
# Input Configuration
# ===================
input:
  # Entry point file (required)
  entry: .promptscript/project.prs

  # Additional files to include
  include:
    - '.promptscript/**/*.prs'

  # Files to exclude
  exclude:
    - '**/node_modules/**'
    - '**/*.test.prs'

# ======================
# Registry Configuration
# ======================
registry:
  # Local registry path
  path: ./registry

  # Or remote HTTP registry URL
  # url: https://registry.example.com/promptscript

  # Or Git repository (recommended for teams)
  # git:
  #   url: https://github.com/org/promptscript-registry.git
  #   ref: main                    # branch, tag, or commit
  #   path: registry/              # subdirectory in repo
  #   auth:
  #     type: token                # or "ssh"
  #     tokenEnvVar: GITHUB_TOKEN  # env var with PAT

  # Authentication for HTTP registries
  # auth:
  #   type: bearer
  #   tokenEnvVar: REGISTRY_TOKEN

  # Cache settings
  cache:
    enabled: true
    ttl: 3600000 # milliseconds (1 hour)

# =====================
# Target Configuration
# =====================
targets:
  # GitHub Copilot
  github:
    enabled: true
    output: .github/copilot-instructions.md

    # Target-specific options
    options:
      includeComments: true
      headerLevel: 2

  # Claude Code
  claude:
    enabled: true
    output: CLAUDE.md

    options:
      format: 'detailed'

  # Cursor
  cursor:
    enabled: true
    output: .cursor/rules/project.mdc

    options:
      compact: true

# =========================
# Validation Configuration
# =========================
validation:
  # Treat warnings as errors
  strict: false

  # Warnings to ignore
  ignoreWarnings:
    - 'unused-shortcut'

  # Custom rules
  rules:
    require-syntax: error
    require-identity: warning
    max-shortcuts: 20

# ====================
# Watch Configuration
# ====================
watch:
  # Files to watch
  include:
    - '.promptscript/**/*.prs'
    - 'registry/**/*.prs'

  # Files to ignore
  exclude:
    - '**/node_modules/**'
    - '**/.git/**'

  # Debounce delay (ms)
  debounce: 300

  # Clear console on rebuild
  clearScreen: true

# =====================
# Output Configuration
# =====================
output:
  # Base directory for all outputs
  baseDir: '.'

  # File header comment
  header: |
    # Auto-generated by PromptScript
    # Do not edit manually

  # Overwrite existing files
  overwrite: true

# =========================
# Formatting Configuration
# =========================
formatting:
  # Auto-detect .prettierrc in project
  prettier: true

  # Or specify explicit path to .prettierrc
  # prettier: "./config/.prettierrc"

  # Or specify options directly
  # proseWrap: always    # 'always' | 'never' | 'preserve'
  # tabWidth: 4          # Number of spaces per indent
  # printWidth: 100      # Max line width for prose wrapping

Configuration Sections¶

input¶

Configures source file handling.

input:
  entry: .promptscript/project.prs
  include:
    - '.promptscript/**/*.prs'
  exclude:
    - '**/*.test.prs'

Field	Type	Default	Description
`entry`	string	Required	Main entry point
`include`	string[]	`["*/.prs"]`	Glob patterns to include
`exclude`	string[]	`[]`	Glob patterns to exclude

registry¶

Configures the inheritance registry. PromptScript supports three registry types:

Local filesystem - for development or monorepos
HTTP/HTTPS - for simple remote registries
Git repository - recommended for teams (supports versioning via tags)

Local Registry¶

registry:
  path: ./registry

HTTP Registry¶

registry:
  url: https://registry.example.com/promptscript
  auth:
    type: bearer
    tokenEnvVar: REGISTRY_TOKEN

Git Registry¶

registry:
  git:
    url: https://github.com/org/promptscript-registry.git
    ref: main
    path: registry/
    auth:
      type: token
      tokenEnvVar: GITHUB_TOKEN
  cache:
    enabled: true
    ttl: 3600000

Registry Fields:

Field	Type	Default	Description
`path`	string	-	Local registry path
`url`	string	-	HTTP registry URL
`git.url`	string	-	Git repository URL
`git.ref`	string	`main`	Branch, tag, or commit
`git.path`	string	-	Subdirectory within the repo
`git.auth.type`	string	-	Auth type: `token` or `ssh`
`git.auth.token`	string	-	Personal access token (direct)
`git.auth.tokenEnvVar`	string	-	Env var containing the token
`git.auth.sshKeyPath`	string	-	Path to SSH key (for SSH auth)
`cache.enabled`	boolean	`true`	Enable caching
`cache.ttl`	number	`3600000`	Cache TTL in milliseconds

Version-tagged imports

With Git registry, you can pin imports to specific versions using Git tags:

```
@inherit @company/base@1.0.0
@use @company/security@2.1.0 as sec
```

This checkouts the specified tag before fetching the file.

targets¶

Configures output targets.

targets:
  github:
    enabled: true
    output: .github/copilot-instructions.md
    options:
      includeComments: true

Available Targets:

Target	Default Output	Default Convention	Supported Versions
`github`	`.github/copilot-instructions.md`	`markdown`	simple / multifile / full
`claude`	`CLAUDE.md`	`markdown`	simple / multifile / full
`cursor`	`.cursor/rules/project.mdc`	`markdown`	modern / multifile / legacy
`antigravity`	`.agent/rules/project.md`	`markdown`	simple / frontmatter

Cursor Versions:

Version	Output Files
`modern`	`.cursor/rules/project.mdc` + `.cursor/commands/*.md` for multi-line shortcuts
`multifile`	Main + `.cursor/rules/.mdc` (glob-based) + `.cursor/rules/shortcuts.mdc` + `.cursor/commands/.md`
`legacy`	`.cursorrules` (deprecated, no slash commands)

Cursor Slash Commands

Multi-line @shortcuts are automatically converted to executable slash commands in .cursor/commands/. Type / in Cursor chat (1.6+) to invoke them. See Language Reference.

Cursor Identity Handling

The Cursor formatter handles @identity blocks intelligently:

- If the identity starts with "You are...", the **full content** is used as the intro
- Otherwise, a generated intro like "You are working on {project}" is created
- Multiline strings are automatically dedented to remove source indentation

This means your `@identity` content appears exactly as written (without extra indentation).

Target Configuration:

Targets can be specified as simple names or with configuration:

targets:
  # Simple format (uses defaults)
  - github
  - claude
  - antigravity

  # With configuration
  - github:
      convention: xml
      output: custom/path/instructions.md
  - claude:
      convention: markdown

  # With version for format variants
  - cursor:
      version: legacy # Use .cursorrules for Cursor < 0.45
  - antigravity:
      version: frontmatter # Use YAML frontmatter with activation types

  # GitHub Copilot versions
  - github:
      version: simple # Single file (default)
  - github:
      version: multifile # Main + path-specific instructions + prompts
  - github:
      version: full # Multifile + skills + AGENTS.md

  # Claude Code versions
  - claude:
      version: simple # Single CLAUDE.md (default)
  - claude:
      version: multifile # Main + modular rules in .claude/rules/
  - claude:
      version: full # Multifile + skills + CLAUDE.local.md

GitHub Copilot Versions:

Version	Output Files
`simple`	`.github/copilot-instructions.md` (single file)
`multifile`	Main + `.github/instructions/.instructions.md` + `.github/prompts/.prompt.md`
`full`	Multifile + `.github/skills/<name>/SKILL.md` + `AGENTS.md`

Claude Code Versions:

Version	Output Files
`simple`	`CLAUDE.md` (single file)
`multifile`	Main + `.claude/rules/*.md` with path-specific rules (from `@guards.globs`)
`full`	Multifile + `.claude/skills/<name>/SKILL.md` (from `@skills`) + `CLAUDE.local.md` (from `@local`)

Target Options:

Field	Type	Default	Description
`enabled`	boolean	`true`	Whether target is enabled
`output`	string	(see above)	Custom output path
`convention`	string	`markdown`	Output convention ('xml' or 'markdown')
`version`	string	(default)	Format version ('legacy' for deprecated)

Disabling Targets

Setting enabled: false skips the target during compilation. This is equivalent to removing the target from the list.

```yaml
targets:
  - github               # Will compile
  - claude:
      enabled: false     # Will NOT compile (skipped)
  - cursor               # Will compile
```

See Formatters API for more details.

Built-in Conventions:

Convention	Section Format	Description
`markdown`	`## Section Name`	Markdown headers
`xml`	`<section-name>content</section-name>`	XML tags wrapping content

customConventions¶

Define custom output conventions for specialized formatting needs.

customConventions:
  my-format:
    name: my-format
    section:
      prefix: '### '
      suffix: ''
      contentPrefix: "\n"
      contentSuffix: "\n\n"
    list:
      itemPrefix: '→ '
      itemSuffix: ''
      listPrefix: ''
      listSuffix: "\n"
    codeBlock:
      prefix: '~~~'
      suffix: '~~~'
      languageSupport: true

# Use custom convention in target
targets:
  - github:
      convention: my-format

Custom Convention Structure:

Field	Type	Description
`name`	string	Convention identifier
`section.prefix`	string	Text before section name
`section.suffix`	string	Text after section name
`section.contentPrefix`	string	Text before section content
`section.contentSuffix`	string	Text after section content
`list.itemPrefix`	string	Text before each list item
`list.itemSuffix`	string	Text after each list item
`list.listPrefix`	string	Text before the list
`list.listSuffix`	string	Text after the list
`codeBlock.prefix`	string	Code block start marker
`codeBlock.suffix`	string	Code block end marker
`codeBlock.languageSupport`	boolean	Whether to include language identifier

validation¶

Configures validation behavior.

validation:
  strict: false
  ignoreWarnings:
    - 'unused-shortcut'
  rules:
    require-syntax: error

Field	Type	Default	Description
`strict`	boolean	`false`	Warnings as errors
`ignoreWarnings`	string[]	`[]`	Warning codes to ignore
`rules`	object	`{}`	Rule severity overrides

watch¶

Configures watch mode.

watch:
  include:
    - '.promptscript/**/*.prs'
  debounce: 300
  clearScreen: true

Field	Type	Default	Description
`include`	string[]	`["*/.prs"]`	Patterns to watch
`exclude`	string[]	`[]`	Patterns to ignore
`debounce`	number	`300`	Debounce delay (ms)
`clearScreen`	boolean	`true`	Clear on rebuild

formatting¶

Configures output formatting to match your project's Prettier configuration.

formatting:
  # Option 1: Auto-detect .prettierrc in project
  prettier: true

  # Option 2: Explicit path to Prettier config
  prettier: "./config/.prettierrc"

  # Option 3: Inline options (overrides .prettierrc)
  proseWrap: always
  tabWidth: 4
  printWidth: 100

Prettier Detection:

When prettier: true, PromptScript searches for Prettier configuration files in this order:

.prettierrc
.prettierrc.json
.prettierrc.yaml
.prettierrc.yml

Configuration Fields:

Field	Type	Default	Description
`prettier`	boolean \| string \| object	-	Enable auto-detect, path, or options
`proseWrap`	`'always'` \| `'never'` \| `'preserve'`	`'preserve'`	How to wrap prose in markdown
`tabWidth`	number	`2`	Number of spaces per indentation
`printWidth`	number	`80`	Maximum line width for wrapping

ProseWrap Options:

Value	Description
`'always'`	Wrap prose at `printWidth`
`'never'`	Do not wrap prose (single long lines)
`'preserve'`	Preserve original line wrapping from source

Option Priority

Explicit options (proseWrap, tabWidth, printWidth) override values from .prettierrc. This allows you to use your project's Prettier config as a base while customizing specific options.

Example: Match Project Prettier Config

If your project already has a .prettierrc:

formatting:
  prettier: true

Example: Custom Formatting Without Prettier File

formatting:
  tabWidth: 4
  proseWrap: always
  printWidth: 100

Environment Variables¶

Configuration values can reference environment variables:

registry:
  auth:
    token: ${REGISTRY_TOKEN}

targets:
  github:
    output: ${OUTPUT_DIR:-.github}/copilot-instructions.md

Syntax	Description
`${VAR}`	Required variable
`${VAR:-default}`	Variable with default

Minimal Configuration¶

The simplest valid configuration:

input:
  entry: .promptscript/project.prs

targets:
  github:
    enabled: true

Extending Configuration¶

You can extend another configuration file:

extends: ./base.config.yaml

targets:
  github:
    output: custom/path.md

Extended configurations are deep-merged.

Schema Validation¶

The configuration file is validated against a JSON schema. Enable editor support by adding the schema reference at the top of your promptscript.yaml:

# yaml-language-server: $schema=https://getpromptscript.dev/latest/schema/config.json

input:
  entry: .promptscript/project.prs

This provides:

Autocomplete - suggestions for all configuration options
Validation - errors for invalid fields or values
Documentation - hover tooltips with field descriptions

Schema is the source of truth

The JSON schema is automatically generated from TypeScript types in @promptscript/core. When in doubt about configuration options, the schema reflects the current implementation.

Schema URL: [`schema/config.json`](https://getpromptscript.dev/latest/schema/config.json)

Examples¶

Minimal Project¶

input:
  entry: .promptscript/project.prs

targets:
  github:
    enabled: true

Multi-Team Setup¶

input:
  entry: .promptscript/${TEAM}/project.prs

registry:
  path: ./shared-registry

targets:
  github:
    enabled: true
    output: .github/copilot-instructions.md
  claude:
    enabled: true
    output: CLAUDE.md

CI/CD Configuration¶

input:
  entry: .promptscript/project.prs

registry:
  git:
    url: https://github.com/org/promptscript-registry.git
    ref: main
    auth:
      type: token
      tokenEnvVar: GITHUB_TOKEN
  cache:
    enabled: true
    ttl: 3600000

validation:
  strict: true

targets:
  github:
    enabled: true
  claude:
    enabled: true
  cursor:
    enabled: true
  antigravity:
    enabled: true

Private Git Registry with SSH¶

registry:
  git:
    url: git@github.com:org/private-registry.git
    ref: v1.0.0 # Pin to specific version
    auth:
      type: ssh
      sshKeyPath: ~/.ssh/id_ed25519