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 files format):

{
  "files": [
    {
      "path": ".claude/skills/critical-skill/SKILL.md",
      "format": "claude",
      "subtype": "skill",
      "eager": true
    },
    {
      "path": ".claude/skills/optional-skill/SKILL.md",
      "format": "claude",
      "subtype": "skill",
      "eager": false
    }
  ]
}

Precedence

When installing, the final eager setting is determined by:

1. CLI flag (--eager/--lazy) - highest priority
2. File-level eager setting (enhanced files)
3. Package-level eager setting
4. Default: lazy (false)

Applicable Subtypes

Subtype	Supports Eager
skill	Yes
agent	Yes
rule	No
slash-command	No
hook	No

Eager loading only affects progressive disclosure formats (agents.md, gemini.md, claude.md, aider).

Tags Best Practices

Tag Structure

• Use kebab-case for all tags
• Be specific and searchable
• Include 3-8 tags per package
• Combine technology, domain, and purpose tags

Tag Categories

Technology Tags:

• Languages: typescript, python, javascript, rust
• Frameworks: react, nextjs, fastify, django
• Tools: aws, docker, kubernetes, postgresql

Domain Tags:

• deployment, testing, ci-cd, database
• infrastructure, cloud, monitoring
• documentation, code-review, security

Purpose Tags:

• troubleshooting, debugging, best-practices
• automation, quality-assurance, performance
• architecture, design-patterns

Meta Tags:

• meta - For packages about creating packages
• prpm-internal - For internal/private packages
• prpm-development - For PRPM development itself

Tag Examples

Good Tags:

{
  "tags": ["typescript", "type-safety", "code-quality", "best-practices", "static-analysis"]
}

Poor Tags:

{
  "tags": [
    "code", // Too generic
    "stuff", // Meaningless
    "TypeScript", // Wrong case
    "type_safety" // Wrong format (use kebab-case)
  ]
}

Organization Best Practices

Multi-Package Organization

Order packages by:

1. Privacy - Private packages first
2. Format - Group by format (claude, cursor, etc.)
3. Subtype - Group by subtype (agent, skill, rule)

Example organization:

{
  "packages": [
    // Private > Claude > Agents
    { "name": "internal-agent", "private": true, "format": "claude", "subtype": "agent" },

    // Private > Claude > Skills
    { "name": "internal-skill", "private": true, "format": "claude", "subtype": "skill" },

    // Private > Cursor > Rules
    { "name": "internal-rule", "private": true, "format": "cursor", "subtype": "rule" },

    // Public > Claude > Skills
    { "name": "public-skill", "format": "claude", "subtype": "skill" },

    // Public > Cursor > Rules
    { "name": "public-rule", "format": "cursor", "subtype": "rule" }
  ]
}

Naming Conventions

Package Names:

• Use kebab-case: my-awesome-skill
• Be descriptive: typescript-type-safety not ts-types
• Avoid duplicates across formats: use suffixes if needed
  • format-conversion-agent (Claude agent)
  • format-conversion (Cursor rule)

File Paths:

• Use full paths from project root (where prpm.json lives)
• Agents: .claude/agents/name.md
• Skills: .claude/skills/name/SKILL.md
• Rules: .cursor/rules/name.mdc
• Commands: .claude/commands/category/name.md

Version Management

Semver Guidelines

Follow semantic versioning:

• Major (1.0.0 → 2.0.0): Breaking changes
• Minor (1.0.0 → 1.1.0): New features, backward compatible
• Patch (1.0.0 → 1.0.1): Bug fixes, backward compatible

Version Bumping

When to bump versions:

• Patch: Bug fixes, typo corrections, minor improvements
• Minor: New sections, additional examples, new features
• Major: Complete rewrites, breaking changes, renamed fields

Keep Versions in Sync

For multi-package repos, keep related packages in sync:

{
  "packages": [
    { "name": "pkg-one", "version": "1.2.0" },
    { "name": "pkg-two", "version": "1.2.0" },
    { "name": "pkg-three", "version": "1.2.0" }
  ]
}

File Management

Files Array

CRITICAL: File paths must be full paths from project root (where prpm.json lives).

Required:

• List all files to include in the package
• Use full paths from project root - not relative to destination directories
• Paths should start with .claude/, .cursor/, etc.
• Include documentation files

Why Full Paths? File paths in prpm.json are used for:

1. Tarball creation - Reads files directly from these paths
2. Snippet extraction - Shows file preview before install
3. Installation - CLI derives destination from format/subtype

Examples:

Claude agent (single file):

{
  "format": "claude",
  "subtype": "agent",
  "files": [".claude/agents/my-agent.md"]
}

Claude skill (multiple files):

{
  "format": "claude",
  "subtype": "skill",
  "files": [
    ".claude/skills/my-skill/SKILL.md",
    ".claude/skills/my-skill/EXAMPLES.md",
    ".claude/skills/my-skill/README.md"
  ]
}

Cursor rule:

{
  "format": "cursor",
  "subtype": "rule",
  "files": [".cursor/rules/my-rule.mdc"]
}

Slash command:

{
  "format": "claude",
  "subtype": "slash-command",
  "files": [".claude/commands/category/my-command.md"]
}

Enhanced File Format

Advanced: Files can be objects with metadata instead of simple strings. Useful for packages with multiple files targeting different formats or needing per-file metadata.

Enhanced file object structure:

{
  "files": [
    {
      "path": ".cursor/rules/typescript.mdc",
      "format": "cursor",
      "subtype": "rule",
      "name": "TypeScript Rules",
      "description": "TypeScript coding standards and best practices",
      "tags": ["typescript", "frontend"]
    },
    {
      "path": ".cursor/rules/python.mdc",
      "format": "cursor",
      "subtype": "rule",
      "name": "Python Rules",
      "description": "Python best practices for backend development",
      "tags": ["python", "backend"]
    }
  ]
}

When to use enhanced format:

• Multi-file packages with different formats/subtypes per file
• Need per-file descriptions or tags
• Want to provide display names for individual files
• Building collection packages with mixed content types

Enhanced file fields:

Field	Required	Description
path	Yes	Relative path to file from project root
format	Yes	File's target format (cursor, claude, etc.)
subtype	No	File's subtype (rule, skill, agent, etc.)
name	No	Display name for this file
description	No	Description of what this file does
tags	No	File-specific tags (array of strings)

Note: Cannot mix simple strings and objects in the same files array. Use all strings OR all objects, not both.

Common Mistake:

{
  // ❌ WRONG - Relative paths without directory prefix
  "files": ["agents/my-agent.md"]  // Will fail to find file

  // ✅ CORRECT - Full path from project root
  "files": [".claude/agents/my-agent.md"]
}

File Verification

Always verify files exist:

# Check all files in prpm.json exist
for file in $(cat prpm.json | jq -r '.packages[].files[]'); do
  if [ ! -f "$file" ]; then
    echo "Missing: $file"
  fi
done

Duplicate Detection

Check for Duplicate Names

Run this check before committing:

# Check for duplicate package names
cat prpm.json | jq -r '.packages[].name' | sort | uniq -d

If output is empty, no duplicates exist. If names appear, you have duplicates to resolve.

Resolving Duplicates

Bad:

{
  "packages": [
    { "name": "typescript-safety", "format": "claude" },
    { "name": "typescript-safety", "format": "cursor" }
  ]
}

Good:

{
  "packages": [
    { "name": "typescript-safety", "format": "claude", "subtype": "skill" },
    { "name": "typescript-safety-rule", "format": "cursor", "subtype": "rule" }
  ]
}

Conversion Hints (Advanced)

Purpose: Help improve quality when converting packages to other formats. The conversion field provides format-specific hints for cross-format transformations.

Note: This is an advanced feature primarily used by format conversion tools. Most packages don't need this.

Structure:

{
  "name": "my-package",
  "version": "1.0.0",
  "format": "claude",
  "conversion": {
    "cursor": {
      "alwaysApply": false,
      "priority": "high",
      "globs": ["**/*.ts", "**/*.tsx"]
    },
    "kiro": {
      "inclusion": "fileMatch",
      "fileMatchPattern": "**/*.ts",
      "domain": "typescript",
      "tools": ["fs_read", "fs_write"],
      "mcpServers": {
        "database": {
          "command": "mcp-server-postgres",
          "args": [],
          "env": {
            "DATABASE_URL": "${DATABASE_URL}"
          }
        }
      }
    },
    "copilot": {
      "applyTo": ["src/**", "lib/**"],
      "excludeAgent": "code-review"
    }
  }
}

Supported conversion hints:

Cursor Hints

{
  "conversion": {
    "cursor": {
      "alwaysApply": boolean,      // Whether rule should always apply
      "priority": "high|medium|low", // Rule priority level
      "globs": ["**/*.ts"]         // File patterns to auto-attach
    }
  }
}

Claude Hints

{
  "conversion": {
    "claude": {
      "model": "sonnet|opus|haiku|inherit", // Preferred model
      "tools": ["Read", "Write"], // Allowed tools
      "subagentType": "format-conversion" // Subagent type if agent
    }
  }
}

Kiro Hints

{
  "conversion": {
    "kiro": {
      "inclusion": "always|fileMatch|manual", // When to include
      "fileMatchPattern": "**/*.ts", // Pattern for fileMatch mode
      "domain": "typescript", // Domain category
      "tools": ["fs_read", "fs_write"], // Available tools
      "mcpServers": {
        // MCP server configs
        "database": {
          "command": "mcp-server-postgres",
          "args": [],
          "env": { "DATABASE_URL": "${DATABASE_URL}" }
        }
      }
    }
  }
}

Copilot Hints

{
  "conversion": {
    "copilot": {
      "applyTo": "src/**", // Path patterns
      "excludeAgent": "code-review|coding-agent" // Agent to exclude
    }
  }
}

Continue Hints

{
  "conversion": {
    "continue": {
      "alwaysApply": boolean,           // Always apply rule
      "globs": ["**/*.ts"],             // File patterns
      "regex": ["import.*from"]         // Regex patterns
    }
  }
}

Windsurf Hints

{
  "conversion": {
    "windsurf": {
      "characterLimit": 12000 // Warn if exceeding limit
    }
  }
}

Agents.md Hints

{
  "conversion": {
    "agentsMd": {
      "project": "my-project", // Project name
      "scope": "backend" // Scope/domain
    }
  }
}

When to use conversion hints:

• Publishing cross-format packages that need specific settings per format
• Format conversion tools need guidance on how to transform content
• Package behavior should change based on target format
• Want to preserve format-specific metadata during conversions

Common Patterns

Private Internal Packages

{
  "name": "internal-tool",
  "version": "1.0.0",
  "description": "Internal development tool",
  "private": true,
  "format": "claude",
  "subtype": "skill",
  "tags": ["prpm-internal", "development"],
  "files": [".claude/skills/internal-tool/SKILL.md"]
}

Meta Packages (Creating Other Packages)

{
  "name": "creating-skills",
  "version": "1.0.0",
  "description": "Guide for creating effective Claude Code skills",
  "format": "claude",
  "subtype": "skill",
  "tags": ["meta", "claude-code", "skills", "documentation", "best-practices"],
  "files": [".claude/skills/creating-skills/SKILL.md"]
}

Cross-Format Packages

When you have the same content for multiple formats:

{
  "packages": [
    {
      "name": "format-conversion-agent",
      "format": "claude",
      "subtype": "agent",
      "description": "Agent for converting between AI prompt formats",
      "files": [".claude/agents/format-conversion.md"]
    },
    {
      "name": "format-conversion",
      "format": "cursor",
      "subtype": "rule",
      "description": "Rule for converting between AI prompt formats",
      "files": [".cursor/rules/format-conversion.mdc"]
    }
  ]
}

Collections in prpm.json

Collections CAN be defined in prpm.json alongside packages using the collections array. Collections bundle multiple packages together for easier installation.

Example with both packages and collections: