### Multi-Team Setup Example

Source: https://getpromptscript.dev/latest/reference/config?q=

Configuration for a multi-team setup with different outputs for various targets.

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

registry:
  path: ./shared-registry

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

```

--------------------------------

### Enterprise Policy Configuration Example

Source: https://getpromptscript.dev/latest/guides/policy-engine

An example `promptscript.yaml` for a three-layer enterprise setup, enforcing layer governance, core immutability, and source control.

```yaml
# promptscript.yaml

# Layer 1: Core platform (managed by platform team)
# Layer 2: Team configurations
# Layer 3: Project-level customizations

policies:
  - name: layer-governance
    kind: layer-boundary
    description: 'Enforce layer hierarchy'
    severity: error
    layers: ['@platform/core', '@teams', '@projects']
    maxDistance: 1

  - name: core-immutability
    kind: property-protection
    description: 'Core skill content cannot be overridden'
    severity: error
    properties: ['content', 'description']
    targetPattern: '@platform/core/*'

  - name: approved-sources
    kind: registry-allowlist
    description: 'Only approved registries can contribute extensions'
    severity: error
    allowed: ['@platform/core', '@teams']


```

--------------------------------

### After Migration Example (.promptscript/project.prs)

Source: https://getpromptscript.dev/latest/getting-started?q=

Example of a PromptScript file after migration.

```promptscript
@meta {
  id: "api-service"
  syntax: "1.0.0"
}

@identity {
  """
  You are a Python developer working on a FastAPI service.
  """
}

@context {
  languages: [python]
  runtime: "Python 3.11"
  frameworks: [fastapi]
  database: "PostgreSQL"
}

@standards {
  code: [
    "Write type hints for all functions",
    "Use async/await for I/O operations"
  ]
}

@restrictions {
  - "Don't commit .env files"
}

```

--------------------------------

### Example Compilation Output

Source: https://getpromptscript.dev/latest/guides/examples

Illustrates how an @examples block compiles into a dedicated 'Examples' section in the output instruction file.

```PromptScript
@meta {
  id: "naming-examples"
  syntax: "1.2.0"
}

@examples {
  camel-case: {
    description: "Variable naming convention"
    input: "const user_name = 'Alice'"
    output: "const userName = 'Alice'"
  }
}

```

--------------------------------

### Project Configuration Example

Source: https://getpromptscript.dev/latest/examples/enterprise?q=

Example PromptScript configuration for a project named 'checkout-app'.

```PromptScript
# checkout-app/promptscript/project.prs
@meta {
  id: "checkout-app"
  syntax: "2.1.0"
}

```

--------------------------------

### Initialize PromptScript project interactively

Source: https://getpromptscript.dev/latest/reference/cli?q=

Initializes a PromptScript project in the current directory using interactive prompts to guide the setup.

```bash
prs init
```

--------------------------------

### PromptScript Configuration Example

Source: https://getpromptscript.dev/latest/getting-started

Example `promptscript.yaml` file demonstrating input and output target configurations.

```yaml
version: '1'

# Input settings
input:
  entry: .promptscript/project.prs

# Output targets
targets:
  # GitHub Copilot - multifile generates .github/prompts/*.prompt.md
  - github:
      version: multifile

  # Claude Code
  - claude

  # Cursor - modern generates .cursor/commands/*.md
  - cursor

  # Antigravity
  - antigravity

# Optional: Registry for inheritance
registry:
  path: ./registry
  # Or remote: https://github.com/your-org/promptscript-registry

```

--------------------------------

### GitHub Actions CI/CD Setup

Source: https://getpromptscript.dev/latest/examples/git-registry?q=

Automates PromptScript CLI installation, registry pulls, compilation, and change detection on push events.

```yaml
# .github/workflows/promptscript.yml
name: PromptScript CI

on:
  push:
    paths:
      - '.promptscript/**'
      - 'promptscript.yaml'

jobs:
  compile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install PromptScript
        run: npm install -g @promptscript/cli

      - name: Pull registry updates
        run: prs pull
        env:
          GITHUB_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

      - name: Compile
        run: prs compile

      - name: Check for changes
        run: |
          git diff --exit-code || {
            echo "::error::Compiled files changed. Run 'prs compile' locally."
            exit 1
          }

```

--------------------------------

### Set @examples syntax version

Source: https://getpromptscript.dev/latest/guides/examples?q=

Shows how to set the required syntax version for @examples.

```yaml
@meta {
  id: "my-project"
  syntax: "1.2.0"    # Required for @examples
}

```

--------------------------------

### Basic @examples Syntax

Source: https://getpromptscript.dev/latest/guides/examples

Defines a simple example for renaming a variable. Each entry requires 'input' and 'output' fields.

```PromptScript
@meta {
  id: "my-project"
  syntax: "1.2.0"
}

@examples {
  rename-variable: {
    input: "const x = 1"
    output: "const itemCount = 1"
  }
}

```

--------------------------------

### startServer()

Source: https://getpromptscript.dev/latest/api-reference/server/src/functions/startServer?q=

Starts the server with the provided options. This function is asynchronous and returns a Promise that resolves when the server has started.

```APIDOC
## startServer()

### Description
Starts the server with the provided options. This function is asynchronous and returns a Promise that resolves when the server has started.

### Method
`startServer`

### Parameters
#### options
- **options** (`ServerOptions`) - Required - Configuration options for the server.

### Returns
- `Promise<void>` - A promise that resolves when the server has successfully started.
```

--------------------------------

### Before Migration Example (CLAUDE.md)

Source: https://getpromptscript.dev/latest/getting-started?q=

Example of an instruction file before migration.

```markdown
# Project

You are a Python developer working on a FastAPI service.

## Stack

- Python 3.11, FastAPI, PostgreSQL

## Rules

- Write type hints for all functions
- Use async/await for I/O

## Don'ts

- Don't commit .env files

```

--------------------------------

### examples()

Source: https://getpromptscript.dev/latest/api-reference/formatters/src/classes/FactoryFormatter

Generates examples from an AST using a specified renderer. This protected method is inherited.

```APIDOC
## examples()

### Description
Generates examples from an Abstract Syntax Tree (AST) using a specified renderer.

### Method
protected

### Signature
examples(ast: Program, renderer: ConventionRenderer): string | null

### Parameters
#### ast
- **ast** (Program) - The Abstract Syntax Tree to generate examples from.
#### renderer
- **renderer** (ConventionRenderer) - The convention renderer to use for example generation.

### Returns
- `string | null` - The generated examples string or null if not possible.
```

--------------------------------

### Full PromptScript Configuration Example

Source: https://getpromptscript.dev/latest/reference/config?q=

This is a comprehensive example of a promptscript.yaml file, illustrating all available configuration sections and their common settings. Use this as a template for your project's configuration.

```yaml
# ===================
# 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
  #   fallbackUrl: git@github.com:org/promptscript-registry.git  # SSH fallback
  #   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:
  # List format (matches prs init output)
  - github
  - claude
  - cursor

# =============================
# Named Build Profiles
# =============================
builds:
  plugin-factory:
    # Optional entry override for this build only
    entry: .promptscript/project.prs

    # Optional output directory for this build only
    output: plugins/logstrip

    # Optional target list for this build only
    targets:
      - factory:
          version: multifile
          skillBaseDir: skills
          includeSkills:
            - logstrip

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

# =============================
# Universal Directory & Skills
# =============================

# Universal directory for auto-discovering skills and commands.
# - true or omitted: Use default '.agents/' directory
# - false: Disable universal directory discovery
# - string: Custom path (relative to project root)
universalDir: true # default: '.agents'

# Include the bundled PromptScript language skill in compilation output.
# When enabled, a SKILL.md that teaches AI agents how to work with .prs
# files is automatically added to each target's native skill directory.
includePromptScriptSkill: true # default: true

```

--------------------------------

### startServer()

Source: https://getpromptscript.dev/latest/api-reference/server/src/functions/startServer

Starts the server with the specified options. This function is asynchronous and returns a Promise that resolves when the server has started.

```APIDOC
## startServer()

### Description
Starts the server with the specified options. This function is asynchronous and returns a Promise that resolves when the server has started.

### Signature
`startServer(options): Promise<void>`

### Parameters
#### options
- **options** (`ServerOptions`) - Description: Server configuration options.

### Returns
- `Promise<void>` - A promise that resolves when the server has successfully started.
```

--------------------------------

### RegistryManifest Example

Source: https://getpromptscript.dev/latest/api-reference/core/src/interfaces/RegistryManifest

An example of a complete registry manifest file, demonstrating its structure and content.

```yaml
version: '1'
meta:
  name: "PromptScript Official Registry"
  description: "Official collection of AI instruction configurations"
  lastUpdated: "2026-01-28"
namespaces:
  "@core":
    description: "Universal foundations"
    priority: 100
catalog:
  - id: "@core/base"
    path: "@core/base.prs"
    name: "Base Foundation"
    description: "Universal AI assistant foundation"
    tags: [core, foundation]
    targets: [github, claude, cursor]
    dependencies: []
suggestionRules:
  - condition: { always: true }
    suggest: { inherit: "@core/base" }

```

--------------------------------

### examples()

Source: https://getpromptscript.dev/latest/api-reference/formatters/src/classes/GeminiFormatter?q=

Extracts examples from an Abstract Syntax Tree (AST) using a specified renderer.

```APIDOC
## examples()

### Description
Extracts examples from an Abstract Syntax Tree (AST) using a specified renderer.

### Method
protected

### Parameters
#### ast
- **ast** (Program) - The Abstract Syntax Tree to process.
#### renderer
- **renderer** (ConventionRenderer) - The renderer to use for extracting examples.

### Returns
- **string | null** - A string representing the examples, or null if none are found.
```

--------------------------------

### Install PromptScript CLI with npm

Source: https://getpromptscript.dev/latest/getting-started

Install the PromptScript CLI globally using npm.

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

```

--------------------------------

### Install Skill using 'skills' CLI (Skills.sh)

Source: https://getpromptscript.dev/latest/guides/local-skills?q=

Install a specific skill from a GitHub repository to your local skills directory using the 'skills' CLI. Ensure you have the CLI installed.

```shell
# Browse available skills
npx skills add anthropics/skills --list

# Install a specific skill to your local skills directory
npx skills add anthropics/skills \
  --skill frontend-design \
  --dir .promptscript/skills

# Install from any GitHub repo
npx skills add vercel-labs/agent-skills \
  --skill ui-design \
  --dir .promptscript/skills
```

--------------------------------

### Adding Descriptions to Examples

Source: https://getpromptscript.dev/latest/guides/examples

Includes optional 'description' fields to label what each example demonstrates, such as conventional commit styles.

```PromptScript
@meta {
  id: "commit-style"
  syntax: "1.2.0"
}

@examples {
  feat-commit: {
    description: "Feature commit with scope"
    input: "Added user authentication with JWT tokens"
    output: "feat(auth): add JWT-based user authentication"
  }

  fix-commit: {
    description: "Bug fix commit"
    input: "Fixed null pointer in payment service"
    output: "fix(payments): resolve null pointer in charge handler"
  }
}

```

--------------------------------

### Install PromptScript CLI with yarn

Source: https://getpromptscript.dev/latest/getting-started

Install the PromptScript CLI globally using yarn.

```bash
yarn global add @promptscript/cli

```

--------------------------------

### Structured Few-Shot Examples

Source: https://getpromptscript.dev/latest/reference/language?q=

Define structured few-shot examples for AI assistants using the @meta and @examples directives. Supports syntax versioning.

```PromptScript
@meta {
  id: "commit-style"
  syntax: "1.2.0"
}

@examples {
  feat-commit: {
    description: "Feature commit with scope"
    input: "Added user authentication with JWT tokens"
    output: "feat(auth): add JWT-based user authentication"
  }

  multiline-example: {
    input: """
      const x = users.filter(u => u.active).map(u => u.email);
    """
    output: """
      const activeEmails = users
        .filter(u => u.active)
        .map(u => u.email);
    """
  }
}

```

--------------------------------

### Install PromptScript CLI with pnpm

Source: https://getpromptscript.dev/latest/getting-started

Install the PromptScript CLI globally using pnpm.

```bash
pnpm add -g @promptscript/cli

```

--------------------------------

### Stack Advisor Skill Usage Example

Source: https://getpromptscript.dev/latest/guides/building-skills

Example of how to run a comparison script within the 'stack-advisor' skill.

```bash
python3 .claude/skills/stack-advisor/scripts/compare.py "react" "vue"

```

--------------------------------

### Structured Few-Shot Examples

Source: https://getpromptscript.dev/latest/reference/language

Define structured few-shot examples using the @examples block. Requires syntax version 1.2.0. The 'input' and 'output' properties are required, while 'description' is optional.

```PromptScript
@meta {
  id: "commit-style"
  syntax: "1.2.0"
}

@examples {
  feat-commit: {
    description: "Feature commit with scope"
    input: "Added user authentication with JWT tokens"
    output: "feat(auth): add JWT-based user authentication"
  }

  multiline-example: {
    input: """
      const x = users.filter(u => u.active).map(u => u.email);
    "
    output: """
      const activeEmails = users
        .filter(u => u.active)
        .map(u => u.email);
    "
  }
}

```

--------------------------------

### Start PromptScript Development Server

Source: https://getpromptscript.dev/latest/reference/cli?q=

Starts a local development server to connect the online playground with local .prs files. Use default port 3000 or specify a custom port.

```bash
prs serve
```

```bash
prs serve --port 8080
```

```bash
prs serve --host 0.0.0.0
```

```bash
prs serve --read-only
```

--------------------------------

### URL Import Example in .prs File

Source: https://getpromptscript.dev/latest/examples/git-registry

Example .prs file demonstrating direct URL imports for PromptScript files, including versioned imports.

```prs
@meta {
  id: "my-project"
  syntax: "1.0.0"
}

# Direct URL import — no alias needed
@use github.com/acme/shared-standards/fragments/security

# Open-source skill auto-discovered from SKILL.md
@use github.com/some-org/claude-skills/skills/tdd-workflow

# Versioned URL import
@use github.com/acme/shared-standards/stacks/typescript@1.0.0


```

--------------------------------

### Install a community skill

Source: https://getpromptscript.dev/latest/guides/npx-skills?q=

Install a skill from any public GitHub repository by specifying the repository owner and name, along with the skill name and target directory.

```bash
npx skills add someone/their-skills \
  --skill my-skill \
  --dir .promptscript/skills
```

--------------------------------

### Install a skill to the default directory

Source: https://getpromptscript.dev/latest/guides/npx-skills?q=

Install a skill using the default `.agents/skills/` directory by omitting the `--dir` flag. PromptScript automatically discovers skills in this location.

```bash
npx skills add anthropics/skills --skill commit
```

--------------------------------

### Compilation Output Example

Source: https://getpromptscript.dev/latest/guides/local-skills

This example shows the expected output after compiling a project that targets multiple platforms (claude, factory, gemini) and includes local skills.

```bash
# Output for a project targeting claude + factory + gemini:
✓ .claude/skills/ui-ux-pro-max/SKILL.md
✓ .claude/skills/ui-ux-pro-max/data/colors.csv
✓ .claude/skills/ui-ux-pro-max/scripts/search.py
✓ .factory/skills/ui-ux-pro-max/SKILL.md
✓ .factory/skills/ui-ux-pro-max/data/colors.csv
✓ .factory/skills/ui-ux-pro-max/scripts/search.py
✓ .gemini/skills/ui-ux-pro-max/skill.md
✓ .gemini/skills/ui-ux-pro-max/data/colors.csv
✓ .gemini/skills/ui-ux-pro-max/scripts/search.py

```

--------------------------------

### Inherit Configurations and Use Fragments

Source: https://getpromptscript.dev/latest/guides/registry?q=

This example shows how to define project metadata and inherit configurations from a registry. It includes inheriting a base stack and using specific fragments for testing.

```promptscript
@meta {
  id: "my-project"
  syntax: "1.0.0"
}

@inherit @stacks/react
@use @fragments/testing


```

--------------------------------

### XML Section Start Template

Source: https://getpromptscript.dev/latest/api-reference/core/src/interfaces/SectionRenderer?q=

Example of a start template for XML sections.

```xml
<{{name}}>
```

--------------------------------

### Install community skill

Source: https://getpromptscript.dev/latest/guides/npx-skills

Install a skill from any public GitHub repository by specifying the repository owner and name, along with the skill name and target directory.

```bash
npx skills add someone/their-skills \
  --skill my-skill \
  --dir .promptscript/skills

```

--------------------------------

### Markdown Section Start Template

Source: https://getpromptscript.dev/latest/api-reference/core/src/interfaces/SectionRenderer?q=

Example of a start template for Markdown sections, using repeat for heading levels.

```markdown
{{#repeat level}}#{{/repeat}} {{name}}
```

--------------------------------

### Policy Configuration Example

Source: https://getpromptscript.dev/latest/guides/policy-engine?q=

Define policies in `promptscript.yaml` to enforce organizational rules. This example shows configurations for layer boundaries, property protection, and registry allowlisting.

```yaml
policies:
  - name: adjacent-layers-only
    kind: layer-boundary
    description: 'Only adjacent layers can extend each other'
    severity: error
    layers: ['@core', '@team', '@project']
    maxDistance: 1

  - name: protect-content
    kind: property-protection
    description: 'Content override requires explicit approval'
    severity: warning
    properties: ['content', 'description']

  - name: approved-registries
    kind: registry-allowlist
    description: 'Extensions must come from approved registries'
    severity: error
    allowed: ['@core', '@team']

```

--------------------------------

### GitLab CI/CD Setup

Source: https://getpromptscript.dev/latest/examples/git-registry?q=

Configures GitLab CI to install PromptScript, pull registry updates, compile, and check for changes.

```yaml
# .gitlab-ci.yml
promptscript:
  image: node:20
  script:
    - npm install -g @promptscript/cli
    - prs pull
    - prs compile
    - git diff --exit-code
  variables:
    # Use GITLAB_TOKEN for GitLab registries, or match your tokenEnvVar config
    GITLAB_TOKEN: $REGISTRY_TOKEN
  only:
    changes:
      - .promptscript/**/*
      - promptscript.yaml

```

--------------------------------

### Example Target Configuration with Custom Options

Source: https://getpromptscript.dev/latest/reference/config

Demonstrates a combined approach using both list and object formats for target configuration, including custom output paths and conventions.

```yaml
targets:
  # List format (recommended)
  - github
  - claude
  - cursor
  - antigravity

  # Object format (for custom options)
  - 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
  - github:
      version: multifile # Main + path-specific instructions + prompts
  - github:
      version: full # Multifile + skills + AGENTS.md (default)

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

  # OpenCode versions
  - opencode:
      version: simple # Single OPENCODE.md
  - opencode:
      version: multifile # Main + commands
  - opencode:
      version: full # Multifile + skills + agents

  # Gemini CLI versions
  - gemini:
      version: simple # Single GEMINI.md
  - gemini:
      version: multifile # Main + commands + skills
  - gemini:
      version: full # Same as multifile (no agent concept)

```

--------------------------------

### GitLab CI/CD Integration

Source: https://getpromptscript.dev/latest/examples/git-registry

Example GitLab CI configuration for installing PromptScript, pulling registry updates, compiling, and checking for changes.

```yaml
# .gitlab-ci.yml
promptscript:
  image: node:20
  script:
    - npm install -g @promptscript/cli
    - prs pull
    - prs compile
    - git diff --exit-code
  variables:
    # Use GITLAB_TOKEN for GitLab registries, or match your tokenEnvVar config
    GITLAB_TOKEN: $REGISTRY_TOKEN
  only:
    changes:
      - .promptscript/**/*
      - promptscript.yaml


```

--------------------------------

### Target Configuration Examples

Source: https://getpromptscript.dev/latest/reference/config?q=

Demonstrates various target configurations including custom output paths, conventions, and specific versions for different targets.

```yaml
targets:
  # List format (recommended)
  - github
  - claude
  - cursor
  - antigravity

  # Object format (for custom options)
  - 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
  - github:
      version: multifile # Main + path-specific instructions + prompts
  - github:
      version: full # Multifile + skills + AGENTS.md (default)

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

  # OpenCode versions
  - opencode:
      version: simple # Single OPENCODE.md
  - opencode:
      version: multifile # Main + commands
  - opencode:
      version: full # Multifile + skills + agents

  # Gemini CLI versions
  - gemini:
      version: simple # Single GEMINI.md
  - gemini:
      version: multifile # Main + commands + skills
  - gemini:
      version: full # Same as multifile (no agent concept)
```

--------------------------------

### PromptScript CLI: Initialize

Source: https://getpromptscript.dev/latest/examples/minimal?q=

Command to initialize a new PromptScript project from scratch.

```bash
prs init

```

--------------------------------

### GitHub Actions CI/CD Integration

Source: https://getpromptscript.dev/latest/examples/git-registry

Example GitHub Actions workflow for installing PromptScript, pulling registry updates, compiling, and checking for changes.

```yaml
# .github/workflows/promptscript.yml
name: PromptScript CI

on:
  push:
    paths:
      - '.promptscript/**'
      - 'promptscript.yaml'

jobs:
  compile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install PromptScript
        run: npm install -g @promptscript/cli

      - name: Pull registry updates
        run: prs pull
        env:
          GITHUB_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

      - name: Compile
        run: prs compile

      - name: Check for changes
        run: |
          git diff --exit-code || {
            echo "::error::Compiled files changed. Run 'prs compile' locally."
            exit 1
          }


```

--------------------------------

### Install a skill using OpenSkills

Source: https://getpromptscript.dev/latest/guides/npx-skills?q=

Install skills using the OpenSkills installer, specifying the skill name and the target directory for installation.

```bash
npx openskills install frontend-design \
  --dir .promptscript/skills
```

--------------------------------

### Install skill using OpenSkills

Source: https://getpromptscript.dev/latest/guides/npx-skills

Use the `openskills` installer to add skills to your project, specifying the skill name and the target directory for installation.

```bash
npx openskills install frontend-design \
  --dir .promptscript/skills

```

--------------------------------

### Multiple Examples in a Block

Source: https://getpromptscript.dev/latest/guides/examples

Defines multiple, uniquely named examples within a single @examples block for various code review suggestions.

```PromptScript
@meta {
  id: "code-review-examples"
  syntax: "1.2.0"
}

@examples {
  missing-error-handling: {
    description: "Always wrap async calls in try/catch"
    input: """
      async function fetchUser(id: string) {
        const res = await fetch(`/api/users/${id}`);
        return res.json();
      }
    """
    output: """
      async function fetchUser(id: string) {
        try {
          const res = await fetch(`/api/users/${id}`);
          if (!res.ok) throw new Error(`HTTP ${res.status}`);
          return res.json();
        } catch (err) {
          logger.error('fetchUser failed', { id, err });
          throw err;
        }
      }
    """
  }

  prefer-const: {
    description: "Use const for values that never change"
    input: "let MAX_RETRIES = 3"
    output: "const MAX_RETRIES = 3"
  }

  explicit-return-type: {
    description: "Add return types to public functions"
    input: "function add(a: number, b: number) { return a + b; }"
    output: "function add(a: number, b: number): number { return a + b; }"
  }
}

```

--------------------------------

### Examples Attached to @skills

Source: https://getpromptscript.dev/latest/guides/examples

Co-locates examples directly within a skill definition for better organization. Demonstrates examples for creating git commits.

```PromptScript
@meta {
  id: "project-skills"
  syntax: "1.2.0"
}

@skills {
  commit: {
    description: "Create git commits following conventional format"
    examples: {
      basic: {
        input: "Added dark mode toggle to settings page"
        output: "feat(settings): add dark mode toggle"
      }

      with-breaking-change: {
        description: "Breaking change in API"
        input: "Renamed /users endpoint to /accounts"
        output: "feat(api)!: rename /users endpoint to /accounts"
      }
    }
    content: """
      When creating commits:
      1. Use conventional commit format: type(scope): description
      2. Keep the subject line under 72 characters
      3. Use imperative mood: "add feature" not "added feature"
    ""
  }
}

```

--------------------------------

### Input Configuration Example

Source: https://getpromptscript.dev/latest/reference/config?q=

Configure how PromptScript handles source files. Specify the main entry point, and glob patterns for files to include or exclude from processing.

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

```

--------------------------------

### Basic @use Import Examples

Source: https://getpromptscript.dev/latest/guides/multi-file?q=

Demonstrates how to use the `@use` directive to import content from local files, registry entries, and with aliases.

```promptscript
# Import fragment - blocks are merged into your file
@use ./fragments/security

# Import from registry
@use @company/standards/testing

# Import with alias - for @extend access
@use @core/guards/security as sec

```

--------------------------------

### Install a skill to a specific directory

Source: https://getpromptscript.dev/latest/guides/npx-skills

Install skills into a custom directory, such as `.promptscript/skills/`, for better project organization. This command installs the `frontend-design` skill from the `anthropics/skills` repository.

```bash
npx skills add anthropics/skills \
  --skill frontend-design \
  --dir .promptscript/skills
```

```bash
npx skills add anthropics/skills \
  --skill commit \
  --dir .promptscript/skills
```

```bash
npx skills add anthropics/skills \
  --skill code-review \
  --dir .promptscript/skills
```

--------------------------------

### examples()

Source: https://getpromptscript.dev/latest/api-reference/formatters/src/classes/KiroFormatter

Extracts example code blocks from the Abstract Syntax Tree (AST) using a specified renderer. This method is used internally to gather example definitions.

```APIDOC
## examples()

### Description
Extracts example code blocks from the Abstract Syntax Tree (AST) using a specified renderer. This method is used internally to gather example definitions.

### Method
protected

### Parameters
#### ast
- **ast** (Program) - The Abstract Syntax Tree node representing the program.
#### renderer
- **renderer** (ConventionRenderer) - The renderer instance to use for extracting examples.

### Returns
- **string | null** - A string representing the examples, or null if none are found.
```

--------------------------------

### Project Structure Example

Source: https://getpromptscript.dev/latest/examples/skills-and-local?q=

Illustrates a typical project structure for a PromptScript project, including configuration and main PromptScript files.

```text
my-project/
├── .promptscript/
│   └── project.prs          # Main PromptScript file
├── promptscript.yaml         # Configuration
├── .gitignore               # Include CLAUDE.local.md
└── ...

```

--------------------------------

### Manual Configuration Files Example

Source: https://getpromptscript.dev/latest/guides/vs-manual?q=

Illustrates the numerous configuration files typically maintained per repository when managing AI tools manually without a unified system.

```markdown
.github/copilot-instructions.md   # GitHub Copilot
CLAUDE.md                          # Claude Code
.cursor/rules/project.mdc         # Cursor
AGENTS.md                          # Codex / Factory AI
GEMINI.md                          # Gemini CLI
... one file per tool


```

--------------------------------

### Verify PromptScript Installation

Source: https://getpromptscript.dev/latest/getting-started

Check the installed version of the PromptScript CLI.

```bash
prs --version

```

--------------------------------

### Constructor

Source: https://getpromptscript.dev/latest/api-reference/browser-compiler/src/classes/VirtualFileSystem

Initializes a new instance of the VirtualFileSystem. Optionally accepts an initial set of files.

```APIDOC
## new VirtualFileSystem

### Description
Initializes a new instance of the VirtualFileSystem. Optionally accepts an initial set of files.

### Parameters
#### initialFiles? (Map<string, string> | Record<string, string>)
An optional map or object containing initial files to populate the virtual file system.

### Returns
`VirtualFileSystem` - A new instance of VirtualFileSystem.
```

--------------------------------

### Initialize PromptScript with Migration Support

Source: https://getpromptscript.dev/latest/getting-started

Command to initialize PromptScript and install migration skills for converting existing AI instruction files.

```bash
prs init --migrate

```

--------------------------------

### PromptScript Project Configuration

Source: https://getpromptscript.dev/latest/examples/git-registry

Example promptscript.yaml file configuring project details, inheritance, input, registry, and targets.

```yaml
version: '1'

project:
  id: customer-portal
  team: frontend

inherit: '@teams/frontend'

input:
  entry: .promptscript/project.prs

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

targets:
  - github
  - claude
  - cursor


```

--------------------------------

### startServer

Source: https://getpromptscript.dev/latest/api-reference/server/src?q=

Starts the PromptScript server, making it ready to handle requests and events.

```APIDOC
## startServer

### Description
Starts the PromptScript server.

### Function Signature
startServer(server: Server)

### Parameters
#### Parameters
- **server** (Server) - Required - The server instance to start.
```

--------------------------------

### startServer

Source: https://getpromptscript.dev/latest/api-reference/server/src

Starts the PromptScript server, making it ready to handle requests. This function should be called after the server has been created.

```APIDOC
## startServer

### Description
Starts the PromptScript server, making it ready to handle requests.

### Function Signature
startServer(server: Server): void

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **server** (Server) - Required - The server instance to start, typically obtained from `createServer`.

### Response
#### Success Response
None (void function)

### Example
```javascript
const server = createServer({ port: 8080 });
startServer(server);
```
```

--------------------------------

### User Configuration File Example

Source: https://getpromptscript.dev/latest/guides/user-config

Define default registry and project settings in the `~/.promptscript/config.yaml` file. This file sets up Git registry details, cache behavior, and default compilation targets and teams.

```yaml
version: '1'

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

defaults:
  targets:
    - github
    - claude
  team: frontend

```

--------------------------------

### extractSkillExamples()

Source: https://getpromptscript.dev/latest/api-reference/formatters/src/classes/FactoryFormatter

Extracts examples from a skill's nested examples property. This method is protected and inherited.

```APIDOC
## extractSkillExamples()

### Description
Extract examples from a skill's nested examples property. Returns the same shape as extractExamples.

### Method
protected

### Signature
extractSkillExamples(skillProps: Record<string, Value>): object[]

### Parameters
#### skillProps
- **skillProps** (Record<string, Value>) - The skill properties object containing nested examples.

### Returns
- `object[]` - An array of example objects.
```

--------------------------------

### extractExamples()

Source: https://getpromptscript.dev/latest/api-reference/formatters/src/classes/FactoryFormatter

Extracts examples from the AST. This method is inherited and protected, returning an array of example definitions.

```APIDOC
## extractExamples()

### Description
Extract examples from the AST. Returns an array of example definitions with name, input, output, and optional description.

### Method
protected

### Signature
extractExamples(ast: Program): object[]

### Parameters
#### ast
- **ast** (Program) - The Abstract Syntax Tree to extract examples from.

### Returns
- `object[]` - An array of example objects.
```

--------------------------------

### Create and Use FileSystemRegistry

Source: https://getpromptscript.dev/latest/api-reference/resolver/src/functions/createFileSystemRegistry?q=

Demonstrates how to create a FileSystemRegistry instance and fetch content from it. Ensure the root path exists and contains the specified registry file.

```typescript
const registry = createFileSystemRegistry('/path/to/registry');
const content = await registry.fetch('@core/guards/compliance.prs');

```

--------------------------------

### Initialize PromptScript project with defaults

Source: https://getpromptscript.dev/latest/reference/cli?q=

Quickly initializes a PromptScript project using default settings, skipping interactive prompts.

```bash
prs init -y
```

--------------------------------

### extractSkillExamples

Source: https://getpromptscript.dev/latest/api-reference/formatters/src/classes/AntigravityFormatter

Extracts examples from a skill's nested examples property, returning the same shape as extractExamples.

```APIDOC
## extractSkillExamples()

> `protected` **extractSkillExamples**(`skillProps`): `object`[]

Defined in: formatters/src/base-formatter.ts:605
Extract examples from a skill's nested examples property. Returns the same shape as extractExamples.
#### Parameters

##### skillProps

`Record`\<`string`, `Value`>

#### Returns

`object`[]

#### Inherited from

`BaseFormatter`.`extractSkillExamples`
```

--------------------------------

### PromptScript Migration Example

Source: https://getpromptscript.dev/latest/getting-started

Compares the 'Before' state of a CLAUDE.md file with its 'After' state in a .promptscript/project.prs file.

```markdown
# Project

You are a Python developer working on a FastAPI service.

## Stack

- Python 3.11, FastAPI, PostgreSQL

## Rules

- Write type hints for all functions
- Use async/await for I/O

## Don'ts

- Don't commit .env files
```

```promptscript
@meta {
  id: "api-service"
  syntax: "1.0.0"
}

@identity {
  """
  You are a Python developer working on a FastAPI service.
  """
}

@context {
  languages: [python]
  runtime: "Python 3.11"
  frameworks: [fastapi]
  database: "PostgreSQL"
}

@standards {
  code: [
    "Write type hints for all functions",
    "Use async/await for I/O operations"
  ]
}

@restrictions {
  - "Don't commit .env files"
}

```

--------------------------------

### examples()

Source: https://getpromptscript.dev/latest/api-reference/formatters/src/classes/KiroFormatter?q=

Processes an Abstract Syntax Tree (AST) and a renderer to generate example-related string output. This method is inherited from the MarkdownInstructionFormatter class.

```APIDOC
## examples()

### Description
Processes an Abstract Syntax Tree (AST) and a renderer to generate example-related string output. This method is inherited from the MarkdownInstructionFormatter class.

### Parameters
#### ast
- **ast** (Program) - The Abstract Syntax Tree node.
#### renderer
- **renderer** (ConventionRenderer) - The renderer to use for generating examples.

### Returns
- **string | null** - The generated example string or null if not applicable.
```

--------------------------------

### PromptScript Main File Example

Source: https://getpromptscript.dev/latest/examples/skills-and-local?q=

A comprehensive PromptScript file defining metadata, identity, context, standards, guards, restrictions, shortcuts, and skills for a fullstack application.

```promptscript
# .promptscript/project.prs

@meta {
  id: "my-fullstack-app"
  syntax: "1.0.0"
  name: "My Fullstack App"
  description: "A modern fullstack application with TypeScript"
}

@identity {
  """
  You are an expert fullstack developer specializing in TypeScript,
  React, and Node.js. You write clean, maintainable, and well-tested code.
  """
}

@context {
  languages: [typescript]
  runtime: "Node.js 20+"
  monorepo: {
    tool: "Nx"
    packageManager: "pnpm"
  }
}

@standards {
  typescript: [
    "Strict mode enabled",
    "Use named exports only"
  ]

  naming: [
    "Files: kebab-case.ts"
  ]

  testing: [
    "Use vitest as test framework",
    "Maintain 90% code coverage"
  ]

  git: [
    "Use Conventional Commits format",
    "Types: feat, fix, docs, style, refactor, test, chore"
  ]
}

@guards {
  globs: ["**/*.ts", "**/*.tsx", "**/*.spec.ts"]
}

@restrictions {
  - "Never use any type - use unknown with type guards"
  - "Never use default exports - only named exports"
  - "Never commit without tests"
  - "Never skip error handling"
}

@shortcuts {
  "/review": "Review code for quality and best practices"
  "/test": "Write comprehensive unit tests"
  "/docs": "Generate documentation"

  "/deploy": {
    prompt: true
    description: "Deploy to production"
    content: """
      Deploy to production:
      1. Build the project
      2. Run tests
      3. Deploy to staging
      4. Run smoke tests
      5. Deploy to production
    """
  }
}

# ============================================================ 
# Skills - Reusable AI Capabilities
# ============================================================ 

@skills {
  commit: {
    description: "Create git commits following project conventions"
    disableModelInvocation: true
    context: "fork"
    agent: "general-purpose"
    allowedTools: ["Bash", "Read", "Write"]
    content: """
      When creating commits:
      1. Use Conventional Commits format: type(scope): description
      2. Types: feat, fix, docs, style, refactor, test, chore
      3. Keep subject line under 72 characters
      4. Include Co-Authored-By trailer for AI assistance
      5. Never amend existing commits unless explicitly asked
      6. Always run linting before committing
    """
  }

  review: {
    description: "Review code changes for quality and issues"
    userInvocable: true
    content: """
      Perform thorough code review checking:

      ## Code Quality
      - Type safety and proper TypeScript usage
      - Error handling completeness
      - Edge case coverage

      ## Security
      - Input validation
      - No secrets in code
      - OWASP top 10 vulnerabilities

      ## Best Practices
      - SOLID principles adherence
      - DRY and KISS principles
      - Proper naming conventions

      ## Performance
      - Unnecessary re-renders in React
      - N+1 query problems
      - Memory leaks
    """
  }

  test: {
    description: "Write comprehensive unit tests"
    userInvocable: true
    content: """
      When writing tests:
      1. Use Vitest as the test runner
      2. Follow AAA pattern (Arrange, Act, Assert)
      3. Test both happy path and error cases
      4. Mock external dependencies
      5. Target >90% code coverage
      6. Use descriptive test names
    """
  }

  refactor: {
    description: "Suggest and implement code refactoring"
    context: "inherit"
    content: """
      When refactoring:
      1. Ensure tests pass before and after
      2. Make small, incremental changes
      3. Keep commits atomic
      4. Document breaking changes
    """
  }
}

# ============================================================ 
# Agents - Specialized AI Subagents (GitHub Copilot & Claude Code) 

```

--------------------------------

### extractSkillExamples()

Source: https://getpromptscript.dev/latest/api-reference/formatters/src/classes/ZencoderFormatter?q=

Extracts examples from a skill's nested examples property. This method returns data in the same format as `extractExamples()`.

```APIDOC
## extractSkillExamples()

### Description
Extracts examples from a skill's nested examples property. This method returns data in the same format as `extractExamples()`.

### Method
protected

### Signature
extractSkillExamples(skillProps: Record<string, Value>): object[]

### Parameters
#### skillProps
- **skillProps** (Record<string, Value>) - The properties of the skill containing nested examples.
```

--------------------------------

### Create and Use VendorRegistry

Source: https://getpromptscript.dev/latest/api-reference/resolver/src/functions/createVendorRegistry

Demonstrates how to create a VendorRegistry using a directory path and fetch a PromptScript file.

```typescript
import { createVendorRegistry } from '@promptscript/resolver';

const vendor = createVendorRegistry('/project/.promptscript/vendor');
const content = await vendor.fetch('@company/base.prs');

```

--------------------------------

### Initialize a New Registry

Source: https://getpromptscript.dev/latest/guides/registry?q=

Use this command to scaffold a new PromptScript registry with starter configurations. This sets up the basic structure for your organization's reusable configurations.

```bash
prs registry init my-company-registry

```

--------------------------------

### extractSkillExamples()

Source: https://getpromptscript.dev/latest/api-reference/formatters/src/classes/MarkdownInstructionFormatter

Extracts examples from a skill's nested examples property. Returns the same shape as extractExamples. Inherited from BaseFormatter.

```APIDOC
## extractSkillExamples()

### Description
Extracts examples from a skill's nested examples property. The returned structure is identical to that of `extractExamples`.

### Parameters
#### skillProps
- `Record<string, Value>`: An object containing skill properties, including nested examples.

### Returns
- `object[]`: An array of example objects.

### Inherited from
`BaseFormatter`.`extractSkillExamples`
```

--------------------------------

### createServer

Source: https://getpromptscript.dev/latest/api-reference/server/src

Initializes and configures a new PromptScript server instance. This function sets up the core server components based on provided configuration.

```APIDOC
## createServer

### Description
Initializes and configures a new PromptScript server instance.

### Function Signature
createServer(options: ServerOptions): Server

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **options** (ServerOptions) - Required - Configuration options for the server, including port, host, and other server settings.

### Response
#### Success Response
* **Server** - An object representing the created server instance.

### Example
```javascript
const server = createServer({ port: 8080, host: 'localhost' });
```
```

--------------------------------

### Default skill installation location

Source: https://getpromptscript.dev/latest/guides/npx-skills

By default, `npx skills add` installs skills into the `.agents/skills/` directory. PromptScript automatically discovers this directory.

```bash
# Default install location (no --dir flag)
npx skills add anthropics/skills --skill commit
# Installs to .agents/skills/commit/SKILL.md

```