# Build Your Registry

PromptScript supports registries - collections of reusable configurations that can be inherited across projects. Each organization creates and manages their own registry, giving full control over AI instruction standards.

## Quick Start

This walkthrough runs end to end from an empty directory. You create a registry, publish it to a Git host, bind a project to it, and compile - every snippet is a command you can run.

### 1. Create a Registry

```bash
prs registry init my-registry --yes --name "My Company Registry" --namespaces @core @stacks @fragments
```

This scaffolds the directory, manifest, and three starter configurations in `@core`:

```text
my-registry/
├── registry-manifest.yaml
├── README.md
├── @core/
│   ├── base.prs        # universal AI assistant foundation
│   ├── quality.prs    # code quality standards mixin
│   └── security.prs    # security best practices mixin
├── @stacks/           # empty, add stack configs here
└── @fragments/        # empty, add mixins here
```

Check it before publishing:

```bash
prs registry validate ./my-registry
```

See [Creating a Registry](#creating-a-registry) for the interactive mode and other options.

### 2. Publish the Registry

`prs registry init` does not create a Git repository, so the registry is not reachable from any project yet. Put it under version control and push it to your Git host:

```bash
cd my-registry
git init -b main
git add .
git commit -m "feat: initial registry"
git remote add origin https://github.com/your-org/my-registry.git  # replace your-org with your GitHub org or user
git push -u origin main
```

From now on, `prs registry publish` re-publishes registry updates - it validates, commits, and pushes in one step (see [Publishing a Registry](#publishing-a-registry)).

### 3. Bind Your Project

Return to the starting directory and create a project:

```bash
cd ..
mkdir my-project
cd my-project
mkdir -p .promptscript
```

In your project root, point `promptscript.yaml` at the registry you just pushed and pick compile targets:

```yaml
# promptscript.yaml
registry:
  git:
    url: https://github.com/your-org/my-registry.git # same URL you pushed to above
    ref: main # Or pin to version: v1.0.0

targets:
  - github # compiles .github/copilot-instructions.md - pick your tools here
```

No Git host handy? A local registry works for the rest of this walkthrough - skip the push and configure `registry: { path: ../my-registry }` instead.

### 4. Use Registry Configurations

Reference configurations by their namespace and file name. The starter registry already ships `@core/quality`, so this resolves out of the box:

```promptscript
# .promptscript/project.prs
@meta {
  id: "my-project"
  syntax: "1.5.0"
}

@use @core/quality
@use @core/security
```

<!-- playground-link-start -->
<a href="https://getpromptscript.dev/playground/?s=N4IgZglgNgpgziAXAbVABwIYBcAWSQwAeGAtmrAHRoBOCANCAMYD2AdljO-gMQAEV1ZmSxxG1CGiwB6GswBWMRlgFwAOqwACJGFgy9g63rwgATRL1UgSATwC0shUsuHeca+wyFzlgIwUArBQADM6sAL7q6hoArnAwvBos1DBSAI7RGFAQWNZRsfGJzMlScYzR4jkgYQC6DJxY1Nb4RKTkMCogDABuMLQQbPg+VUA" target="_blank" rel="noopener noreferrer">
  <img src="https://img.shields.io/badge/Try_in-Playground-blue?style=flat-square" alt="Try in Playground" />
</a>
<!-- playground-link-end -->

### 5. Validate and Compile

```bash
prs validate  # resolves the registry, validates the project
prs compile   # fetches the registry, writes the compiled files
```

Expected output:

```text
- Loading configuration...
✔ Validation successful

- Compiling...
  ✓ .github/copilot-instructions.md
  ✓ .github/skills/promptscript/SKILL.md
  ✓ AGENTS.md
✔ Compilation successful
```

**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 connect to your registry and suggest configurations:

```bash
prs init
```

It will:

1. Detect your tech stack (React, Node, Python, etc.)
2. Offer to connect to a Git or local registry
3. Suggest relevant configurations from your registry's catalog
4. Generate your `promptscript.yaml` and `.promptscript/project.prs`

You can also set a default registry via [user-level config](https://getpromptscript.dev/guides/user-config/index.md) so `prs init --yes` automatically uses it.

### How Overlay-Aware Suggestions Work

When your registry catalogs Layer 2 / Layer 3 [skill overlays](https://getpromptscript.dev/guides/skill-overlays/index.md), `prs init` collapses overlay relationships before showing the picker so you don't see both the base skill and its overlay as separate choices.

Detection works two ways:

1. **Manifest `extends` field** — when a skill entry in `registry-manifest.yaml` declares `extends: <base-skill-id>`, the suggestion engine treats it as an overlay of that base.
2. **Inline `@extend` scan** — when no manifest hint exists, the engine scans the suggested skill's `.prs` source for `@use … as <alias>` plus `@extend <alias>.skills.<name>` and resolves the base skill via the alias map.

When an overlay is detected and **both** the overlay and its base were suggested, the base is removed from the choices. The overlay choice is annotated inline:

```text
? Select skills to add: (Use space to select, enter to confirm)
  ◉ @stacks/react (use)
  ◉ @skills/code-review (extends @skills/code-review-base) (skill)
  ◉ @skills/security-review (skill)
```

The `(extends …)` annotation makes it explicit which base the overlay is layering on top of, so reviewers can audit the chain at a glance. If your registry doesn't yet declare `extends`, populate the field in `registry-manifest.yaml` to get the cleanest experience:

```yaml
catalog:
  - id: '@skills/code-review-base'
    description: 'Generic code-review base skill'
  - id: '@skills/code-review'
    description: 'Org-specific code-review overlay (banking compliance)'
    extends: '@skills/code-review-base'
```

See [Skill Overlays](https://getpromptscript.dev/guides/skill-overlays/index.md) for the overlay model itself, and the [Registry Manifest](#registry-manifest) section below for the full schema.

## Usage Patterns

### Pattern 1: Inherit the Base

```promptscript
@meta { id: "base-project" syntax: "1.5.0" }

@inherit @core/base
```

<!-- playground-link-start -->
<a href="https://getpromptscript.dev/playground/?s=N4IgZglgNgpgziAXAbVABwIYBcAWSQwAeGAtmrAHRoBOCANCAMYD2AdljO-gAIkxYYABMEEQAJokEAdEACMMcGAFoazAFYxGWGYLgBPdhkKSZARgoBWCgAYdAXymtH3CKxwxqELIO4tqMAHp5RRA7AF0GTixqPXwiUnIYKloQBgA3DzgINnxTUKA" target="_blank" rel="noopener noreferrer">
  <img src="https://img.shields.io/badge/Try_in-Playground-blue?style=flat-square" alt="Try in Playground" />
</a>
<!-- playground-link-end -->

### Pattern 2: Mix in Shared Standards

```promptscript
@meta { id: "secure-project" syntax: "1.5.0" }

@inherit @core/base
@use @core/quality
@use @core/security
```

<!-- playground-link-start -->
<a href="https://getpromptscript.dev/playground/?s=N4IgZglgNgpgziAXAbVABwIYBcAWSQwAeGAtmrAHRoBOCANCAMYD2AdljO-gAIkxYYABMEEQAJokEAdEHBiMArtRgBaGswBW8rDMFwAnuwyFJMgIwUArBQAMugL5TWT7hFY4Y1CFkHcWygHoAIww5FwU5X38YAIBHBQwob31wyL9mQLlFLyx9EHsAXQZOLGo8xAJiMkoaehAAN084CDZ8M3ygA" target="_blank" rel="noopener noreferrer">
  <img src="https://img.shields.io/badge/Try_in-Playground-blue?style=flat-square" alt="Try in Playground" />
</a>
<!-- playground-link-end -->

### Pattern 3: Use a Mixin Directly

```promptscript
@meta { id: "security-review" syntax: "1.5.0" }

@use @core/security
```

<!-- playground-link-start -->
<a href="https://getpromptscript.dev/playground/?s=N4IgZglgNgpgziAXAbVABwIYBcAWSQwAeGAtmrAHRoBOCANCAMYD2AdljO-gAIkxYYABMEEQAJokEAdEHBiMArtQhYAngFpqMAG4QYAdxmC4q9hkKSZARgoBWCgAYjAXyms33BXMHcWWgPRyispqIM4AugycWNSq+ESk5DBUtCAM2jC0EGz4VmFAA" target="_blank" rel="noopener noreferrer">
  <img src="https://img.shields.io/badge/Try_in-Playground-blue?style=flat-square" alt="Try in Playground" />
</a>
<!-- playground-link-end -->

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

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

### Force Refresh

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

### Large Repositories and Timeouts

Every Git operation (clone, fetch, ls-remote) has a 60-second timeout by default.
Two knobs raise it when a registry lives in a big repository:

```yaml
# Per registry entry (registries aliases)
registries:
  '@internal':
    url: https://gitlab.internal.com/company/monorepo.git
    root: skills
    timeout: 600000 # 10 minutes, in milliseconds

# Or for the single git registry
registry:
  git:
    url: https://gitlab.internal.com/company/monorepo.git
    timeout: 600000
```

Globally, without touching config:

```bash
export PROMPTSCRIPT_GIT_TIMEOUT=600000
```

Timeout errors name both knobs in their message.

Registry imports also use partial sparse clones (`--depth 1 --filter=blob:none
--sparse` plus `sparse-checkout`), which materialize a reduced sparse subset
around the imported directory. A 73 MB monorepo where a full clone times out
usually resolves in about a second. If the server does not support partial
clones, PromptScript falls back to a plain shallow clone automatically.

## Version Pinning

Pin to a specific version for stability:

```yaml
registry:
  git:
    ref: v1.0.0
```

Or in `.prs` files:

```promptscript
@inherit @stacks/react@1.0.0
```

---

## Creating a Registry

Use the `prs registry init` command to scaffold a new registry:

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

This creates the full directory structure, manifest, and optional seed configurations.

### Interactive Mode

```bash
prs registry init my-registry
# Prompts for: name, description, namespaces, seed configs
```

### Non-Interactive Mode

```bash
prs registry init my-registry --yes --name "My Company Registry" --namespaces @core @stacks @fragments
```

### Skip Seed Configs

```bash
prs registry init my-registry --no-seed
```

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

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

| Field            | Required | Description                              |
| ---------------- | -------- | ---------------------------------------- |
| `id`             | Yes      | Unique ID matching file path             |
| `path`           | Yes      | Path to the `.prs` file                  |
| `name`           | Yes      | Human-readable name                      |
| `description`    | Yes      | Brief description                        |
| `tags`           | Yes      | Searchable tags                          |
| `targets`        | No       | Supported targets (github, claude, etc.) |
| `dependencies`   | No       | Required configurations                  |
| `detectionHints` | No       | Auto-suggestion hints (see below)        |

#### `detectionHints` Fields

| Field          | Description                                    |
| -------------- | ---------------------------------------------- |
| `always`       | Always suggest this configuration              |
| `files`        | Suggest if these files exist                   |
| `dependencies` | Suggest if package.json has these dependencies |
| `languages`    | Suggest for these languages                    |
| `frameworks`   | Suggest for these frameworks                   |

### Using Your Registry

#### Git Registry

Host on GitHub, GitLab, or any Git provider:

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

#### Local Registry

For development or air-gapped environments:

```yaml
registry:
  path: ./path/to/registry
```

### Validating a Registry

Use `prs registry validate` to check your registry structure:

```bash
prs registry validate ./my-registry
```

Validation checks:

- `registry-manifest.yaml` exists and parses correctly
- Manifest schema is valid (version, meta, namespaces, catalog)
- All catalog entry `.prs` files exist
- Catalog IDs match declared namespaces
- No circular dependencies
- Warns about orphaned `.prs` files not in catalog

Use `--strict` to treat warnings as errors:

```bash
prs registry validate ./my-registry --strict
```

Use `--format json` for machine-readable output:

```bash
prs registry validate ./my-registry --format json
```

### Publishing a Registry

Use `prs registry publish` to commit and push registry updates:

```bash
prs registry publish ./my-registry
```

This will:

1. Validate the registry (use `--force` to skip)
2. Update `meta.lastUpdated` in the manifest
3. Stage, commit, and push changes

Options:

```bash
prs registry publish ./my-registry --dry-run              # Preview without publishing
prs registry publish ./my-registry -m "Add React stack"    # Custom commit message
prs registry publish ./my-registry --tag v1.0.0            # Tag the release
prs registry publish ./my-registry --force                 # Skip validation
```

### CI/CD Integration

Add registry validation to your CI pipeline:

```yaml
# .github/workflows/registry.yml
name: Registry CI
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '24'
      - run: npm install -g @promptscript/cli
      - run: prs registry validate --strict
```

---

## Next Steps

- [Enterprise Setup](https://getpromptscript.dev/guides/enterprise/index.md) - Scale PromptScript across your organization
- [CI/CD Integration](https://getpromptscript.dev/guides/ci/index.md) - Automate validation and compilation in your pipeline

---

## Registry Aliases

Registry aliases let you define short names for Git repository URLs so that imports stay readable and organization-wide base URLs are configured in one place.

### Configuring Aliases

Aliases are defined in the `registries` field of `promptscript.yaml` (project scope) or `~/.promptscript/config.yaml` (user scope):

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

Use any scoped name as the key. The value is a bare Git host path - no `https://` prefix required.

### Three-Level Merge

Aliases are merged from three sources in priority order (highest first):

1. **Project** - `promptscript.yaml` in the repo (team-specific overrides)
2. **User** - `~/.promptscript/config.yaml` (developer preferences)
3. **System** - `/etc/promptscript/config.yaml` (IT-provisioned defaults)

Project aliases win over user aliases, which win over system aliases. This lets IT provision company-wide aliases while still allowing projects to override specific ones.

### Using Aliases in .prs Files

Once configured, use the alias as the scope prefix in any import:

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

# Resolves to github.com/acme/promptscript-base/@org/base.prs
@inherit @company/@org/base

# Resolves to github.com/acme/team-frontend/@stacks/react.prs
@use @team/@stacks/react
```

<!-- playground-link-start -->
<a href="https://getpromptscript.dev/playground/?s=N4IgZglgNgpgziAXAbVABwIYBcAWSQwAeGAtmrAHRoBOCANCAMYD2AdljO-gAIkxYYABMEEQAJokEAdECQCeAWhrMAVjEZYZguHPYZCkmQEYKAVgoAGLQF8prOwGJBAJXjMoAN3iCszQQHMIXABXACMKFhIAegxGPijlMiw4RmoINCwFUIw4GCjuZmp-KOzcqlo7bghWHBg0rEFuSMxWOXzC4tKYO0cXN09vXwCgnDCI5mjY+I5SBTBqNg5WMXy4AUYAazgo6hhYrHK4SuDcxpno7jXYrZ29jRBrOnRsPEQQJomWtoKikpyYQ4gBgsdicLD4JwAZWCaHIEBgYm0flwMEERFI5FR1GCrDgglquwoggAcswGphqA1mGAfLVBGJmIxgnw9FgIGw6IIMMtBKwyVzBLsMFBBJhNhh-ADKnwBMI7IJRBJpO9mtzvh0-rkZPLtLoBAZlSYAGyWbWsBUkCCEaqSLDY7qsWysS4CZYYahiPHAHUsMQwSTIGQABSgsRgOHcfuo2ldYndYhkAF0dRw1tV-AHg6HGOHI3UY9y4x6k3Yndxdms0hp2bi5ebBAplSGwxGoFHBfA7RBq2wzdYHk8QJhcDxzqt1jchRpAcDFmCIYJobCoPDEXBkXT0WRYIKcXiCQCSfyKVSaSj6YzmWDsDXOYXefyhEKRWKNhKpc6ZUJvfXxIZ3mOLrXNsU6aCAOo6HoBrGBQJpWOB9aWtarC2vapaVFcboel6PrMH6mYgM2Oatu2mFFgmIDJvWqZsqwGaCIGhHZrmbb5mR8Ylo6lQVl2Pa1j+CqNlmLZ5tGPFVmyvYIf21iJgwYLUHI+BbpiM4gF4tA1vgRgPEAA" target="_blank" rel="noopener noreferrer">
  <img src="https://img.shields.io/badge/Try_in-Playground-blue?style=flat-square" alt="Try in Playground" />
</a>
<!-- playground-link-end -->

---

## Go-Style URL Imports

Beyond registry aliases, PromptScript supports Go-module-style bare URL imports. You can reference any Git repository directly by its host path - no alias required.

### Basic URL Import

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

# Import directly from a public GitHub repo
@use github.com/acme/shared-standards/@fragments/security

# Import from any Git host
@use gitlab.com/myorg/prompts/@stacks/python
```

<!-- playground-link-start -->
<a href="https://getpromptscript.dev/playground/?s=N4IgZglgNgpgziAXAbVABwIYBcAWSQwAeGAtmrAHRoBOCANCAMYD2AdljO-gAIkxYYABMEEQAJokEAdECQCeAWhrMAVjEZYZguHPYZCkmQEYKAVgoAGLQF8prOwGJBASTLNqWQWIjV1WKHKCYNTMJIJCaACuAEZQEIyCAOIQWAASMYK+aMx23JFwMIIA5ik4MRQsJAD0GIx8VXA4GL5iCnACrGLNYnBV3MEYRXzsvQWMkdQpcnaOLm4eQSFhGKyByZ44zO25+YUl-hjRFaFV8u5FVcpkWL3c7bUA1r1ocrhsINZ06Nh4iCD7ZSOlRqdRgDSaLTaHS61B6fQGQ04Nwa6gmUyotBADBY7CR+CcAGVImhyBAYGJtMxBLhCkRSORCtRIqw4IIcDBfBRBAA5ZieTALZhgansrzMcbDARYCBsOjhTqCVh88KZGAYKCCTCMB6DGAUXJ8ATCOyCUQSaT-UrlYG1eqNZrkqErGFw-rUQaS0aoyZYaYgE3aXQCAwWkwANksMgDJAghAgrEkWCZMDstlYd2h3VZwADLDEMEkyBkAAUoLUYJsoPnqNpM7CZABdAMcdrxoqFktlxgV5hVjm153dRup3K+dqTDQylnG1imhQW0vlyvV1Xj+LSthR1jWD5fECYXD4fZloEnM7UC5XNDIjOPZ6vTasDH0JhsDhcP6E4mk8mUkW04gyFgTJmVZdlOR5ZUBU8IV-zFCUkWwKc5WdRVlSEXx1U1R5dX1dNDSEHNZzNQxLQOU9qnPS8lmvW57m1e83nsf1iJ0PQQ2MCgIysFjTRjOME2pZMR3Te5OizGdTTzAtBCLEBF27Zd+zEl1h2IltpVYdtZM7JdexXFShxAJtt1HeAk3XKdswDeddMU-T+zHCzJ03Fid2sBsGCRag5HwOkgL1GgXwANw5OAp3wIwPiAA" target="_blank" rel="noopener noreferrer">
  <img src="https://img.shields.io/badge/Try_in-Playground-blue?style=flat-square" alt="Try in Playground" />
</a>
<!-- playground-link-end -->

### Version Pinning in URL Imports

Append a version specifier with `@`:

```promptscript
# Pin to an exact tag
@use github.com/acme/shared-standards/@org/base@1.2.0

# Pin to a semver range (latest patch in 1.x)
@use github.com/acme/shared-standards/@org/base@^1.0.0

# Pin to a branch
@use github.com/acme/shared-standards/@org/base@main
```

<!-- playground-link-start -->
<a href="https://getpromptscript.dev/playground/?s=N4IgZglgNgpgziAXAbVABwIYBcAWSQwAeGAtmrAHRoBOCANCAMYD2AdljO-gMQAEAAiRhYMvDABNxMcbzjNeuCHF5hqGAOZD2vFmWjxebXhCzLmAd1bGruGL3IYAnuurMArq3EAdVoOGjgH15jcUReLwJiMlgIoNlHdgxCMIiARgoANgoABljWAF8fHz4ABQgbeQwrIgxGLAUNH343ODt1Exw3ACMKXQB6WqE+uBwMamkAWjgRTzHxOD7+Zmp1Pq6MVv50gCYcotZS8oVK2RgSADcYal41VnU7AAoobHh6zCxGHGtedMIASiaLTaHW6vWYJAGjCGIzGk2mVXEcwWSxWaw2MH4AD10tk9qxirwyhUxLwurdPoDWrx2rhQf1BjBhqNxuIpjNEdR5otlqt1psSBhyiB8nR0Ng8IgQDTOj16VDGTCWWyEUjuai+RidjkqLQQAwWOxOFgeLwAMpuNDkCDSWTyWy8GrROzUDzKHBXGAUXgAOWYbzG9WYYAU7t44mYjDcWhEWAgbDoYk8vFYfpJ4wwUHstQA1hpPU0hCJeIErCEUlKQbLwZDocy4ezVSjeeithRdrkQHE4AkRMlwiB0lkO3ESBBCOUwlgXTAfIVfPDZpzlCXgiwpGFkBESs9GDAcMwoFJrguOd4QABdOIcabldQbrc7vcHo+yBuciKXgpNcbTagQOpxqwy5xBM-bbrUT6HlcNyvH+AFsHk+TCqKIDvBKFa0lWEIMkysKsiejY8mimzYtquI0PQTBsBwXCSnw5qWlA1oyHIIZ2I65DOq6vDuuMXq+v61CBsG9rhpG0bYIBCYIsmqaiOmmaYIwub3BQBb+MWcQQKE-bSnS1Y4Yq9YqkuarNiROJ7J2pbdokfZpJkVkjmOE4KNOs5NARS6aaWa4wPeIDgbu+5Qceb5np+wTXrGdwBUFkEvl5EUeb4P5Tv+sZsMBpagQ+EEhS+aVwZl+LWUhIpirg+B6VhNYKnW+HhciREaoIgqsDqlEGjRxp0WaFpWjarH2hxsA3NxvGej6qaYEJhgiaGYlRkaknxomMgpvU8kwBmWbKXmam+IWARaTpEQ1WC2HyrhSpJc16otgK5R5MEtm9uWg5OaWo7jqwk7uV+85NT5q7MOuvCboFj4FdBSUflery3nF0PPrD4Xw4D-BFRlgHZcEuVQ-lqPXNj8GlbOwrngwRrUI4+CjZ6FF6iAly0IB+CpMKQA" target="_blank" rel="noopener noreferrer">
  <img src="https://img.shields.io/badge/Try_in-Playground-blue?style=flat-square" alt="Try in Playground" />
</a>
<!-- playground-link-end -->

| Specifier | Meaning                               |
| --------- | ------------------------------------- |
| `@1.2.0`  | Exact tag `v1.2.0` or `1.2.0`         |
| `@^1.0.0` | Latest tag matching `^1.0.0` (semver) |
| `@main`   | Tip of branch `main`                  |
| (none)    | Default branch as configured          |

### Alias vs URL Import

| Style         | Example                                | When to Use                        |
| ------------- | -------------------------------------- | ---------------------------------- |
| Alias         | `@use @company/security`               | Frequently-used internal packages  |
| Full URL      | `@use github.com/acme/security`        | One-off external imports           |
| Versioned URL | `@use github.com/acme/security@^1.0.0` | Reproducible external dependencies |

---

## Auto-Discovery

When you import a repository that does not contain `.prs` files, PromptScript looks for native AI plugin files and converts them automatically. This means you can `@use` any GitHub repository that contains `SKILL.md`, agent definitions, or command files - even if it was not authored with PromptScript.

### What Gets Auto-Discovered

| Source File Pattern                       | Imported As        |
| ----------------------------------------- | ------------------ |
| `SKILL.md` in root or `skills/` directory | `@skills` block    |
| `.claude/agents/*.md`                     | `@agents` block    |
| `.claude/commands/*.md`                   | `@shortcuts` block |
| `.github/skills/*/SKILL.md`               | `@skills` block    |

Agent and command frontmatter is parsed as YAML, the same way as in
`.promptscript/agents/` and `.promptscript/commands/`. See
[Agents and Commands as Markdown Files](https://getpromptscript.dev/features/agents/index.md#agents-and-commands-as-markdown-files).

### Example: Importing an Open-Source Skill Library

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

# This repo has a SKILL.md but no .prs files - auto-discovered
@use github.com/some-org/claude-skills/skills/tdd-workflow
```

<!-- playground-link-start -->
<a href="https://getpromptscript.dev/playground/?s=N4IgZglgNgpgziAXAbVABwIYBcAWSQwAeGAtmrAHRoBOCANCAMYD2AdljO-gAIkxYYABMEEQAJokEAdECQCeAWhrMAVjEZYZguHPYZCkmQEYKAVgoAGLQF8prOwGJBAFRwQ4g6jDTNBODB5CAMoA0gCSADIRFCRiggBGAK5Ygqy+VLSCkLAeCoIYycwKYu4sAG4wXmJ23IlwMIIA5hC4ifEULCQA9HDMfArM1I1djFAFYjAKcADW0FBwPbNQ811YYmIKAO6D02BQzJsg1nTo2HiIIM2t7Z09fZODw6PjkzNzC2-LC2sb29S7+02GXoTDYHC4FycQUSaHIEBgcV6glwDSIpHIDWoiVYHhwlRgFEEADlmClMNQUswwMi8YIxMxGIk+HosBA2HR8qw4mkUkIvBgoIJMIxphhGgSanwBMI7IJRBJpJcWjg2h0+nd+o8RmNEhMpksVp8Vj8tjs9gcZLLtLoBAZFSYAGyWS2sOUkCCECCsSRYLEwOy2VjcOACLkYahiDzAK0sCaSZAyAAKY0YMBwzCgE2o2lDYnD1RAAF0rRwQ17GvGkym0xmszmMGGIzJi6xA9wvCHqBANGycTLXYI8lWMKn05nKp54L7u6y2C7rEdCwxOL65Pg0WRKDQQRVaL38EYjkA" target="_blank" rel="noopener noreferrer">
  <img src="https://img.shields.io/badge/Try_in-Playground-blue?style=flat-square" alt="Try in Playground" />
</a>
<!-- playground-link-end -->

PromptScript fetches the repository, detects the `SKILL.md`, and synthesizes a virtual `.prs` fragment that you can merge into your project just like any other import.

:::tip[Zero Config Required]
Auto-discovery works without any setup in the remote repo. The remote maintainer does not need to know about PromptScript.
:::

---

## Lockfile

PromptScript generates a `promptscript.lock` file to record the exact resolved commit for every remote import. This gives you reproducible builds - the same source always produces the same output, regardless of when you compile.

### Generating the Lockfile

```bash
prs lock            # Create or update promptscript.lock
prs lock --dry-run  # Show what would change without writing
```

Compilation never rewrites the lockfile. Run `prs lock` after adding or changing
remote imports, then commit the result.

### Lockfile Format

Actual `prs lock` output for a project configured with
`registry.git.url: https://github.com/acme/promptscript-base.git`:

```yaml
# promptscript.lock - written by `prs lock`
version: 1
dependencies:
  https://github.com/acme/promptscript-base.git:
    version: main
    commit: a3f8c2d91b4e6f7890123456789abcdef0123456
    integrity: sha256-pending
```

For a default Git registry, the dependency key preserves the configured URL.
`version` records the requested ref, while `commit` records the resolved
40-character commit SHA.

Projects whose skills pull registry reference files (via `@skills.references`) also get a `references` map. The shape below is illustrative - the key and hash values come from your own locked content - but the field types are exact:

```yaml
# Illustrative view - run `prs lock` to see real values
references:
  "github.com/acme/promptscript-base\0references/testing.md\0main":
    hash: sha256-0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef # 64-char SHA-256
    lockedAt: 2026-03-23T10:00:00.000Z # ISO timestamp of when `prs lock` recorded this hash
```

`integrity: sha256-pending` is the literal value `prs lock` writes for Git dependencies: the commit pin is the security guarantee, so no content hash is claimed for the repository as a whole. Managed Markdown-sourced skill entries get a computed `sha256-<hex>` instead, aggregated from their child entries.

### Integrity Hashes

The `dependencies` map pins each remote repository to an exact commit.
Registry-sourced files listed by `@skills.references` are recorded separately in
the top-level `references` map using the repository URL, relative path, and
locked version as the key. This applies to aliased imports and the default Git
registry. During compilation and validation, these SHA-256
hashes are verified against the actual file contents. If a reference has been
modified since it was locked, a reference integrity error is raised.

This protects against:

- **Tampered dependencies** - changes to registry files after locking
- **Cache corruption** - stale or corrupted cached copies
- **Supply chain attacks** - unauthorized modifications to shared skills

To skip hash verification (e.g., during local development), use:

```bash
prs compile --ignore-hashes
prs validate --ignore-hashes
```

:::caution
Never use `--ignore-hashes` in CI pipelines. Hash verification is a critical security check for production builds.
:::

### Committing the Lockfile

Commit `promptscript.lock` to version control. This ensures:

- **Reproducible builds** - CI always compiles against the same commits
- **Auditable deps** - diffs show exactly when a dependency was updated
- **Offline support** - works with `prs vendor sync` (see below)

### Updating Dependencies

```bash
# Update a specific package to its latest allowed version
prs update github.com/acme/promptscript-base

# Update all packages
prs update

# Preview updates without writing
prs update --dry-run
```

---

## Vendor Mode

Vendor mode copies all remote dependencies into a local `.promptscript/vendor/` directory. This enables fully offline builds - useful in air-gapped CI environments or when you want to audit third-party content before it runs.

### Syncing the Vendor Directory

```bash
# Download the exact lockfile-resolved packages to vendor/
prs vendor sync

# Check that vendor/ is in sync with the lockfile
prs vendor check
```

`prs vendor sync` fails if an exact locked commit cannot be downloaded. After a successful sync, compilation resolves locked remote imports from the vendor directory without network requests.

Tracked symbolic links are accepted only when they resolve to tracked regular files inside the same repository and outside retained Git metadata. Broken, external, directory, and retargeted symbolic links fail repository verification.

Vendor commands reject a symbolic link or filesystem escape in the `.promptscript/` parent before reading, replacing, or cleaning vendor content.

### Vendor Directory Structure

```
.promptscript/
└── vendor/
    ├── github.com/
    │   ├── acme/
    │   │   └── promptscript-base/
    │   │       ├── .promptscript-git/
    │   │       ├── @org/base.prs
    │   │       └── @org/security.prs
    │   └── some-org/
    │       └── claude-skills/
    │           └── skills/
    │               └── tdd-workflow/
    │                   └── SKILL.md
    └── .vendor-manifest.json
```

### CI Pipeline with Vendor

```yaml
# .github/workflows/promptscript.yml
- name: Validate
  run: prs vendor check && prs validate --strict

- name: Compile
  run: prs compile
```

Commit the vendor directory to your repository for fully self-contained, network-free builds. Regenerating it requires network access to the locked repositories.

---

## Private Repositories

### SSH Authentication

PromptScript uses your existing SSH keys automatically for `git@` URLs:

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

Or in URL imports:

```promptscript
@use git@github.com:acme/private-skills/@fragments/security
```

<!-- playground-link-start -->
<a href="https://getpromptscript.dev/playground/?s=N4IgZglgNgpgziAXAbVABwIYBcAWSQwAeGAtmrAHRoBOCANCAMYD2AdljO-gMQAEAAiRhYMvDABNxMcbzjNeuCHF5hqGAOZD2vFmWjxebXhCzLmAd1bGruGL3IYAnuurMArq3EAdVoOGjgH15jcUReLwJiMlgIoNlHdgxCMIiARgoANgoABljWAF8fH343ODt1E34K3DcAIwpdRAxGIQB6GggAN2wYAFo4AGtoKDhW-lUNLVNWssY3ahNHEHy6dGw8RBBqqpMcOobmEiaWmHaF7o5+oagRsYnNTmnZ+cWqWhAGFnZHnl4AZTcaHIEGksnktl4RFI5Ds1A8yhwMGoMAovAAcswsPYMNQscwwApEbxxMw5lNsBA2HQxJ5eKxMWJeMiMFBsYwBhoUcUhCJeIErCEUltKtU9vVGs02h0Ln1BsNRuM1A92KNngssI48sE4AkRMlwiB0llciA4iQIIQIKwwlg4TAfIVfHARJ4ceJlPzgiwpGFkBEAApQZowHDMKBSaiyF3iN0RAC6cQ4zqt6l9AaDjBDYYjUYwruo3hACYKxWRzoWjCwlNYHrivQNgeDofDSKZ8FtEEr1by+WWcYYj2oS02UOiKJo9BAnSRcGr+FSyyAA" target="_blank" rel="noopener noreferrer">
  <img src="https://img.shields.io/badge/Try_in-Playground-blue?style=flat-square" alt="Try in Playground" />
</a>
<!-- playground-link-end -->

Ensure your SSH key is added to `ssh-agent` or configured in `~/.ssh/config`.

### Token Authentication (GITHUB_TOKEN)

For HTTPS URLs, configure a token in your registry entry:

```yaml
# promptscript.yaml
registry:
  git:
    url: https://github.com/acme/promptscript-base.git
    ref: main
    auth:
      type: token
      tokenEnvVar: GITHUB_TOKEN
```

The `tokenEnvVar` field names the environment variable that holds the token - it is never stored in plain text.

### User-Level Token Configuration

Set up credentials for the default Git registry in `~/.promptscript/config.yaml`:

```yaml
# ~/.promptscript/config.yaml
version: '1'

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

registry:
  git:
    url: https://github.com/acme/promptscript-base.git
    auth:
      type: token
      tokenEnvVar: GITHUB_TOKEN
```

### CI Configuration

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