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
For repositories with one package:
{"name":"my-awesome-skill","version":"1.0.0","description":"Clear, concise description of what this package does","author":"Your Name <you@example.com>","license":"MIT","repository":"https://github.com/username/repo","organization":"your-org","format":"claude","subtype":"skill","tags":["typescript","best-practices","code-quality"],"files":[".claude/skills/my-awesome-skill/SKILL.md"]}
Multi-Package Repository
For repositories with multiple packages (like this one):
{"name":"prpm-packages","version":"1.0.0","author":"Your Name","license":"MIT","repository":"https://github.com/username/repo","organization":"your-org","packages":[{"name":"package-one","version":"1.0.0","description":"Description of package one","private":true,"format":"claude","subtype":"agent","tags":["tag1","tag2"],"files":[".claude/agents/package-one.md"]},{"name":"package-two","version":"1.0.0","description":"Description of package two","format":"cursor","subtype":"rule","tags":["tag1","tag3"],"files":[".cursor/rules/package-two.mdc"]}]}
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.
{// ❌ 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 existfor file in $(cat prpm.json | jq -r '.packages[].files[]'); doif [ ! -f "$file" ]; thenecho"Missing: $file"fidone
{"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"]}]}
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.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
Lockfile is Auto-Generated - Never manually edit prpm.lock
Separation of Concerns:
prpm.json = What you PUBLISH
prpm.lock = What you INSTALL
Check Lockfile First - Before adding to prpm.json, check if it's already in prpm.lock
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
# 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, 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
Always validate before committing
Keep versions in sync for related packages
Use consistent, searchable tags
Organize packages logically (private > format > subtype)
Verify all file paths exist
Check for duplicate names
Follow semver for version management
Goal: Create maintainable, well-organized package manifests that are easy to publish and discover in the PRPM registry, while keeping installed dependencies separate in prpm.lock.
