/prpm-json-best-practices-skill

name: prpm-json-best-practices
description: Best practices for structuring prpm.json package manifests with required fields, tags, organization, multi-package management, enhanced file format, eager/lazy activation, and conversion hints

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