### Setup PromptScript Repository

Source: https://github.com/mrwogu/promptscript/blob/main/CONTRIBUTING.md

Steps to clone the repository, install dependencies, and verify the setup.

```bash
git clone https://github.com/mrwogu/promptscript.git
cd promptscript

pnpm install

nx run-many -t test
```

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

### Install Community Plugin

Source: https://github.com/mrwogu/promptscript/blob/main/ROADMAP.md

Example of how to install a community-provided plugin for PromptScript.

```bash
prs plugin install @community/windsurf-formatter
```

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

### Complete Multi-File Project Setup Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/multi-file.md

Demonstrates a comprehensive multi-file project structure, including the main entry file (`project.prs`) and its configuration (`promptscript.yaml`). This setup allows for modularity and organization of complex projects.

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

# Inherit team base configuration
@inherit @team/base

# Import project fragments
@use ./fragments/security
@use ./fragments/testing
@use ./fragments/api-standards
@use ./fragments/documentation

@identity {
  """
  You are a senior full-stack developer working on My Project.
  You follow team conventions and project-specific patterns.
  """
}

@context {
  project: "My Project"
  team: "Platform"

  """
  A microservices-based platform for data processing.

  Tech Stack:
  - Backend: Node.js, TypeScript, NestJS
  - Frontend: React, TypeScript, Vite
  - Database: PostgreSQL, Redis
  - Infrastructure: Kubernetes, AWS
  """
}

@shortcuts {
  "/start": "Initialize development environment"
  "/deploy": "Deploy to staging environment"
}
```

```yaml
version: '1'

project:
  id: my-project
  team: platform

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

registry:
  path: ./registry

targets:
  - github
  - claude
  - cursor
```

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

### Defining Examples with @meta and @examples

Source: https://github.com/mrwogu/promptscript/blob/main/packages/cli/skills/promptscript/SKILL.md

Use @meta to define syntax version and @examples to provide structured few-shot examples for AI assistants. Each example requires 'input' and 'output'.

```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"
  }
}
```

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

### Basic @examples Syntax

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/examples.md

Define top-level examples with named entries, each containing 'input' and 'output' fields.

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

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

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

### User Configuration File Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/user-config.md

This is an example of the `~/.promptscript/config.yaml` file, showing how to set default registry and initialization options.

```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
```

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

### Install and Run PromptScript CLI

Source: https://github.com/mrwogu/promptscript/blob/main/README.md

Installs the PromptScript CLI globally and provides commands to initialize a project, compile configurations, and install hooks.

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

prs init             # auto-detects your tech stack
prs compile          # outputs to all AI tools
prs hooks install --all  # auto-recompile on save, block AI from overwriting outputs
```

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

### Full PromptScript Configuration Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/reference/config.md

This is a complete example of a promptscript.yaml file, showcasing all available configuration options across different sections.

```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)
uniqueversalDir: 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

```

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

### Install pre-commit hooks

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/ci.md

Install the pre-commit framework and enable the git hooks for your repository.

```bash
pip install pre-commit
pre-commit install
```

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

### PromptScript Configuration Example

Source: https://github.com/mrwogu/promptscript/blob/main/packages/cli/README.md

An example of the `promptscript.yaml` file used for project configuration, specifying version, input entry point, and compilation targets.

```yaml
version: '1'
input:
  entry: '.promptscript/project.prs'
targets:
  - github
  - claude
  - cursor
```

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

### Cursor Command Output Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/reference/language.md

This example shows how a multi-line shortcut is processed to create a command file in Cursor.

```markdown
Write unit tests using: - Vitest as the test runner - AAA pattern (Arrange, Act, Assert)
```

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

### PromptScript Configuration Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/enterprise.md

Example of a promptscript.yaml file showing registry and target configurations. Use Git tags for production stability.

```yaml
input:
  entry: .promptscript/project.prs

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

targets:
  github:
    enabled: true
    output: .github/copilot-instructions.md
  claude:
    enabled: true
    output: CLAUDE.md
  cursor:
    enabled: true
    output: .cursor/rules/project.mdc

validation:
  strict: true
```

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

### Project Installation and Testing Commands

Source: https://github.com/mrwogu/promptscript/blob/main/packages/importer/src/__tests__/fixtures/sample-claude.md

Commands for installing project dependencies, running tests, and building the project using pnpm.

```bash
pnpm install
pnpm test
pnpm build
```

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

### PromptScript Configuration Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/examples/skills-and-local.md

Example of a promptscript.yaml configuration file specifying input entry and targets for different AI models.

```yaml
# promptscript.yaml
version: '1'

input:
  entry: .promptscript/project.prs

targets:
  # GitHub Copilot with full features (skills + custom agents)
  - github:
      version: full
      convention: markdown

  # Claude Code with full features (skills + agents + local memory)
  - claude:
      version: full
      convention: markdown

  # Cursor with multifile rules
  - cursor:
      version: multifile

```

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

### Install PromptScript CLI with yarn

Source: https://github.com/mrwogu/promptscript/blob/main/docs/getting-started.md

Install the PromptScript CLI toolchain globally using yarn.

```bash
yarn global add @promptscript/cli
```

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

### PromptScript Configuration File Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/reference/cli.md

This is an example of a PromptScript configuration file, showing settings for input, registry, output targets, validation, and watch options.

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

# Registry configuration
registry:
  path: ./registry
  # Or remote URL
  # url: https://github.com/org/registry

# Output targets
targets:
  github:
    enabled: true
    output: .github/copilot-instructions.md

  claude:
    enabled: true
    output: CLAUDE.md

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

  antigravity:
    enabled: true
    output: .agent/rules/project.md

# Validation settings
validation:
  strict: false
  ignoreWarnings: []

# Watch settings
watch:
  include:
    - '.promptscript/**/*.prs'
  exclude:
    - '**/node_modules/**'
```

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

### Install Skill via npx skills

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/building-skills.md

Install a skill from a GitHub repository using the `npx skills add` command. Specify the skill name and the local directory for installation.

```bash
npx skills add your-org/your-skills \
  --skill my-skill \
  --dir .promptscript/skills
```

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

### Define Structured Examples for AI

Source: https://github.com/mrwogu/promptscript/blob/main/docs/reference/language.md

Use the @examples block to define structured few-shot examples for AI assistants, specifying input, output, and optional descriptions. Requires syntax version 1.2.0 or higher.

```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);
    """
  }
}
```

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

### PromptScript Migration Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/getting-started.md

This example shows the transformation of a CLAUDE.md file before migration to its PromptScript equivalent (.promptscript/project.prs) after 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
```

```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 Output Structure

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/examples.md

This markdown illustrates the compiled output generated from the @examples directive, showing a dedicated Examples section with input and output code blocks.

```markdown
## Examples

### camel-case

Variable naming convention

**Input:**
```

const user_name = 'Alice'

```

**Output:**

```

const userName = 'Alice'

```
```

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

### Install PromptScript CLI

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/faq.md

Install the PromptScript command-line interface globally using npm.

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

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

### Install Project Dependencies

Source: https://github.com/mrwogu/promptscript/blob/main/packages/formatters/src/__tests__/__golden__/factory/simple.md

Installs all necessary dependencies for the project using pnpm.

```bash
pnpm install
```

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

### Install a skill to the default directory

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/npx-skills.md

Install a skill using the default `.agents/skills/` directory by omitting the `--dir` flag.

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

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

### Install PromptScript CLI with pnpm

Source: https://github.com/mrwogu/promptscript/blob/main/docs/getting-started.md

Install the PromptScript CLI toolchain globally using pnpm.

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

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

### Install a community skill

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/npx-skills.md

Install a skill from any GitHub repository containing skill directories by specifying the repository and skill name.

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

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

### Complete Inheritance Example: Template and Project

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/inheritance.md

Demonstrates a complete example of parameterized inheritance, showing a React app template and a child project inheriting and providing specific parameters.

```promptscript
# @stacks/react-app.prs
@meta {
  id: "@stacks/react-app"
  syntax: "1.0.0"
  params: {
    projectName: string
    port: number = 3000
    strict: boolean = true
  }
}

@identity {
  """
  You are a React developer working on {{projectName}}.
  """
}

@context {
  project: {{projectName}}
  devServer: "http://localhost:{{port}}"
  strictMode: {{strict}}
}

@standards {
  code: ["TypeScript strict mode enabled"]
}
```

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

@inherit @stacks/react-app(projectName: "Checkout App", port: 8080)

@identity {
  """
  You specialize in e-commerce checkout flows.
  """
}
```

```markdown
## Identity

You are a React developer working on Checkout App.

You specialize in e-commerce checkout flows.

## Context

- project: Checkout App
- devServer: http://localhost:8080
- strictMode: true

## Standards

### Code
- TypeScript strict mode enabled
```

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

### Start Playground Development Server

Source: https://github.com/mrwogu/promptscript/blob/main/packages/playground/README.md

Starts the development server for the playground package using pnpm and Nx. This command is used for local development and testing.

```bash
pnpm nx dev playground
```

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

### Directory Import Resolution Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/design/2026-03-26-markdown-imports-design.md

Provides an example of how the resolver identifies individual skills within a directory based on SKILL.md and <dirname>.md conventions.

```promptscript
# Resolver finds:
#   gitnexus/exploring/SKILL.md    → skill "exploring"
#   gitnexus/debugging/SKILL.md    → skill "debugging"
#   gitnexus/refactoring/SKILL.md  → skill "refactoring"
#   gitnexus/impact/SKILL.md       → skill "impact"
```

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

### Fragment File Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/inheritance.md

Reusable fragments can be defined in separate files and imported using @use. This example shows a testing fragment with standards and shortcuts.

```promptscript
# @fragments/testing.prs
@meta {
  id: "@fragments/testing"
  syntax: "1.0.0"
}

@standards {
  testing: ["Use vitest as test framework", "Maintain 80% code coverage", "Write unit and integration tests"]
}

@shortcuts {
  "/test": "Write comprehensive tests"
  "/coverage": "Check test coverage"
}
```

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

### Commit Installed Skills to Git

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/npx-skills.md

Commit installed skills to your Git repository as they are part of your project's AI configuration. This ensures your skill setup is versioned.

```bash
git add .promptscript/skills/
git commit -m "feat: add frontend-design and commit skills"
```

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

### Install Skills using npx openskills

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/local-skills.md

Shows how to use the OpenSkills CLI to install skills into your project's local skills directory, providing a universal way to manage skills.

```bash
# Install a skill
npx openskills install frontend-design \
  --dir .promptscript/skills
```

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

### CI Configuration with GITHUB_TOKEN

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/registry.md

Example CI environment variable setup for providing a GitHub token during compilation.

```yaml
# .github/workflows/promptscript.yml
- name: Compile
  run: prs compile
  env:
    GITHUB_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
```

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

### prs init Command Examples

Source: https://github.com/mrwogu/promptscript/blob/main/docs/design/2026-03-20-intelligent-init-design.md

Demonstrates various ways to use the 'prs init' command, including interactive, non-interactive, and migration-focused modes.

```bash
prs init                          # Interactive — gateway choice if files detected
prs init -y                       # Non-interactive, safe defaults, skip migration
prs init -y --auto-import         # Non-interactive + static import of detected files
prs init -i                       # Force interactive even with all args provided
prs init -f                       # Force reinitialize
prs init --backup                 # Create .prs-backup/
prs init -m, --migrate            # DEPRECATED → deprecation notice, installs skill
```

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

### GitLab CI/CD Integration

Source: https://github.com/mrwogu/promptscript/blob/main/docs/examples/git-registry.md

Example GitLab CI configuration to install PromptScript CLI, 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
```

```yaml
variables:
  GITLAB_TOKEN: $CI_JOB_TOKEN
```

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

### Enterprise Policy Configuration

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/policy-engine.md

An example of configuring policies for a three-layer enterprise setup, including layer governance, core immutability, and approved sources.

```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']
```

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

### Example `project.prs` with `@use` Directives

Source: https://github.com/mrwogu/promptscript/blob/main/docs/design/2026-03-20-intelligent-init-design.md

Demonstrates the main `project.prs` file structure, showcasing how `@use` directives import content from other modular .prs files and include the project's identity.

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

@use ./context
@use ./standards
@use ./restrictions
@use ./commands

@identity {
  """
  [merged identity from primary source]
  """
}
```

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

### GitHub Actions CI/CD Integration

Source: https://github.com/mrwogu/promptscript/blob/main/docs/examples/git-registry.md

Example GitHub Actions workflow to install PromptScript CLI, pull registry updates, compile, and check 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
          }
```

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

### Project Structure Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/examples/skills-and-local.md

Illustrates a typical project structure including the PromptScript configuration file and gitignore.

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

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

### Azure Pipeline: Basic CI Setup

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/ci.md

A basic Azure pipeline to set up Node.js, install the PromptScript CLI, validate, compile, and check for drift in PromptScript files. This pipeline triggers on changes to specific directories and branches.

```yaml
trigger:
  branches:
    include:
      - main
  paths:
    include:
      - .promptscript/**
      - promptscript.yaml

pr:
  branches:
    include:
      - main
  paths:
    include:
      - .promptscript/**
      - promptscript.yaml

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
    displayName: 'Setup Node.js'

  - script: npm install -g @promptscript/cli
    displayName: 'Install PromptScript CLI'

  - script: prs validate --strict
    displayName: 'Validate PromptScript files'

  - script: prs compile
    displayName: 'Compile PromptScript'

  - script: |
      if ! git diff --quiet; then
        echo "##vso[task.logissue type=error]Compiled files are out of sync"
        git diff --stat
        exit 1
      fi
    displayName: 'Check for drift'
```

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

### TSDoc with Example

Source: https://github.com/mrwogu/promptscript/blob/main/CONTRIBUTING.md

Example of TSDoc documentation for a public function, including parameters, return value, exceptions, and a usage example.

```typescript
/**
 * Parses a PromptScript path reference.
 *
 * @param path - The path string (e.g., "@core/guards/compliance@1.0.0")
 * @returns Parsed path object
 * @throws {ParseError} If path format is invalid
 *
 * @example
 * ```typescript
 * const parsed = parsePath('@core/org');
 * // { namespace: 'core', segments: ['org'], version: undefined }
 * ```
 */
export function parsePath(path: string): ParsedPath {
  // ...
}
```

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

### Initialize PromptScript Project

Source: https://github.com/mrwogu/promptscript/blob/main/docs/examples/minimal.md

Use this command to initialize a new PromptScript project from scratch.

```bash
prs init
```

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

### Install a skill using OpenSkills

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/npx-skills.md

Use the `openskills` installer to install skills, specifying the skill name and target directory.

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

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

### Start local development server

Source: https://github.com/mrwogu/promptscript/blob/main/docs/reference/cli.md

Use 'prs serve' to launch a local development server. This connects the online playground to your local .prs files, enabling real-time synchronization.

```bash
prs serve
```

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

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

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

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

### Multiple Examples in a Block

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/examples.md

Define multiple named examples within a single @examples block. Names must be unique within the block.

```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; }"
  }
}
```

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

### PromptScript Configuration Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/index.md

A basic PromptScript configuration file demonstrating metadata, inheritance, and identity settings.

```promptscript
@meta { id: "my-project" syntax: "1.0.0" }
@inherit @company/standards
@identity { """You are an expert developer.""" }

```

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

### Defining @examples in PromptScript

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/examples.md

This snippet shows the structure for defining examples using the @examples directive, including metadata and input/output pairs for variable naming conventions.

```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'"
  }
}
```

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

### Initialize PromptScript in Repository

Source: https://github.com/mrwogu/promptscript/blob/main/CONTRIBUTING.md

Command to set up PromptScript project configuration and AI instructions files within the repository.

```bash
pnpm prs init
```

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

### Examples Inside @skills

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/examples.md

Attach examples directly to a skill definition to keep them co-located with the skill they demonstrate. Skill-level examples appear in the skill's output file.

```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"
    """
  }
}
```

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

### Install Skills using npx skills (Skills.sh)

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/local-skills.md

Demonstrates how to use the 'skills' CLI to list, install, and manage skills from GitHub repositories directly into your project's local skills directory.

```bash
# 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
```

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

### Attaching Examples to Skills

Source: https://github.com/mrwogu/promptscript/blob/main/packages/cli/skills/promptscript/SKILL.md

Examples can be directly attached to skills using the 'examples' property within the @skills directive. This associates specific input/output pairs with a skill's functionality.

```promptscript
@skills {
  commit: {
    description: "Create conventional commits"
    examples: {
      basic: {
        input: "Added dark mode toggle"
        output: "feat(settings): add dark mode toggle"
      }
    }
    content: (triple-quoted text)
  }
}
```

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

### PromptScript Configuration File

Source: https://github.com/mrwogu/promptscript/blob/main/README.md

Example of the promptscript.yaml file, showing how to configure registry aliases for importing standards.

```yaml
registries:
  '@company': github.com/acme/promptscript-base
```

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

### Verify PromptScript Installation

Source: https://github.com/mrwogu/promptscript/blob/main/docs/getting-started.md

Verify that the PromptScript CLI has been installed correctly by checking its version.

```bash
prs --version
```

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

### Full non-interactive PromptScript project setup

Source: https://github.com/mrwogu/promptscript/blob/main/docs/reference/cli.md

Perform a complete non-interactive initialization by specifying project name, inheritance, and targets.

```bash
prs init -n my-project --inherit @company/team --targets github claude cursor
```

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

### Initialize Company Registry

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/enterprise.md

Use the CLI to scaffold your company registry with specified name and namespaces.

```bash
prs registry init company-registry --name "ACME Registry" --namespaces @org @teams @fragments @templates
```

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

### Mermaid Diagram Example

Source: https://github.com/mrwogu/promptscript/blob/main/packages/formatters/src/__tests__/__golden__/antigravity/frontmatter.md

Example of how to embed a Mermaid flowchart diagram within markdown documentation.

```mermaid
flowchart LR
    A[Input] --> B[Process] --> C[Output]
```

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

### Initialize a New Registry

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/registry.md

Use this command to scaffold a new registry with starter configurations. See Creating a Registry for more details.

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

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

### Example GitHub Copilot Skill File

Source: https://github.com/mrwogu/promptscript/blob/main/docs/examples/skills-and-local.md

Demonstrates the structure of a skill file for GitHub Copilot, including name, description, and invocation settings.

```markdown
---
name: "commit"
description: "Create git commits following project conventions"
disable-model-invocation: true
---

When creating commits:

1. Use Conventional Commits format: type(scope): description
2. Types: feat, fix, docs, style, refactor, test, chore
   ...

```

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

### Importing All Skills from a Directory

Source: https://github.com/mrwogu/promptscript/blob/main/docs/design/2026-03-26-markdown-imports-design.md

Demonstrates how to import all skills contained within a specified directory, including aliasing and parameterization.

```promptscript
# Import all skills from a directory
@use github.com/repo/skills/gitnexus
@use ./external/skills/gitnexus

# Aliases and parameters still work
@use github.com/repo/skills/gitnexus as gn
```

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

### Parity Matrix Example Entry

Source: https://github.com/mrwogu/promptscript/blob/main/docs/testing/parity-testing.md

An example entry in the parity matrix, detailing requirements and patterns for the 'restrictions' section.

```typescript
{
  id: 'restrictions',
  name: 'Restrictions',
  description: "Don'ts and forbidden practices",
  sources: [{ block: 'restrictions' }],
  requiredBy: ['github', 'cursor', 'claude', 'antigravity'],
  optionalFor: [],
  contentPatterns: [/never|don't|do not|avoid|forbidden/i],
  headerVariations: {
    github: "## Don'ts",
    cursor: 'Never:',
    claude: "## Don'ts",
    antigravity: "## Don'ts",
  },
}
```

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

### OpenCode Project Structure Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/reference/formatters/opencode.md

This example illustrates the typical directory and file structure generated by the OpenCode formatter. It shows the main instructions file and the organization of commands, skills, and agents within the .opencode directory.

```directory
project-root/
├── OPENCODE.md                        # Main instructions
└── .opencode/
    ├── commands/
    │   └── review.md                  # Command definition
    ├── skills/
    │   └── my-skill/
    │       └── SKILL.md               # Skill definition
    └── agents/
        └── reviewer.md               # Agent config
```

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

### SKILL.md Frontmatter Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/building-skills.md

Example of the YAML frontmatter in a SKILL.md file, defining the skill's name and description.

```yaml
# SKILL.md frontmatter
name: ui-design
description: UI design with searchable databases
```

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

### Policy Configuration Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/policy-engine.md

Define various policies including layer boundaries, property protection, and registry allowlists in the `promptscript.yaml` file.

```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']
```

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

### Adding Descriptions to Examples

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/examples.md

Use the optional 'description' field to provide a human-readable label for each example, clarifying its purpose.

```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"
  }
}
```

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

### Run PromptScript CLI without Installation

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/faq.md

Execute PromptScript commands using npx without a global installation.

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

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

### Example Output for Adding a Skill

Source: https://github.com/mrwogu/promptscript/blob/main/docs/design/2026-03-26-markdown-imports-design.md

Shows the confirmation messages and the added @use directive when a skill is successfully added.

```bash
$ prs skills add github.com/anthropics/skills/frontend-design@1.0.0


vim.png✓ Resolved frontend-design@1.0.0 (commit a1b2c3d)
✓ Added @use to project.prs
✓ Updated promptscript.lock

Added to project.prs:
  @use github.com/anthropics/skills/frontend-design@1.0.0
```

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

### Mermaid Diagram Example

Source: https://github.com/mrwogu/promptscript/blob/main/packages/formatters/src/__tests__/__golden__/antigravity.md

Example of a simple flowchart diagram using Mermaid syntax, wrapped in a markdown code block.

```mermaid
flowchart LR
  A[Input] --> B[Process] --> C[Output]
```

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

### Initialize PromptScript project with defaults

Source: https://github.com/mrwogu/promptscript/blob/main/docs/reference/cli.md

Use the '-y' or '--yes' flag to skip interactive prompts and use default settings for initialization.

```bash
prs init -y
```

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

### Layer-Level Output Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/superpowers/specs/2026-04-03-prs-inspect-layers-design.md

Example of the `--layers` output format for `prs inspect`, detailing changes made by each layer.

```text
Skill: code-review (3 layers)

Layer 1 — @company/code-review.prs (base)
  + description: "Standard code review"
  + content: (247 lines)
  + references: [company-standards.md]
  + requires: [lint-check]
  + sealed: ["content"]

Layer 2 — @product/code-review.prs (@extend)
  ~ description: replaced → "Product review"
  + references: [product-patterns.md]

Layer 3 — @bu/code-review.prs (@extend)
  - references: [product-patterns.md] (negated)
  + references: [bu-arch.md, bu-modules.md]
  + requires: [security-scan]
```

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

### Property-Level Output Example

Source: https://github.com/mrwogu/promptscript/blob/main/docs/superpowers/specs/2026-04-03-prs-inspect-layers-design.md

Example of the default output format for `prs inspect`, showing property provenance and merge strategies.

```text
Skill: code-review

  description    "Product review"           [replace]  ← @product/code-review.prs
  content        (247 lines)                [sealed]   ← @company/code-review.prs
  references     3 files                    [append]   ← @company + @bu
  requires       ["lint-check", "scan"]     [append]   ← @company + @bu
  sealed         ["content"]                           ← @company/code-review.prs
```

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

### URL Import Example in PromptScript

Source: https://github.com/mrwogu/promptscript/blob/main/docs/examples/git-registry.md

Shows how to directly import PromptScript components using their full URLs without requiring alias configuration. This is useful for referencing external components or specific versions.

```promptscript
@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
```

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

### Importing Fragments and Registry Modules

Source: https://github.com/mrwogu/promptscript/blob/main/docs/guides/multi-file.md

Demonstrates importing local fragments and modules from a registry. Aliases can be used for selective extension.

```promptscript
@use ./fragments/security

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

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

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

### Frontend Team Setup Commands

Source: https://github.com/mrwogu/promptscript/blob/main/docs/__snapshots__/docs/examples/team-setup.md/@team/frontend_L35/claude.md

These commands are available for generating new code artifacts and performing code reviews. Use them to maintain consistency and efficiency in development.

```bash
/component - Create a new React component with tests
/hook      - Create a custom React hook
/test      - Write tests using Vitest and Testing Library
/a11y      - Review code for accessibility
```