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)

Optional Top-Level Fields

Multi-Package Fields

When using packages array:

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:

Each package within collection:

Format and Subtype Values

Format (Target AI Tool)

Subtype (Package Type)

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

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:

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:

{
  "name": "my-prompts-repo",
  "author": "Your Name",
  "license": "MIT",
  "packages": [
    {
      "name": "typescript-rules",
      "version": "1.0.0",
      "description": "TypeScript best practices",
      "format": "cursor",
      "subtype": "rule",
      "tags": ["typescript"],
      "files": [".cursor/rules/typescript.mdc"]
    }
  ],
  "collections": [
    {
      "id": "my-dev-setup",
      "name": "My Development Setup",
      "description": "Complete development setup with TypeScript and React",
      "version": "1.0.0",
      "category": "development",
      "tags": ["typescript", "react"],
      "packages": [
        {
          "packageId": "typescript-strict",
          "version": "^1.0.0",
          "required": true,
          "reason": "Enforces strict TypeScript type safety"
        },
        {
          "packageId": "react-best-practices",
          "version": "^2.0.0",
          "required": true
        }
      ]
    }
  ]
}

For more details on creating collections, see the PRPM documentation at https://docs.prpm.dev or run prpm help collections.

Summary: prpm.json can contain both packages (skills, agents, rules, slash-commands, etc.) and collections.

Lifecycle Scripts

IMPORTANT: 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, particularly for building TypeScript hooks before publishing.

When to Use Scripts

Primary use case: Building TypeScript Hooks

If your packages include Claude Code hooks written in TypeScript, you MUST build them to JavaScript before publishing:

{
  "name": "my-packages",
  "license": "MIT",
  "scripts": {
    "prepublishOnly": "cd packages/hooks && npm run build"
  },
  "packages": [
    {
      "name": "my-hook",
      "version": "1.0.0",
      "format": "claude",
      "subtype": "hook",
      "files": [
        ".claude/hooks/my-hook/hook.ts",
        ".claude/hooks/my-hook/hook.json",
        ".claude/hooks/my-hook/dist/hook.js"
      ]
    }
  ]
}

Available Script Types

Always use prepublishOnly instead of prepublish to avoid running builds when users install your packages.

prepublishOnly Examples

Single hook:

{
  "scripts": {
    "prepublishOnly": "cd .claude/hooks/my-hook && npm run build"
  }
}

Multiple hooks:

{
  "scripts": {
    "prepublishOnly": "cd .claude/hooks/hook-one && npm run build && cd ../hook-two && npm run build"
  }
}

With tests:

{
  "scripts": {
    "prepublishOnly": "npm test && cd packages/hooks && npm run build"
  }
}

What Happens During Publishing

When you run prpm publish:

1. PRPM checks for scripts.prepublishOnly in your prpm.json
2. If found, runs the script from the directory containing prpm.json
3. If script succeeds (exit code 0), publishing continues
4. If script fails (non-zero exit code), publishing is aborted

Script execution details:

• Working directory: Same directory as prpm.json
• Timeout: 5 minutes (300,000ms) default
• Environment: Inherits your shell's environment variables
• Output: Shown in real-time

Best Practices for Scripts

DO:

• ✅ Use prepublishOnly for building hooks
• ✅ Chain commands with && for dependencies: npm test && npm run build
• ✅ Keep scripts fast (under 1 minute if possible)
• ✅ Test scripts locally before publishing

DON'T:

• ❌ Use prepublish (runs on install too)
• ❌ Forget to build hooks before publishing
• ❌ Use scripts in single-package manifests (not supported)
• ❌ Put long-running operations in scripts

Common Patterns

Hooks in packages/ directory:

{
  "scripts": {
    "prepublishOnly": "cd packages/hooks && npm run build"
  }
}

Hooks in .claude/ directory:

{
  "scripts": {
    "prepublishOnly": "cd .claude/hooks/my-hook && npm run build"
  }
}

Build multiple components:

{
  "scripts": {
    "prepublishOnly": "npm run build:hooks && npm run build:assets"
  }
}

Debugging Script Failures

If your prepublishOnly script fails:

1. Check the output - Error messages show what went wrong
2. Run manually - Test the exact command in your terminal
3. Verify working directory - Scripts run from prpm.json location
4. Check dependencies - Ensure npm packages are installed

Example debugging:

# Test your prepublishOnly script manually
cd /path/to/prpm.json/directory
cd packages/hooks && npm run build

# If it works manually but fails in PRPM, check:
# - Working directory assumptions
# - Environment variables
# - Installed dependencies

Why This Matters

Without prepublishOnly:

• You might forget to build hooks before publishing
• Published packages contain stale/outdated JavaScript
• Users install broken hooks
• Manual builds are error-prone

With prepublishOnly:

• Hooks automatically build before every publish
• JavaScript always matches TypeScript source
• Prevents publishing broken code
• Consistent, reliable publishing workflow

Validation Checklist

Before publishing, verify:

Required Fields:

• All packages have name, version, description
• All packages have format and subtype
• All packages have files array
• Top-level has author and license

File Verification:

• All files in files arrays exist
• File paths are relative to repo root
• No missing or broken file references

No Duplicates:

• No duplicate package names
• Package names are unique across entire manifest

Tags:

• Tags use kebab-case
• 3-8 relevant tags per package
• Tags include technology, domain, and purpose

Organization:

• Private packages listed first
• Packages grouped by format and subtype
• Consistent versioning across related packages

Lockfile Management

Understanding prpm.lock

The prpm.lock file is auto-generated and tracks installed packages. It serves as the source of truth for what's installed in your project.

IMPORTANT: Do NOT add packages to prpm.json if they already exist in prpm.lock:

• prpm.lock tracks installed dependencies (packages you use)
• prpm.json defines published packages (packages you create and share)

When to Use prpm.json vs prpm.lock

Use prpm.json when:

• You're creating a package to publish to the registry
• You want to define metadata for YOUR packages
• You're setting up a multi-package repository

Use prpm.lock (auto-generated) when:

• You install packages with prpm install
• You want to track which packages are installed
• You want reproducible installations across environments

Common Mistake: Duplicating Dependencies

❌ WRONG - Don't add installed packages to prpm.json:

// prpm.json
{
  "name": "my-project",
  "packages": [
    {
      "name": "typescript-safety",  // ❌ This is an INSTALLED package
      "version": "1.0.0",
      "format": "cursor",
      "subtype": "rule",
      "files": [".cursor/rules/typescript-safety.mdc"]
    }
  ]
}

// prpm.lock (auto-generated)
{
  "packages": {
    "@prpm/typescript-safety": {  // ✅ Already tracked here
      "version": "1.0.0",
      "format": "cursor",
      "subtype": "rule"
    }
  }
}

✅ CORRECT - prpm.json only for YOUR packages:

// prpm.json - Only YOUR packages you're publishing
{
  "name": "my-project",
  "packages": [
    {
      "name": "my-custom-rule",  // ✅ This is YOUR package
      "version": "1.0.0",
      "format": "cursor",
      "subtype": "rule",
      "files": [".cursor/rules/my-custom-rule.mdc"]
    }
  ]
}

// prpm.lock - Installed dependencies (auto-generated)
{
  "packages": {
    "@prpm/typescript-safety": {  // ✅ Installed from registry
      "version": "1.0.0",
      "format": "cursor",
      "subtype": "rule"
    }
  }
}

Key Principles

1. Lockfile is Auto-Generated - Never manually edit prpm.lock
2. Separation of Concerns:
   • prpm.json = What you PUBLISH
   • prpm.lock = What you INSTALL
3. Check Lockfile First - Before adding to prpm.json, check if it's already in prpm.lock
4. Trust the Lockfile - It's the authoritative record of installed packages

Workflow Example

# Install a package (updates prpm.lock automatically)
prpm install @prpm/typescript-safety

# This creates/updates prpm.lock - DO NOT add to prpm.json!

# Only create prpm.json entries for packages YOU create:
# 1. Create your custom rule/skill/agent
# 2. Add entry to prpm.json
# 3. Publish with: prpm publish

Publishing Workflow

1. Validate Manifest

# Validate JSON syntax
cat prpm.json | jq . > /dev/null

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

# Verify files exist
# (see File Verification section)

2. Bump Versions

Update version numbers for changed packages.

3. Test Locally

# Test package installation
prpm install . --dry-run

4. Publish

# Publish all packages
prpm publish

# Or publish specific package
prpm publish --package my-skill

Common Mistakes to Avoid

❌ Missing Required Fields

{
  "name": "my-skill",
  // Missing: version, description, format, subtype, files
}

❌ Wrong Tag Format

{
  "tags": ["TypeScript", "Code_Quality", "bestPractices"]
  // Should be: ["typescript", "code-quality", "best-practices"]
}

❌ Duplicate Names

{
  "packages": [
    { "name": "my-skill", "format": "claude" },
    { "name": "my-skill", "format": "cursor" }
    // Second should be: "my-skill-rule" or similar
  ]
}

❌ Missing Files

{
  "files": [".claude/skills/my-skill/SKILL.md"]
  // But .claude/skills/my-skill/SKILL.md doesn't exist in the repo
}

❌ Absolute Paths

{
  "files": ["/Users/me/project/.claude/skills/my-skill/SKILL.md"]
  // Should be: ".claude/skills/my-skill/SKILL.md" (relative to project root)
}

❌ Missing Directory Prefix

{
  "files": ["agents/my-agent.md"]
  // Should be: ".claude/agents/my-agent.md" (include .claude/ prefix)
}

Remember

• prpm.json is only for publishing YOUR packages/collections, not for installed dependencies
• Never add packages from prpm.lock to prpm.json - they serve different purposes
• prpm.lock tracks what you INSTALL, prpm.json defines what you PUBLISH
• Use collections array to bundle existing packages (references by packageId)
• Use packages array to define packages with files
• Can combine both packages and collections in same repo
• Always validate before committing
• Keep versions in sync for related packages
• Use consistent, searchable tags
• Verify all file paths exist
• Check for duplicate names
• Follow semver for version management

Goal: Create maintainable, well-organized package manifests and curated collections that are easy to publish and discover in the PRPM registry.