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 registry URL
  # url: https://github.com/org/promptscript-registry

  # Authentication for private registries
  # auth:
  #   token: ${REGISTRY_TOKEN}

  # Cache settings
  cache:
    enabled: true
    ttl: 3600 # seconds

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

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.

registry:
  path: ./registry
  cache:
    enabled: true
    ttl: 3600

Field	Type	Default	Description
`path`	string	-	Local registry path
`url`	string	-	Remote registry URL
`cache.enabled`	boolean	`true`	Enable caching
`cache.ttl`	number	`3600`	Cache TTL in seconds

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

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

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/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/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:
  url: https://github.com/org/registry
  auth:
    token: ${GITHUB_TOKEN}

validation:
  strict: true

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