prpm-json-best-practices

PRPM JSON Best Practices

You are an expert at creating and maintaining prpm.json package manifests for PRPM (Prompt Package Manager). You understand the structure, required fields, organization patterns, and best practices for multi-package repositories.

When to Apply This Skill

Use when:

• Creating a new prpm.json manifest for publishing packages
• Maintaining existing prpm.json files
• Organizing multi-package repositories
• Adding or updating package metadata
• Ensuring package manifest quality and completeness

Don't use for:

• User configuration files (.prpmrc) - those are for users
• Lockfiles (prpm.lock) - those are auto-generated by PRPM
• Regular package installation (users don't need prpm.json)
• Dependencies already tracked in lockfiles

Core Purpose

prpm.json is only needed if you're publishing packages. Regular users installing packages from the registry don't need this file.

Use prpm.json when you're:

• Publishing a package to the PRPM registry
• Creating a collection of packages
• Distributing your own prompts/rules/skills/agents
• Managing multiple related packages in a monorepo

File Structure

Single Package

See examples/single-package.json for complete structure.

Key fields: name, version, description, author, license, format, subtype, files

Multi-Package Repository

See examples/multi-package.json for complete structure.

Use when: Publishing multiple related packages from one repo Key difference: Top-level packages array with individual package definitions

Collections Repository

See examples/collections-repository.json for complete structure.

Use when: Bundling existing published packages into curated collections Key points:

• collections array references packages by packageId (not files)
• Each collection has id, name, description, packages
• Packages can be required: true (default) or false (optional)
• Use version ranges (^1.0.0) or latest
• Add reason to explain why package is included

Packages + Collections (Combined)

See examples/packages-with-collections.json for complete structure.

Use when: Publishing packages AND creating collections that bundle them Key points:

• Define packages in packages array with files
• Define collections in collections array referencing those packages
• Collections can reference both local packages and external ones
• Publish both individual packages and collection bundles from same repo

Required Fields

Top-Level (Single Package)

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Package name (kebab-case, unique in registry) | | version | string | Yes | Semver version (e.g., 1.0.0) | | description | string | Yes | Clear description of what the package does | | author | string | Yes | Author name and optional email | | license | string | Yes | SPDX license identifier (e.g., MIT, Apache-2.0) | | format | string | Yes | Target format: claude, cursor, continue, windsurf, etc. | | subtype | string | Yes | Package type: agent, skill, rule, slash-command, prompt, collection | | files | string[] | Yes | Array of files to include in package |

Optional Top-Level Fields

| Field | Type | Description | |-------|------|-------------| | repository | string | Git repository URL | | organization | string | Organization name (for scoped packages) | | homepage | string | Package homepage URL | | documentation | string | Documentation URL | | license_text | string | Full text of the license file for proper attribution | | license_url | string | URL to the license file in the repository | | tags | string[] | Searchable tags (kebab-case) | | keywords | string[] | Additional keywords for search | | category | string | Package category | | private | boolean | If true, won't be published to public registry | | dependencies | object | Package dependencies (name: semver) | | scripts | object | Lifecycle scripts (multi-package only) | | eager | boolean | If true, skill/agent loads at session start (not on-demand) |

Multi-Package Fields

When using packages array:

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Unique package name | | version | string | Yes | Package version | | description | string | Yes | Package description | | format | string | Yes | Package format | | subtype | string | Yes | Package subtype | | tags | string[] | Recommended | Searchable tags | | files | string[] | Yes | Files to include | | private | boolean | No | Mark as private | | eager | boolean | No | Load at session start (skills/agents only) |

Collection Fields

When using collections array:

Top-level (repository with collections):

• name, version, description, author, license - Required
• repository, organization - Recommended
• Note: No format, subtype, or files required at top level

Each collection object:

| Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | Unique collection identifier (kebab-case, 3-100 chars) | | name | string | Yes | Display name (3-100 chars) | | description | string | Yes | What the collection provides (10-500 chars) | | packages | array | Yes | Array of packages to include (minimum 1) | | version | string | Recommended | Semantic version of collection | | category | string | Recommended | Collection category (development, testing, etc.) | | tags | string[] | Recommended | Searchable tags (kebab-case, 1-10 items) | | icon | string | Optional | Emoji or icon (max 10 chars) |

Each package within collection:

| Field | Type | Required | Description | |-------|------|----------|-------------| | packageId | string | Yes | Package to include | | version | string | Optional | Version range (^1.0.0, ~2.1.0, 1.0.0, latest) | | required | boolean | Optional | Whether package is required (default: true) | | reason | string | Optional | Why package is included (max 200 chars) |

Format and Subtype Values

Format (Target AI Tool)

| Format | Description | |--------|-------------| | claude | Claude Code (agents, skills) | | cursor | Cursor IDE (rules, MDC files) | | continue | Continue.dev extension | | windsurf | Windsurf IDE | | copilot | GitHub Copilot | | kiro | Kiro IDE | | agents.md | Agents.md format | | generic | Generic/universal format | | mcp | Model Context Protocol |

Subtype (Package Type)

| Subtype | Description | Typical Formats | |---------|-------------|-----------------| | agent | Autonomous agents | claude, agents.md | | skill | Specialized capabilities | claude | | rule | IDE rules and guidelines | cursor, windsurf | | slash-command | Slash commands | cursor, continue | | prompt | Prompt templates | generic | | collection | Package collections | Any | | chatmode | Chat modes | kiro | | tool | MCP tools | mcp |

Eager vs Lazy Activation

Skills and agents can be configured to load eagerly (at session start) or lazily (on-demand when relevant).

When to Use Eager

Use eager: true when:

• The skill should ALWAYS be active (coding standards, style guides)
• Critical behavior that must never be skipped
• Small, foundational skills with minimal token cost

Keep lazy (default) when:

• Specialized skills for specific contexts
• Large skills with significant token overhead
• Skills that only apply to certain file types

Setting Eager in prpm.json

Package-level:

{
  "name": "code-style-enforcer",
  "version": "1.0.0",
  "format": "claude",
  "subtype": "skill",
  "eager": true,
  "files": [".claude/skills/code-style/SKILL.md"]
}

**File-level (enhanced