prpm-json-best-practices

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 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: CLI flag ( --eager / --lazy ) - highest priority File-level eager setting (enhanced files) Package-level eager setting Default: lazy (false)