Manifest Reference

Complete prpm.json documentation

prpm.json Reference

Complete reference for the PRPM package manifest.

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

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

Single Package

Basic package manifest:

{
  "name": "my-package",
  "version": "1.0.0",
  "description": "Clear description of what this package does",
  "author": "Your Name <[e-mail]>",
  "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:

{
  "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:

{
  "files": [".cursor/rules/typescript.mdc"]
}

Wrong:

{
  "files": ["rules/typescript.mdc"]  // Missing .cursor/ prefix
}

Tags

Use 3-8 kebab-case tags:

Good:

{
  "tags": ["typescript", "best-practices", "type-safety"]
}

Bad:

{
  "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

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

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

{
  "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:

{
  "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 &&:

{
  "scripts": {
    "prepublishOnly": "npm test && npm run build && npm run validate"
  }
}

Example: Building Multiple Hooks

{
  "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

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.

Good:

{
  "scripts": {
    "prepublishOnly": "npm run build"
  }
}

Bad:

{
  "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

Publishing Collections

Create package collections

Publishing Guide

Publish your packages