prpm-json-best-practices

What this skill does

# 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:**
```json
{
  "name": "code-style-enforcer",
  "version": "1.0.0",
  "format": "claude",
  "subtype": "skill",
  "eager": true,
  "files": [".claude/skills/code-style/SKILL.md"]
}
```

**File-level (enhance