PRPM JSON Best Practices 是一份面向 PRPM(Prompt Package Manager)包清单 prpm.json 的编写与维护规范,主要用于发布提示词、规则、技能和智能体等 AI 开发资源包。
用途与适用时机 仅在发布包时使用 prpm.json:向 PRPM 注册表发布包、创建包集合、分发自己的 prompts/rules/skills/agents、在 monorepo 中管理多个相关包,或维护并更新已有清单的元数据与质量。普通用户安装包不需要 prpm.json;用户配置文件 .prpmrc、锁文件 prpm.lock 以及已由锁文件跟踪的依赖不适用本技能。
文件结构与必填字段 单包清单的必填字段包括:name(kebab-case,注册表内唯一)、version(语义化版本)、description、author(可含邮箱)、license(SPDX 标识符)、format(目标 AI 工具格式)、subtype(包类型)、files(文件数组)。可选顶层字段有 repository、organization、homepage、documentation、tags、keywords、category、private、dependencies。多包仓库使用 packages 数组,其中每个包需提供 name、version、description、format、subtype、files,tags 为推荐项,private 可选。
format 与 subtype 取值 format 包括 claude、cursor、continue、windsurf、copilot、kiro、agents.md、generic、mcp;subtype 包括 agent、skill、rule、slash-command、prompt、collection、chatmode、tool,并给出了常见搭配,如 agent 对应 claude/agents.md,rule 对应 cursor/windsurf,tool 对应 mcp。
标签规范 标签统一使用 kebab-case,每个包建议 3-8 个,覆盖技术(语言、框架、工具)、领域(部署、测试、安全等)、用途(排错、最佳实践、性能等)和元标签(meta、prpm-internal、prpm-development)。应避免过泛、无意义、大小写错误或下划线格式的标签。
组织与命名 多包仓库建议按 private、format、subtype 的顺序分组排列。包名使用 kebab-case 且具描述性;同一内容跨格式时用后缀区分,例如 format-conversion-agent 与 format-conversion。文件路径必须是从项目根目录(prpm.json 所在处)开始的完整路径,以 .claude/、.cursor/ 等开头,如 .claude/agents/name.md、.claude/skills/name/SKILL.md、.cursor/rules/name.mdc,避免绝对路径或缺失目录前缀。
版本与文件管理 遵循语义化版本:破坏性变更为 major,向后兼容的新功能为 minor,缺陷修复为 patch;相关包版本保持同步。files 数组需列出全部待打包文件,路径用于创建 tarball、片段预览和安装时推导目标位置,发布前应逐一验证文件存在。
重复检测与校验清单 发布前用 jq 检查 JSON 语法、包名重复(sort | uniq -d)和文件缺失,确认必填字段、文件路径、标签格式、组织顺序和版本一致性。跨格式同名包需重命名消歧。
锁文件与发布流程 prpm.lock 由 PRPM 自动生成,记录已安装包,是安装状态的权威来源,不可手动编辑;不要把已安装依赖写入 prpm.json,二者职责分离:prpm.json 定义你发布的包,prpm.lock 记录你安装的包。发布流程为:校验清单、升级版本、本地以 prpm install . --dry-run 测试、再用 prpm publish(或 --package 指定单个包)发布。
限制与注意事项 资料未提供 PRPM 的收费、平台支持范围、性能效果等信息;本技能只是文档规范,不保证发布成功。需避免缺失必填字段、标签格式错误、重名、文件不存在、绝对路径和缺少目录前缀等常见错误。