Registry¶

PromptScript supports registries - collections of reusable configurations that can be inherited across projects. The official registry contains 1,134 configurations, but you can also create your own.

Official Registry¶

Repository: github.com/mrwogu/promptscript-registry

The official registry includes:

Quick Start¶

1. Configure Registry¶

Add to your promptscript.yaml:

registry:
  git:
    url: https://github.com/mrwogu/promptscript-registry.git
    ref: main # Or pin to version: v1.0.0

2. Inherit Configurations¶

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

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

3. Compile¶

prs compile  # Automatically fetches registry and generates output

Note: When using a Git registry, the CLI automatically clones and caches the repository. You don't need to run prs pull separately - the compile and validate commands handle this automatically.

The registry is cached at ~/.promptscript/.cache/git/ with a default TTL of 1 hour. Use prs pull --refresh to force an update.

Using prs init¶

The prs init command can automatically suggest configurations:

prs init

It will:

1. Detect your tech stack (React, Node, Python, etc.)
2. Offer to connect to the official registry
3. Suggest relevant configurations
4. Generate your promptscript.yaml and .promptscript/project.prs

Available Configurations¶

Tech Stacks (@stacks/)¶

Roles (@roles/)¶

Fragments (@fragments/)¶

Core mixins:

Categorized fragments:

Prompts (@prompts/)¶

632 general-purpose prompts organized by category:

Usage Patterns¶

Pattern 1: Inherit a Tech Stack¶

@meta { id: "react-app" syntax: "1.0.0" }

@inherit @stacks/react

Pattern 2: Mix in Fragments¶

@meta { id: "secure-app" syntax: "1.0.0" }

@inherit @stacks/node
@use @fragments/testing
@use @fragments/security/owasp-security-review

Pattern 3: Use Prompts Directly¶

@meta { id: "terminal" syntax: "1.0.0" }

@inherit @prompts/coding/linux-terminal

How Git Registry Resolution Works¶

When you configure a Git registry, the CLI handles everything automatically:

1. On first use: The registry is cloned to ~/.promptscript/.cache/git/<hash>/
2. On subsequent uses: The cached version is used if not stale (default: 1 hour TTL)
3. On cache expiry: The registry is updated with git fetch

prs init --yes
    ↓
Creates config with registry.git.url

prs compile
    ↓
resolveRegistryPath() → checks cache validity
    ↓
If stale/missing: GitRegistry.fetch() → clone/update
    ↓
Compiler uses cached registry path

Cache Configuration¶

Control caching behavior in promptscript.yaml:

registry:
  git:
    url: https://github.com/mrwogu/promptscript-registry.git
    ref: main
  cache:
    enabled: true # Set to false to always fetch
    ttl: 3600000 # Cache TTL in ms (default: 1 hour)

Force Refresh¶

prs pull --refresh  # Force re-clone the registry

Version Pinning¶

Pin to a specific version for stability:

registry:
  git:
    ref: v1.0.0

Or in .prs files:

@inherit @stacks/react@1.0.0

Creating Custom Registries¶

You can create your own registry for your organization.

Registry Structure¶

my-registry/
├── registry-manifest.yaml    # Catalog of all configurations
├── @core/
│   └── base.prs
├── @roles/
│   └── developer/
│       └── fullstack.prs
├── @stacks/
│   └── react.prs
└── @fragments/
    └── testing.prs

Registry Manifest¶

The registry-manifest.yaml file catalogs all configurations and enables prs init suggestions:

version: '1'

meta:
  name: 'My Company Registry'
  description: 'Internal AI instruction configurations'
  lastUpdated: '2025-01-28'

namespaces:
  '@core':
    description: 'Universal foundations'
    priority: 100
  '@roles':
    description: 'AI personas'
    priority: 90
  '@stacks':
    description: 'Tech stack configurations'
    priority: 80
  '@fragments':
    description: 'Reusable mixins'
    priority: 70

catalog:
  - id: '@core/base'
    path: '@core/base.prs'
    name: 'Base Foundation'
    description: 'Universal AI assistant foundation'
    tags: [core, foundation]
    targets: [github, claude, cursor]
    dependencies: []
    detectionHints:
      always: true

  - id: '@stacks/react'
    path: '@stacks/react.prs'
    name: 'React Stack'
    description: 'React + TypeScript configuration'
    tags: [react, typescript, frontend]
    targets: [github, claude, cursor]
    dependencies: ['@core/base']
    detectionHints:
      dependencies: ['react', 'react-dom']
      frameworks: ['react', 'nextjs']

suggestionRules:
  - condition: { always: true }
    suggest: { inherit: '@core/base' }
  - condition: { frameworks: ['react'] }
    suggest: { inherit: '@stacks/react', use: ['@fragments/testing'] }

Manifest Fields¶

catalog Entry Fields¶

detectionHints Fields¶

Using Your Registry¶

Git Registry¶

Host on GitHub, GitLab, or any Git provider:

registry:
  git:
    url: https://github.com/your-org/your-registry.git
    ref: main

Local Registry¶

For development or air-gapped environments:

registry:
  path: ./path/to/registry

Verification Scripts¶

Add these to your registry's package.json:

{
  "scripts": {
    "verify": "node scripts/verify-manifest.js",
    "rebuild": "node scripts/rebuild-catalog.js"
  }
}

verify-manifest.js - Checks all .prs files are in the catalog:

// Scan all .prs files and compare against catalog
// Exit with error if any files are missing

rebuild-catalog.js - Regenerates catalog from files:

// Parse all .prs files and extract @meta information
// Update registry-manifest.yaml with new entries

See the official registry scripts for reference implementations.

CI/CD Integration¶

Add manifest verification to your CI pipeline:

# .github/workflows/verify-manifest.yml
name: Verify Manifest
on: [push, pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run verify

Contributing to Official Registry¶

1. Fork promptscript-registry
2. Add your .prs file in the appropriate namespace
3. Ensure @meta.id matches the file path
4. Run npm run rebuild to update the catalog
5. Submit a pull request

See the contributing guide for details.