Loading
Also from Kynth Studios
Also from Kynth Studios
Also from Kynth Studios
1234567# PRPM JSON Best Practices89Best practices for creating and maintaining `prpm.json` package manifests for PRPM (Prompt Package Manager).1011## Core Purpose1213`prpm.json` is **only needed if you're publishing packages**. Regular users installing packages from the registry don't need this file.1415Use `prpm.json` when you're:16- Publishing a package to the PRPM registry17- Creating a collection of packages18- Distributing your own prompts/rules/skills/agents19- Managing multiple related packages in a monorepo2021## File Structure2223### Single Package2425```json26{27 "name": "my-awesome-skill",28 "version": "1.0.0",29 "description": "Clear, concise description of what this package does",30 "author": "Your Name <you@example.com>",31 "license": "MIT",32 "repository": "https://github.com/username/repo",33 "organization": "your-org",34 "format": "claude",35 "subtype": "skill",36 "tags": ["typescript", "best-practices", "code-quality"],37 "files": [38 "SKILL.md"39 ]40}41```4243**Note:** When `"organization": "your-org"` is specified, the registry automatically prefixes the package name with `@your-org/`, so this package will be published as `@your-org/my-awesome-skill` and installed with `prpm install @your-org/my-awesome-skill`.4445### Multi-Package Repository4647```json48{49 "name": "prpm-packages",50 "version": "1.0.0",51 "author": "Your Name",52 "license": "MIT",53 "repository": "https://github.com/username/repo",54 "organization": "your-org",55 "packages": [56 {57 "name": "package-one",58 "version": "1.0.0",59 "description": "Description of package one",60 "private": true,61 "format": "claude",62 "subtype": "agent",63 "tags": ["tag1", "tag2"],64 "files": [".claude/agents/package-one.md"]65 }66 ]67}68```6970## Required Fields7172### Single Package7374| Field | Type | Required | Description |75|-------|------|----------|-------------|76| `name` | string | **Yes** | Package name (kebab-case, unique in registry) |77| `version` | string | **Yes** | Semver version (e.g., `1.0.0`) |78| `description` | string | **Yes** | Clear description of what the package does |79| `author` | string | **Yes** | Author name and optional email |80| `license` | string | **Yes** | SPDX license identifier (e.g., `MIT`) |81| `format` | string | **Yes** | Target format: `claude`, `cursor`, `continue`, `windsurf` |82| `subtype` | string | **Yes** | Package type: `agent`, `skill`, `rule`, `slash-command`, `prompt` |83| `files` | string[] | **Yes** | Array of files to include in package |8485### Multi-Package8687Each package in `packages` array requires:88- `name`, `version`, `description` - Package identity89- `format`, `subtype` - Package classification90- `files` - Files to include91- `tags` - Recommended for discoverability9293## Format and Subtype Values9495### Format (Target AI Tool)9697- `claude` - Claude Code (agents, skills)98- `cursor` - Cursor IDE (rules, MDC files)99- `continue` - Continue.dev extension100- `windsurf` - Windsurf IDE101- `copilot`, `kiro`, `agents.md`, `generic`, `mcp`102103### Subtype (Package Type)104105- `agent` - Autonomous agents (Claude, agents.md)106- `skill` - Specialized capabilities (Claude)107- `rule` - IDE rules and guidelines (Cursor, Windsurf)108- `slash-command`, `prompt`, `collection`, `chatmode`, `tool`109110## Tags Best Practices111112### Structure113114- Use **kebab-case**: `type-safety` not `typeSafety` or `type_safety`115- Include 3-8 tags per package116- Combine technology + domain + purpose tags117118### Categories119120**Technology:** `typescript`, `python`, `react`, `aws`, `postgresql`121**Domain:** `deployment`, `testing`, `database`, `infrastructure`122**Purpose:** `troubleshooting`, `best-practices`, `automation`123**Meta:** `meta` (packages about packages), `prpm-internal` (private)124125### Good Example126127```json128{129 "tags": [130 "typescript",131 "type-safety",132 "code-quality",133 "best-practices",134 "static-analysis"135 ]136}137```138139## Organization Best Practices140141### Multi-Package Order142143Organize packages by:1441. **Privacy** - Private packages first1452. **Format** - Group by format (claude, cursor)1463. **Subtype** - Group by subtype (agent, skill, rule)147148```json149{150 "packages": [151 // Private > Claude > Agents152 { "name": "internal-agent", "private": true, "format": "claude", "subtype": "agent" },153154 // Private > Claude > Skills155 { "name": "internal-skill", "private": true, "format": "claude", "subtype": "skill" },156157 // Private > Cursor > Rules158 { "name": "internal-rule", "private": true, "format": "cursor", "subtype": "rule" },159160 // Public > Claude > Skills161 { "name": "public-skill", "format": "claude", "subtype": "skill" },162163 // Public > Cursor > Rules164 { "name": "public-rule", "format": "cursor", "subtype": "rule" }165 ]166}167```168169### Naming Conventions170171**Package Names:**172- Use **kebab-case**: `my-awesome-skill`173- Be **descriptive**: `typescript-type-safety` not `ts-types`174- Avoid duplicates: use suffixes if needed175 - `format-conversion-agent` (Claude agent)176 - `format-conversion` (Cursor rule)177178**File Paths:**179- Agents: `agents/name.md`180- Skills: `skills/name/SKILL.md`181- Rules: `rules/name.mdc`182183## Version Management184185### Semver186187- **Major (1.0.0 → 2.0.0)**: Breaking changes188- **Minor (1.0.0 → 1.1.0)**: New features, backward compatible189- **Patch (1.0.0 → 1.0.1)**: Bug fixes, backward compatible190191### Keep Related Packages in Sync192193```json194{195 "packages": [196 { "name": "pkg-one", "version": "1.2.0" },197 { "name": "pkg-two", "version": "1.2.0" },198 { "name": "pkg-three", "version": "1.2.0" }199 ]200}201```202203## File Management204205### Files Array206207List all files to include in the package:208209```json210{211 "files": [212 "skills/my-skill/SKILL.md",213 "skills/my-skill/examples/",214 "skills/my-skill/README.md"215 ]216}217```218219### Verify Files Exist220221```bash222# Check all files exist223for file in $(cat prpm.json | jq -r '.packages[].files[]'); do224 if [ ! -f "$file" ]; then225 echo "Missing: $file"226 fi227done228```229230## Duplicate Detection231232### Check for Duplicates233234```bash235# No output = no duplicates236cat prpm.json | jq -r '.packages[].name' | sort | uniq -d237```238239### Resolve Duplicates240241❌ **Bad:**242```json243{ "packages": [244 { "name": "typescript-safety", "format": "claude" },245 { "name": "typescript-safety", "format": "cursor" }246]}247```248249✅ **Good:**250```json251{ "packages": [252 { "name": "typescript-safety", "format": "claude", "subtype": "skill" },253 { "name": "typescript-safety-rule", "format": "cursor", "subtype": "rule" }254]}255```256257## Common Patterns258259### Private Internal Package260261```json262{263 "name": "internal-tool",264 "version": "1.0.0",265 "description": "Internal development tool",266 "private": true,267 "format": "claude",268 "subtype": "skill",269 "tags": ["prpm-internal", "development"],270 "files": [".claude/skills/internal-tool/SKILL.md"]271}272```273274### Meta Package (Creating Other Packages)275276```json277{278 "name": "creating-skills",279 "version": "1.0.0",280 "description": "Guide for creating effective Claude Code skills",281 "format": "claude",282 "subtype": "skill",283 "tags": ["meta", "claude-code", "skills", "documentation"],284 "files": [".claude/skills/creating-skills/SKILL.md"]285}286```287288### Collections in prpm.json289290Collections CAN be defined in prpm.json alongside packages using the `collections` array. Collections bundle multiple packages together for easier installation.291292**Example with both packages and collections:**293294```json295{296 "name": "my-prompts-repo",297 "author": "Your Name",298 "license": "MIT",299 "packages": [300 {301 "name": "typescript-rules",302 "version": "1.0.0",303 "description": "TypeScript best practices",304 "format": "cursor",305 "subtype": "rule",306 "tags": ["typescript"],307 "files": [".cursor/rules/typescript.mdc"]308 }309 ],310 "collections": [311 {312 "id": "my-dev-setup",313 "name": "My Development Setup",314 "description": "Complete development setup with TypeScript and React",315 "version": "1.0.0",316 "category": "development",317 "tags": ["typescript", "react"],318 "packages": [319 {320 "packageId": "typescript-strict",321 "version": "^1.0.0",322 "required": true,323 "reason": "Enforces strict TypeScript type safety"324 },325 {326 "packageId": "react-best-practices",327 "version": "^2.0.0",328 "required": true329 }330 ]331 }332 ]333}334```335336For more details on creating collections, see the PRPM documentation at https://docs.prpm.dev or run `prpm help collections`.337338## Validation Checklist339340Before publishing:341342**Required Fields:**343- [ ] All packages have `name`, `version`, `description`344- [ ] All packages have `format` and `subtype`345- [ ] All packages have `files` array346- [ ] Top-level has `author` and `license`347348**File Verification:**349- [ ] All files in `files` arrays exist350- [ ] File paths use full paths from project root (e.g., `.claude/agents/name.md`)351- [ ] Paths start with `.claude/`, `.cursor/`, etc. (not just `agents/` or `skills/`)352353**No Duplicates:**354- [ ] No duplicate package names355356**Tags:**357- [ ] Tags use kebab-case358- [ ] 3-8 relevant tags per package359360**Organization:**361- [ ] Private packages listed first362- [ ] Packages grouped by format and subtype363364## Common Mistakes365366### ❌ Missing Required Fields367368```json369{370 "name": "my-skill"371 // Missing: version, description, format, subtype, files372}373```374375### ❌ Wrong Tag Format376377```json378{379 "tags": ["TypeScript", "Code_Quality"]380 // Should be: ["typescript", "code-quality"]381}382```383384### ❌ Duplicate Names385386```json387{388 "packages": [389 { "name": "my-skill", "format": "claude" },390 { "name": "my-skill", "format": "cursor" }391 // Add suffix: "my-skill-rule"392 ]393}394```395396### ❌ Missing Files397398```json399{400 "files": ["SKILL.md"]401 // But SKILL.md doesn't exist402}403```404405## Lockfile Management406407### Understanding prpm.lock408409The `prpm.lock` file is **auto-generated** and tracks installed packages. It's the source of truth for what's installed.410411**CRITICAL:** Do NOT add packages to `prpm.json` if they exist in `prpm.lock`:412413- `prpm.lock` tracks **installed dependencies** (packages you use)414- `prpm.json` defines **published packages** (packages you create)415416### When to Use Each File417418**Use `prpm.json` when:**419- Creating a package to publish to the registry420- Defining metadata for YOUR packages421- Setting up a multi-package repository422423**Use `prpm.lock` (auto-generated) when:**424- Installing packages with `prpm install`425- Tracking which packages are installed426- Ensuring reproducible installations427428### Common Mistake: Duplicating Dependencies429430❌ **WRONG - Don't add installed packages to prpm.json:**431432```json433// prpm.json434{435 "packages": [436 {437 "name": "typescript-safety", // ❌ This is INSTALLED438 "version": "1.0.0",439 "files": [".cursor/rules/typescript-safety.mdc"]440 }441 ]442}443444// prpm.lock (auto-generated)445{446 "packages": {447 "@prpm/typescript-safety": { // ✅ Already here448 "version": "1.0.0"449 }450 }451}452```453454✅ **CORRECT - Only YOUR packages in prpm.json:**455456```json457// prpm.json - Only packages you're publishing458{459 "packages": [460 {461 "name": "my-custom-rule", // ✅ YOUR package462 "version": "1.0.0",463 "files": [".cursor/rules/my-custom-rule.mdc"]464 }465 ]466}467468// prpm.lock - Installed dependencies469{470 "packages": {471 "@prpm/typescript-safety": { // ✅ Installed472 "version": "1.0.0"473 }474 }475}476```477478### Key Principles4794801. **Lockfile is Auto-Generated** - Never manually edit `prpm.lock`4812. **Separation of Concerns**:482 - `prpm.json` = What you PUBLISH483 - `prpm.lock` = What you INSTALL4843. **Check Lockfile First** - Before adding to `prpm.json`, check `prpm.lock`4854. **Trust the Lockfile** - It's authoritative for installed packages486487### Workflow488489```bash490# Install a package (updates prpm.lock automatically)491prpm install @prpm/typescript-safety492493# DO NOT add to prpm.json!494495# Only add to prpm.json when YOU create a package:496# 1. Create your custom rule/skill/agent497# 2. Add entry to prpm.json498# 3. Publish: prpm publish499```500501## Publishing Workflow502503### 1. Validate Manifest504505```bash506# Validate JSON507cat prpm.json | jq . > /dev/null508509# Check duplicates510cat prpm.json | jq -r '.packages[].name' | sort | uniq -d511512# Verify files exist (see File Management section)513```514515### 2. Bump Versions516517Update version numbers for changed packages.518519### 3. Publish520521```bash522# Publish all packages523prpm publish524525# Or specific package526prpm publish --package my-skill527```528529## Remember530531- `prpm.json` is **only for publishing YOUR packages**, not installed dependencies532- **Never add packages from `prpm.lock` to `prpm.json`** - different purposes533- `prpm.lock` = What you INSTALL, `prpm.json` = What you PUBLISH534- Always validate before committing535- Keep versions in sync for related packages536- Use consistent, searchable tags537- Organize packages logically538- Verify all file paths exist539- Check for duplicate names540- Follow semver for versioning541
One repository carrying more than one format is the comparison this product exists for: does anyone actually write different content in each file, or is one a copy of the other?
| Repository | Format | Stack | Covers | Score | Changed |
|---|---|---|---|---|---|
| pr-pm/prpm.cursor/rules/testing-patterns.mdc · 121 | Cursor rules | testlint-formatstyletesting-strategy | 77/100 | 14 days ago | |
| pr-pm/prpm.cursor/rules/beanstalk-deploy.mdc · 121 | Cursor rules | teststyletypes | 62/100 | 14 days ago | |
| pr-pm/prpm.cursor/rules/core-principles.mdc · 121 | Cursor rules | testlint-formatstylearch+6 | 69/100 | 14 days ago | |
| pr-pm/prpm.cursor/rules/creating-agents-md.mdc · 121 | Cursor rules | testlint-formatstylearch+7 | 92/100 | 14 days ago | |
| pr-pm/prpm.cursor/rules/creating-cursor-rules.mdc · 121 | Cursor rules | testlint-formatstylearch+5 | 76/100 | 14 days ago | |
| pr-pm/prpm.cursor/rules/creating-skills.mdc · 121 | Cursor rules | stylearchtesting-strategydo-not+1 | 61/100 | 14 days ago | |
| pr-pm/prpm.cursor/rules/github-actions-testing.mdc · 121 | Cursor rules | setupbuildstylearch+4 | 93/100 | 14 days ago | |
| pr-pm/prpm.cursor/rules/karen-repo-reviewer.mdc · 121 | Cursor rules | archgit | 58/100 | 14 days ago | |
| pr-pm/prpm.cursor/rules/self-improve-cursor.mdc · 121 | Cursor rules | setuptestarchdependencies+3 | 69/100 | 14 days ago | |
| pr-pm/prpm.cursor/rules/typescript-type-safety.mdc · 121 | Cursor rules | buildstylearchtypes+2 | 89/100 | 14 days ago | |
| pr-pm/prpm.cursor/rules/typescript-type-specialist.mdc · 121 | Cursor rules | styletypesdo-notagent-behaviour | 65/100 | 14 days ago | |
| pr-pm/prpmAGENTS.md · 121 | AGENTS.md | setupbuildtestlint-format+12 | 84/100 | 14 days ago | |
| pr-pm/prpmCLAUDE.md · 121 | CLAUDE.md | teststylegitapi+2 | 69/100 | 14 days ago | |
| pr-pm/prpm.cursor/rules/creating-kiro-agents.mdc · 121 | Cursor rules | setupbuildteststyle+5 | 76/100 | 14 days ago | |
| pr-pm/prpm.cursor/rules/format-conversion.mdc · 121 | Cursor rules | testlint-formatstyledo-not+1 | 63/100 | 14 days ago |
Same format, overlapping stack, ranked by quality.
| Repository | Format | Stack | Covers | Score | Changed |
|---|---|---|---|---|---|
| hiromaily/go-crypto-wallet.cursor/rules/typescript.mdc · 126 | Cursor rules | setupbuildtestlint-format+6 | 100/100 | 14 days ago | |
| TechSquidTV/Hermes.cursor/rules/10-hermes-api.mdc · 46 | Cursor rules | testlint-formatstylearch+5 | 100/100 | 14 days ago | |
| Allymahmoud/case-intake-platform.cursor/rules/frontend.mdc · 0 | Cursor rules | setuptestlint-formatstyle+7 | 99/100 | 14 days ago | |
| dodgecfr/combatfilms-webapp.cursor/rules/frontend.mdc · 0 | Cursor rules | setuptestlint-formatstyle+7 | 99/100 | 14 days ago | |
| deifos/clipmira-subtitles.cursor/rules/frontend.mdc · 1 | Cursor rules | setuptestlint-formatstyle+7 | 99/100 | 14 days ago | |
| markstev/mark-starter.cursor/rules/frontend.mdc · 0 | Cursor rules | setuptestlint-formatstyle+6 | 99/100 | 14 days ago | |
| langflow-ai/langflow.cursor/rules/docs_development.mdc · 153k | Cursor rules | setupbuildtestlint-format+7 | 97/100 | 14 days ago | |
| bybren-llc/safe-agentic-workflow.cursor/rules/10-backend-python.mdc · 399 | Cursor rules | testlint-formatstylegit+4 | 97/100 | today |
A badge carrying the measured quality of the strongest agent config file in this repository, out of 100. It reads from this index every time somebody loads your page, so it changes when the measurement changes and there is nothing to keep up to date. Free, no account, and the value is not something you or we can set by hand.
[](https://rulestack.kynth.studio/configs/pr-pm-prpm-cursor-rules-prpm-json-best-practices)Would rather not hotlink us? Every badge is also served in shields.io’s endpoint schema, so shields renders the image and your readers never talk to our domain:
Published by Toolproof, the masthead over this index and eight others. The method behind the number is at toolproof.kynth.studio/methodology, and the whole thing is readable as JSON with no key at /api.