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)

| 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 (enhanced files format):**
```json
{
  "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:**
```json
{
  "tags": [
    "typescript",
    "type-safety",
    "code-quality",
    "best-practices",
    "static-analysis"
  ]
}
```

**Poor Tags:**
```json
{
  "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:**

```json
{
  "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:
```json
{
  "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):
```json
{
  "format": "claude",
  "subtype": "agent",
  "files": [".claude/agents/my-agent.md"]
}
```

Claude skill (multiple files):
```json
{
  "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:
```json
{
  "format": "cursor",
  "subtype": "rule",
  "files": [".cursor/rules/my-rule.mdc"]
}
```

Slash command:
```json
{
  "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:**
```json
{
  "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:**
```json
{
  // ❌ 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:
```bash
# 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:

```bash
# 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:**
```json
{
  "packages": [
    { "name": "typescript-safety", "format": "claude" },
    { "name": "typescript-safety", "format": "cursor" }
  ]
}
```

**Good:**
```json
{
  "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:**

```json
{
  "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
```json
{
  "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
```json
{
  "conversion": {
    "claude": {
      "model": "sonnet|opus|haiku|inherit", // Preferred model
      "tools": ["Read", "Write"],          // Allowed tools
      "subagentType": "format-conversion"  // Subagent type if agent
    }
  }
}
```

### Kiro Hints
```json
{
  "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
```json
{
  "conversion": {
    "copilot": {
      "applyTo": "src/**",                         // Path patterns
      "excludeAgent": "code-review|coding-agent"  // Agent to exclude
    }
  }
}
```

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

### Windsurf Hints
```json
{
  "conversion": {
    "windsurf": {
      "characterLimit": 12000  // Warn if exceeding limit
    }
  }
}
```

### Agents.md Hints
```json
{
  "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

```json
{
  "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)

```json
{
  "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:

```json
{
  "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:**

```json
{
  "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:

```json
{
  "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

| Script | When it Runs | Use Case |
|--------|--------------|----------|
| `prepublishOnly` | Before `prpm publish` only | **Recommended** - Build hooks, compile assets |
| `prepublish` | Before publish AND on npm install | **Not recommended** - causes unexpected builds |

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

### prepublishOnly Examples

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

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

**With tests:**
```json
{
  "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:**
```json
{
  "scripts": {
    "prepublishOnly": "cd packages/hooks && npm run build"
  }
}
```

**Hooks in .claude/ directory:**
```json
{
  "scripts": {
    "prepublishOnly": "cd .claude/hooks/my-hook && npm run build"
  }
}
```

**Build multiple components:**
```json
{
  "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:**
```bash
# 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:**

```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"]
    }
  ]
}
```

```json
// 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:**

```json
// 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"]
    }
  ]
}
```

```json
// 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

```bash
# 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

```bash
# 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

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

### 4. Publish

```bash
# Publish all packages
prpm publish

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

## Common Mistakes to Avoid

### ❌ Missing Required Fields

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

### ❌ Wrong Tag Format

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

### ❌ Duplicate Names

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

### ❌ Missing Files

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

### ❌ Absolute Paths

```json
{
  "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

```json
{
  "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.