> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prpm.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Manifest Reference

> Complete prpm.json documentation

# prpm.json Reference

Complete reference for the PRPM package manifest.

<Tip>
  **Need help creating prpm.json files?** Install the PRPM package that teaches AI to write prpm.json manifests:

  ```bash theme={null}
  # For Claude Code
  prpm install @prpm/prpm-json-best-practices-skill

  # For Cursor
  prpm install @prpm/prpm-json-best-practices
  ```

  These packages include real examples and best practices for single-package, multi-package, and collection repositories.
</Tip>

## Single Package

Basic package manifest:

```json theme={null}
{
  "name": "my-package",
  "version": "1.0.0",
  "description": "Clear description of what this package does",
  "author": "Your Name <you@example.com>",
  "license": "MIT",
  "repository": "https://github.com/username/repo",
  "format": "cursor",
  "subtype": "rule",
  "tags": ["typescript", "best-practices"],
  "files": [".cursor/rules/my-rule.mdc"]
}
```

## Multi-Package Repository

For repositories with multiple packages:

```json theme={null}
{
  "name": "my-prompts-repo",
  "author": "Your Name",
  "license": "MIT",
  "repository": "https://github.com/username/repo",
  "packages": [
    {
      "name": "package-one",
      "version": "1.0.0",
      "description": "First package",
      "format": "cursor",
      "subtype": "rule",
      "tags": ["tag1"],
      "files": [".cursor/rules/one.mdc"]
    },
    {
      "name": "package-two",
      "version": "1.0.0",
      "description": "Second package",
      "format": "claude",
      "subtype": "skill",
      "tags": ["tag2"],
      "files": [".claude/skills/two/SKILL.md"]
    }
  ]
}
```

## Required Fields

### Single Package

| Field         | Type      | Description                             |
| ------------- | --------- | --------------------------------------- |
| `name`        | string    | Package name (kebab-case, unique)       |
| `version`     | string    | Semver version (e.g., `1.0.0`)          |
| `description` | string    | Clear description (min 10 chars)        |
| `author`      | string    | Author name and optional email          |
| `license`     | string    | SPDX license identifier                 |
| `format`      | string    | Target format (claude, cursor, etc.)    |
| `subtype`     | string    | Package type (agent, skill, rule, etc.) |
| `files`       | string\[] | Files to include in package             |

### Multi-Package

Each package in the `packages` array requires the same fields, except top-level `author`, `license`, and `repository` can be inherited.

## Format Values

| Format      | Description                |
| ----------- | -------------------------- |
| `claude`    | Claude Code                |
| `cursor`    | Cursor IDE                 |
| `continue`  | Continue.dev               |
| `windsurf`  | Windsurf IDE               |
| `copilot`   | GitHub Copilot             |
| `kiro`      | Kiro AI                    |
| `gemini`    | Gemini CLI                 |
| `opencode`  | OpenCode AI                |
| `ruler`     | Ruler                      |
| `droid`     | Factory Droid              |
| `agents.md` | Agents.md universal format |
| `mcp`       | Model Context Protocol     |
| `generic`   | Multi-tool                 |

### Format Aliases

Some formats have aliases for compatibility:

* `claude.md` → `claude`
* `gemini.md` → `gemini`

## Subtype Values

| Subtype         | Description                                     |
| --------------- | ----------------------------------------------- |
| `agent`         | Autonomous agents that execute multi-step tasks |
| `skill`         | Specialized capabilities and knowledge domains  |
| `rule`          | IDE rules and coding standards                  |
| `slash-command` | Executable commands for quick actions           |
| `prompt`        | Reusable prompt templates                       |
| `workflow`      | Multi-step automation workflows                 |
| `tool`          | Executable utilities, scripts, and MCP servers  |
| `template`      | File and project templates                      |
| `collection`    | Curated package collections                     |
| `chatmode`      | Chat interface modes and configurations         |
| `hook`          | Event-triggered executable hooks                |

### Subtype by Format

Different formats support different subtypes:

* **claude**: skill, agent, slash-command, tool, hook
* **cursor**: rule, agent, slash-command, tool
* **continue**: rule, agent, prompt
* **windsurf**: rule, agent, slash-command
* **kiro**: rule, agent, tool, hook
* **opencode**: agent, slash-command, tool
* **ruler**: rule, agent, tool
* **droid**: skill, slash-command, hook
* **mcp**: tool
* **generic**: all subtypes

## File Paths

Use full paths from project root:

**Correct:**

```json theme={null}
{
  "files": [".cursor/rules/typescript.mdc"]
}
```

**Wrong:**

```json theme={null}
{
  "files": ["rules/typescript.mdc"]  // Missing .cursor/ prefix
}
```

## Tags

Use 3-8 kebab-case tags:

**Good:**

```json theme={null}
{
  "tags": ["typescript", "best-practices", "type-safety"]
}
```

**Bad:**

```json theme={null}
{
  "tags": ["TypeScript", "code_quality"]  // Wrong case, wrong separator
}
```

## Optional Fields

| Field           | Type      | Description                            |
| --------------- | --------- | -------------------------------------- |
| `repository`    | string    | GitHub repository URL                  |
| `homepage`      | string    | Package homepage                       |
| `documentation` | string    | Documentation URL                      |
| `organization`  | string    | Organization name/ID                   |
| `keywords`      | string\[] | Additional search keywords             |
| `private`       | boolean   | Mark as private (default: false)       |
| `scripts`       | object    | Lifecycle scripts (multi-package only) |

## Lifecycle Scripts

<Warning>
  The `scripts` field only applies to **multi-package manifests** (prpm.json with a `packages` array). It does not work in single-package manifests.
</Warning>

Use the `scripts` field to run commands automatically during package operations:

```json theme={null}
{
  "name": "my-packages",
  "license": "MIT",
  "repository": "https://github.com/username/repo",
  "scripts": {
    "prepublishOnly": "cd packages/hooks && npm run build"
  },
  "packages": [...]
}
```

### Available Scripts

| Script           | When it Runs                  | Use Case                               |
| ---------------- | ----------------------------- | -------------------------------------- |
| `prepublishOnly` | Before `prpm publish`         | Build TypeScript hooks, compile assets |
| `prepublish`     | Before publish AND on install | Not recommended - use prepublishOnly   |

### prepublishOnly (Recommended)

Use `prepublishOnly` to build hooks or compile code before publishing:

```json theme={null}
{
  "scripts": {
    "prepublishOnly": "cd .claude/hooks/my-hook && npm run build"
  }
}
```

**What happens:**

1. You run `prpm publish`
2. PRPM runs your `prepublishOnly` script
3. If the script succeeds, publishing continues
4. If the script fails, publishing is aborted

**Common use cases:**

* Building TypeScript hooks to JavaScript
* Compiling assets
* Running tests before publish
* Validating package contents

### Multiple Commands

Chain multiple commands with `&&`:

```json theme={null}
{
  "scripts": {
    "prepublishOnly": "npm test && npm run build && npm run validate"
  }
}
```

### Example: Building Multiple Hooks

```json theme={null}
{
  "name": "my-hooks",
  "scripts": {
    "prepublishOnly": "cd .claude/hooks/hook-one && npm run build && cd ../hook-two && npm run build"
  },
  "packages": [
    {
      "name": "hook-one",
      "version": "1.0.0",
      "format": "claude",
      "subtype": "hook",
      "files": [
        ".claude/hooks/hook-one/hook.ts",
        ".claude/hooks/hook-one/hook.json",
        ".claude/hooks/hook-one/dist/hook.js"
      ]
    },
    {
      "name": "hook-two",
      "version": "1.0.0",
      "format": "claude",
      "subtype": "hook",
      "files": [
        ".claude/hooks/hook-two/hook.ts",
        ".claude/hooks/hook-two/hook.json",
        ".claude/hooks/hook-two/dist/hook.js"
      ]
    }
  ]
}
```

### Script Execution Details

**Working Directory:** Scripts run from the directory containing prpm.json

**Timeout:** Default 5 minutes (300,000ms)

**Environment:** Inherits your shell's environment variables

**Error Handling:**

* Exit code 0 = success (publishing continues)
* Exit code non-zero = failure (publishing aborted)
* Script output is shown in real-time

### Best Practices

<Tip>
  **Always use prepublishOnly for builds**

  This ensures your published packages always contain up-to-date compiled code, preventing the common mistake of publishing stale JavaScript files.
</Tip>

**Good:**

```json theme={null}
{
  "scripts": {
    "prepublishOnly": "npm run build"
  }
}
```

**Bad:**

```json theme={null}
{
  "scripts": {
    "prepublish": "npm run build"  // Runs on install too!
  }
}
```

### Why Not prepublish?

The `prepublish` script runs both before publishing AND when someone runs `npm install` in your repository. This can cause unexpected build steps for users installing your packages.

Use `prepublishOnly` which ONLY runs before `prpm publish`.

## Next Steps

<CardGroup cols={2}>
  <Card title="Publishing Collections" icon="boxes-stacked" href="/publishing/collections">
    Create package collections
  </Card>

  <Card title="Publishing Guide" icon="upload" href="/publishing/getting-started">
    Publish your packages
  </Card>
</CardGroup>