메뉴
Best practices for structuring prpm.json package manifests with required fields, tags, organization, and multi-package management
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/NangoHQ/ai-ide-prompts --skill prpm-json-best-practices명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SOC 직업 분류 기준
SKILL.md 표시 중
| name | PRPM JSON Best Practices |
| description | Best practices for structuring prpm.json package manifests with required fields, tags, organization, and multi-package management |
| author | PRPM Team |
| version | 1.0.0 |
| tags | ["prpm","package-management","json","manifest","best-practices","publishing"] |
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.
Use when:
prpm.json manifest for publishing packagesprpm.json filesDon't use for:
.prpmrc) - those are for usersprpm.lock) - those are auto-generated by PRPMprpm.json)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:
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"
]
}
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"]
}
]
}
| 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 |
| Field | Type | Description |
|---|---|---|
repository | string | Git repository URL |
organization | string | Organization name (for scoped packages) |
homepage | string | Package homepage URL |
documentation | string | Documentation URL |
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) |
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 |
| 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 | 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 |
Technology Tags:
typescript, python, javascript, rustreact, nextjs, fastify, djangoaws, docker, kubernetes, postgresqlDomain Tags:
deployment, testing, ci-cd, databaseinfrastructure, cloud, monitoringdocumentation, code-review, securityPurpose Tags:
troubleshooting, debugging, best-practicesautomation, quality-assurance, performancearchitecture, design-patternsMeta Tags:
meta - For packages about creating packagesprpm-internal - For internal/private packagesprpm-development - For PRPM development itselfGood 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)
]
}
Order packages by:
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" }
]
}
Package Names:
my-awesome-skilltypescript-type-safety not ts-typesformat-conversion-agent (Claude agent)format-conversion (Cursor rule)File Paths:
.claude/agents/name.md.claude/skills/name/SKILL.md.cursor/rules/name.mdc.claude/commands/category/name.mdFollow semantic versioning:
When to bump versions:
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" }
]
}
CRITICAL: File paths must be full paths from project root (where prpm.json lives).
Required:
.claude/, .cursor/, etc.Why Full Paths?
File paths in prpm.json are used for:
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"]
}
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"]
}
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
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.
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" }
]
}
{
"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"]
}
{
"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"]
}
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"]
}
]
}
Before publishing, verify:
Required Fields:
name, version, descriptionformat and subtypefiles arrayauthor and licenseFile Verification:
files arrays existNo Duplicates:
Tags:
Organization:
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)Use prpm.json when:
Use prpm.lock (auto-generated) when:
prpm install❌ 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"
}
}
}
prpm.lockprpm.json = What you PUBLISHprpm.lock = What you INSTALLprpm.json, check if it's already in prpm.lock# 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
# 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)
Update version numbers for changed packages.
# Test package installation
prpm install . --dry-run
# Publish all packages
prpm publish
# Or publish specific package
prpm publish --package my-skill
{
"name": "my-skill",
// Missing: version, description, format, subtype, files
}
{
"tags": ["TypeScript", "Code_Quality", "bestPractices"]
// Should be: ["typescript", "code-quality", "best-practices"]
}
{
"packages": [
{ "name": "my-skill", "format": "claude" },
{ "name": "my-skill", "format": "cursor" }
// Second should be: "my-skill-rule" or similar
]
}
{
"files": [".claude/skills/my-skill/SKILL.md"]
// But .claude/skills/my-skill/SKILL.md doesn't exist in the repo
}
{
"files": ["/Users/me/project/.claude/skills/my-skill/SKILL.md"]
// Should be: ".claude/skills/my-skill/SKILL.md" (relative to project root)
}
{
"files": ["agents/my-agent.md"]
// Should be: ".claude/agents/my-agent.md" (include .claude/ prefix)
}
prpm.json is only for publishing YOUR packages, not for installed dependenciesprpm.lock to prpm.json - they serve different purposesprpm.lock tracks what you INSTALL, prpm.json defines what you PUBLISHGoal: 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.