PRPMJSON最佳实践Skill prpm-json-best-practices

PRPM JSON 最佳实践

您是创建和维护 PRPM（Prompt 包管理器）prpm.json 包清单的专家。您了解结构、必填字段、组织模式以及多包仓库的最佳实践。

应用此技能的时机

使用场景：

• 创建新的 prpm.json 清单以发布包
• 维护现有的 prpm.json 文件
• 组织多包仓库
• 添加或更新包元数据
• 确保包清单的质量和完整性

不适用场景：

• 用户配置文件（.prpmrc） - 这些是给用户的
• 锁文件（prpm.lock） - 这些由 PRPM 自动生成
• 常规包安装（用户不需要 prpm.json）
• 锁文件中已跟踪的依赖项

核心目的

prpm.json 仅在您发布包时需要。从注册表安装包的常规用户不需要此文件。

当您：

• 发布包到 PRPM 注册表
• 创建包集合
• 分发您自己的提示/规则/技能/代理
• 在单体仓库中管理多个相关包

文件结构

单包

查看 examples/single-package.json 了解完整结构。

关键字段： name, version, description, author, license, format, subtype, files

多包仓库

查看 examples/multi-package.json 了解完整结构。

使用场景： 从单个仓库发布多个相关包 关键区别： 顶层 packages 数组包含各个包定义

集合仓库

查看 examples/collections-repository.json 了解完整结构。

使用场景： 将现有的已发布包捆绑到策划的集合中 关键点：

• collections 数组通过 packageId 引用包（不是文件）
• 每个集合有 id, name, description, packages
• 包可以是 required: true（默认）或 false（可选）
• 使用版本范围（^1.0.0）或 latest
• 添加 reason 解释为什么包含包

包 + 集合（组合）

查看 examples/packages-with-collections.json 了解完整结构。

使用场景： 发布包 AND 创建捆绑它们的集合 关键点：

• 在 packages 数组中定义包和文件
• 在 collections 数组中引用这些包
• 集合可以引用本地包和外部包
• 从同一个仓库发布单个包和集合包

必填字段

顶层（单包）

字段	类型	必填	描述
name	string	是	包名称（kebab-case，注册表中唯一）
version	string	是	Semver 版本（例如，1.0.0）
description	string	是	包做什么的清晰描述
author	string	是	作者姓名和可选电子邮件
license	string	是	SPDX 许可证标识符（例如，MIT, Apache-2.0）
format	string	是	目标格式：claude, cursor, continue, windsurf 等
subtype	string	是	包类型：agent, skill, rule, slash-command, prompt, collection
files	string[]	是	要包含在包中的文件数组

可选顶层字段

字段	类型	描述
repository	string	Git 仓库 URL
organization	string	组织名称（用于 scoped 包）
homepage	string	包主页 URL
documentation	string	文档 URL
license_text	string	许可证文件的全文，用于适当的归属
license_url	string	仓库中许可证文件的 URL
tags	string[]	可搜索的标签（kebab-case）
keywords	string[]	其他关键词用于搜索
category	string	包类别
private	boolean	如果为 true，则不会发布到公共注册表
dependencies	object	包依赖项（名称：semver）
scripts	object	生命周期脚本（仅限多包）
eager	boolean	如果为 true，则技能/代理在会话开始时加载（不是按需）

多包字段

使用 packages 数组时：

字段	类型	必填	描述
name	string	是	唯一包名称
version	string	是	包版本
description	string	是	包描述
format	string	是	包格式
subtype	string	是	包子类型
tags	string[]	推荐	可搜索的标签
files	string[]	是	要包含的文件
private	boolean	否	标记为私有
eager	boolean	否	在会话开始时加载（仅限技能/代理）

集合字段

当使用 collections 数组时： 顶层（带集合的仓库）：

• name, version, description, author, license - 必填
• repository, organization - 推荐
• 注意：顶层不需要 format, subtype 或 files

每个集合对象：

字段	类型	必填	描述
id	string	是	唯一的集合标识符（kebab-case，3-100 个字符）
name	string	是	显示名称（3-100 个字符）
description	string	是	集合提供的内容（10-500 个字符）
packages	array	是	要包含的包数组（最少 1 个）
version	string	推荐	集合的语义版本
category	string	推荐	集合类别（开发，测试等）
tags	string[]	推荐	可搜索的标签（kebab-case，1-10 项）
icon	string	可选	表情符号或图标（最多 10 个字符）

集合中的每个包：

字段	类型	必填	描述
packageId	string	是	要包含的包
version	string	可选	版本范围（^1.0.0, ~2.1.0, 1.0.0, latest）
required	boolean	可选	包是否必需（默认：true）
reason	string	可选	为什么包含包（最多 200 个字符）

格式和子类型值

格式（目标 AI 工具）

格式	描述
claude	Claude 代码（代理，技能）
cursor	Cursor IDE（规则，MDC 文件）
continue	Continue.dev 扩展
windsurf	Windsurf IDE
copilot	GitHub Copilot
kiro	Kiro IDE
agents.md	Agents.md 格式
generic	通用/通用格式
mcp	模型上下文协议

子类型（包类型）

子类型	描述	典型格式
agent	自主代理	claude, agents.md
skill	特殊能力	claude
rule	IDE 规则和指南	cursor, windsurf
slash-command	斜杠命令	cursor, continue
prompt	提示模板	generic
collection	包集合	任何
chatmode	聊天模式	kiro
tool	MCP 工具	mcp

急切与懒加载

技能和代理可以配置为急切加载（在会话开始时）或懒加载（按需相关时）。

何时使用急切

使用 eager: true 时：

• 技能应该始终处于活动状态（编码标准，风格指南）
• 必须始终执行的关键行为
• 小型，基础技能，令牌成本很小

保持懒加载（默认）时：

• 特定上下文的专业技能
• 大型技能，具有显著的令牌开销
• 仅适用于某些文件类型的技能

在 prpm.json 中设置急切

包级别：

{
  "name": "code-style-enforcer",
  "version": "1.0.0",
  "format": "claude",
  "subtype": "skill",
  "eager": true,
  "files": [".claude/skills/code-style/SKILL.md"]
}

文件级别（增强文件格式）：

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

优先级

安装时，最终的急切设置由以下决定：

1. CLI 标志（--eager/--lazy） - 最高优先级
2. 文件级 eager 设置（增强文件）
3. 包级 eager 设置
4. 默认：懒加载（false）

适用子类型

子类型	支持急切
skill	是
agent	是
rule	否
slash-command	否
hook	否

急切加载仅影响渐进式披露格式（agents.md, gemini.md, claude.md, aider）。

标签最佳实践

标签结构

• 使用 kebab-case 用于所有标签
• 要 具体 和 可搜索
• 每个包包含 3-8 个标签
• 结合技术，领域和目的标签

标签类别

技术标签：

• 语言：typescript, python, javascript, rust
• 框架：react, nextjs, fastify, django
• 工具：aws, docker, kubernetes, postgresql

领域标签：

• deployment, testing, ci-cd, database
• infrastructure, cloud, monitoring
• documentation, code-review, security

目的标签：

• troubleshooting, debugging, best-practices
• automation, quality-assurance, performance
• architecture, design-patterns

元标签：

• meta - 用于关于创建包的包
• prpm-internal - 用于内部/私有包
• prpm-development - 用于 PRPM 本身的开发

标签示例

好的标签：

{
  "tags": [
    "typescript",
    "type-safety",
    "code-quality",
    "best-practices",
    "static-analysis"
  ]
}

差的标签：

{
  "tags": [
    "code",  // 太通用
    "stuff", // 无意义
    "TypeScript", // 错误的大小写
    "type_safety"  // 错误的格式（使用 kebab-case）
  ]
}

组织最佳实践

多包组织

按顺序组织包：

1. 隐私 - 私有包优先
2. 格式 - 按格式（claude, cursor 等）分组
3. 子类型 - 按子类型（代理，技能，规则）分组

示例组织：

{
  "packages": [
    // 私有 > Claude > 代理
    { "name": "internal-agent", "private": true, "format": "claude", "subtype": "agent" },

    // 私有 > Claude > 技能
    { "name": "internal-skill", "private": true, "format": "claude", "subtype": "skill" },

    // 私有 > Cursor > 规则
    { "name": "internal-rule", "private": true, "format": "cursor", "subtype": "rule" },

    // 公共 > Claude > 技能
    { "name": "public-skill", "format": "claude", "subtype": "skill" },

    // 公共 > Cursor > 规则
    { "name": "public-rule", "format": "cursor", "subtype": "rule" }
  ]
}

命名约定

包名称：

• 使用 kebab-case：my-awesome-skill
• 要 描述性：typescript-type-safety 不是 ts-types
• 避免跨格式重复：如果需要，使用后缀
  • format-conversion-agent（Claude 代理）
  • format-conversion（Cursor 规则）

文件路径：

• 使用 从项目根目录的完整路径（prpm.json 所在位置）
• 代理：.claude/agents/name.md
• 技能：.claude/skills/name/SKILL.md
• 规则：.cursor/rules/name.mdc
• 命令：.claude/commands/category/name.md

版本管理

Semver 指南

遵循语义化版本控制：

• 主要（1.0.0 → 2.0.0）：破坏性变更
• 次要（1.0.0 → 1.1.0）：新功能，向后兼容
• 修补（1.0.0 → 1.0.1）：修复错误，向后兼容

版本提升

提升版本的场景：

• 修补：错误修复，错别字更正，小改进
• 次要：新部分，附加示例，新功能
• 主要：完全重写，破坏性变更，重命名字段

保持版本同步

对于多包仓库，保持相关包的版本同步：

{
  "packages": [
    { "name": "pkg-one", "version": "1.2.0" },
    { "name": "pkg-two", "version": "1.2.0" },
    { "name": "pkg-three", "version": "1.2.0" }
  ]
}

文件管理

文件数组

关键：文件路径必须从项目根目录的完整路径。

必填：

• 列出要包含在包中的所有文件
• 使用 从项目根目录的完整路径 - 不是相对于目标目录
• 路径应以 .claude/, .cursor/ 等开头
• 包括文档文件

为什么完整路径？ prpm.json 中的文件路径用于：

1. Tarball 创建 - 直接从这些路径读取文件
2. 片段提取 - 安装前显示文件预览
3. 安装 - CLI 从格式/子类型推导目的地

示例：

Claude 代理（单文件）：

{
  "format": "claude",
  "subtype": "agent",
  "files": [".claude/agents/my-agent.md"]
}

Claude 技能（多个文件）：

{
  "format": "claude",
  "subtype": "skill",
  "files": [
    ".claude/skills/my-skill/SKILL.md",
    ".claude/skills/my-skill/EXAMPLES.md",
    ".claude/skills/my-skill/README.md"
  ]
}

Cursor 规则：

{
  "format": "cursor",
  "subtype": "rule",
  "files": [".cursor/rules/my-rule.mdc"]
}

Slash 命令：

{
  "format": "claude",
  "subtype": "slash-command",
  "files": [".claude/commands/category/my-command.md"]
}

增强文件格式

高级： 文件可以是带有元数据的对象，而不仅仅是简单的字符串。对于包含多个文件的目标不同格式或需要每个文件的元数据的包很有用。

增强文件对象结构：

{
  "files": [
    {
      "path": ".cursor/rules/typescript.mdc",
      "format": "cursor",
      "subtype": "rule",
      "name": "TypeScript 规则",
      "description": "TypeScript 编码标准和最佳实践",
      "tags": ["typescript", "frontend"]
    },
    {
      "path": ".cursor/rules/python.mdc",
      "format": "cursor",
      "subtype": "rule",
      "name": "Python 规则",
      "description": "Python 后端开发的最佳实践",
      "tags": ["python", "backend"]
    }
  ]
}

何时使用增强格式：

• 包含不同格式/子类型每个文件的多文件包
• 需要每个文件的描述或标签
• 想要为单个文件提供显示名称
• 构建包含混合内容类型的集合包

增强文件字段：

字段	必填	描述
path	是	从项目根目录到文件的相对路径
format	是	文件的目标格式（cursor, claude 等）
subtype	否	文件的子类型（rule, skill, agent 等）
name	否	此文件的显示名称
description	否	此文件的作用描述
tags	否	文件特定标签（字符串数组）

注意： 不能在同一 files 数组中混合简单字符串和对象。全部使用字符串 OR 全部使用对象，不能两者都使用。

常见错误：

{
  // ❌ 错误 - 没有目录前缀的相对路径
  "files": ["agents/my-agent.md"]  // 将无法找到文件

  // ✅ 正确 - 从项目根目录的完整路径
  "files": [".claude/agents/my-agent.md"]
}

文件验证

始终验证文件存在：

# 检查 prpm.json 中的所有文件是否存在
for file in $(cat prpm.json | jq -r '.packages[].files[]'); do
  if [ ! -f "$file" ]; then
    echo "Missing: $file"
  fi
done

重复检测

检查重复名称

提交前运行此检查：

# 检查包名称重复
cat prpm.json | jq -r '.packages[].name' | sort | uniq -d

如果输出为空，则没有重复。如果出现名称，则需要解决重复问题。

解决重复

不良：

{
  "packages": [
    { "name": "typescript-safety", "format": "claude" },
    { "name": "typescript-safety", "format": "cursor" }
  ]
}

良好：

{
  "packages": [
    { "name": "typescript-safety", "format": "claude", "subtype": "skill" },
    { "name": "typescript-safety-rule", "format": "cursor", "subtype": "rule" }
  ]
}

转换提示（高级）

目的： 帮助在转换包到其他格式时提高质量。conversion 字段为跨格式转换提供格式特定的提示。

注意： 这是高级功能，主要由格式转换工具使用。大多数包不需要此功能。

结构：

{
  "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"
    }
  }
}

支持的转换提示：

Cursor 提示

{
  "conversion": {
    "cursor": {
      "alwaysApply": boolean,      // 是否应始终应用规则
      "priority": "high|medium|low", // 规则优先级
      "globs": ["**/*.ts"]         // 自动附加的文件模式
    }
  }
}

Claude 提示

{
  "conversion": {
    "claude": {
      "model": "sonnet|opus|haiku|inherit", // 首选模型
      "tools": ["Read", "Write"],          // 允许的工具
      "subagentType": "format-conversion"  // 如果是代理，则为子代理类型
    }
  }
}

Kiro 提示

{
  "conversion": {
    "kiro": {
      "inclusion": "always|fileMatch|manual", // 何时包括
      "fileMatchPattern": "**/*.ts",         // fileMatch 模式的模式
      "domain": "typescript",                // 领域类别
      "tools": ["fs_read", "fs_write"],     // 可用工具
      "mcpServers": {                        // MCP 服务器配置
        "database": {
          "command": "mcp-server-postgres",
          "args": [],
          "env": { "DATABASE_URL": "${DATABASE_URL}" }
        }
      }
    }
  }
}

Copilot 提示

{
  "conversion": {
    "copilot": {
      "applyTo": "src/**",                         // 路径模式
      "excludeAgent": "code-review|coding-agent"  // 要排除的代理
    }
  }
}

Continue 提示

{
  "conversion": {
    "continue": {
      "alwaysApply": boolean,           // 始终应用规则
      "globs": ["**/*.ts"],             // 文件模式
      "regex": ["import.*from"]         // 正则表达式模式
    }
  }
}

Windsurf 提示

{
  "conversion": {
    "windsurf": {
      "characterLimit": 12000  // 超过限制时警告
    }
  }
}

Agents.md 提示

{
  "conversion": {
    "agentsMd": {
      "project": "my-project",  // 项目名称
      "scope": "backend"        // 范围/领域
    }
  }
}

何时使用转换提示：

• 发布需要特定设置的跨格式包
• 格式转换工具需要指导如何转换内容
• 基于目标格式更改包行为
• 在转换过程中保留格式特定的元数据

常见模式

私有内部包

{
  "name": "internal-tool",
  "version": "1.0.0",
  "description": "内部开发工具",
  "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": "创建有效的 Claude 代码技能指南",
  "format": "claude",
  "subtype": "skill",
  "tags": ["meta", "claude-code", "skills", "documentation", "best-practices"],
  "files": [".claude/skills/creating-skills/SKILL.md"]
}

跨格式包

当您有多个格式的相同内容时：

{
  "packages": [
    {
      "name": "format-conversion-agent",
      "format": "claude",
      "subtype": "agent",
      "description": "用于在 AI 提示格式之间转换的代理",
      "files": [".claude/agents/format-conversion.md"]
    },
    {
      "name": "format-conversion",
      "format": "cursor",
      "subtype": "rule",
      "description": "用于在 AI 提示格式之间转换的规则",
      "files": [".cursor/rules/format-conversion.mdc"]
    }
  ]
}

prpm.json 中的集合

集合可以在 prpm.json 中使用 collections 数组定义。集合将多个包捆绑在一起，便于安装。

包和集合示例：

{
  "name": "my-prompts-repo",
  "author": "您的姓名",
  "license": "MIT",
  "packages": [
    {
      "name": "typescript-rules",
      "version": "1.0.0",
      "description": "TypeScript 最佳实践",
      "format": "cursor",
      "subtype": "rule",
      "tags": ["typescript"],
      "files": [".cursor/rules/typescript.mdc"]
    }
  ],
  "collections": [
    {
      "id": "my-dev-setup",
      "name": "我的开发设置",
      "description": "完整的开发设置，包括 TypeScript 和 React",
      "version": "1.0.0",
      "category": "development",
      "tags": ["typescript", "react"],
      "packages": [
        {
          "packageId": "typescript-strict",
          "version": "^1.0.0",
          "required": true,
          "reason": "强制执行严格的 TypeScript 类型安全"
        },
        {
          "packageId": "react-best-practices",
          "version": "^2.0.0",
          "required": true
        }
      ]
    }
  ]
}

有关创建集合的更多详细信息，请访问 PRPM 文档 https://docs.prpm.dev 或运行 prpm help collections。

总结： prpm.json 可以包含包（技能，代理，规则，斜杠命令等）和集合。

生命周期脚本

重要： scripts 字段仅适用于 多包清单（带有 packages 数组的 prpm.json）。它不适用于单包清单。

使用 scripts 字段在包操作期间自动运行命令，特别是构建 TypeScript 钩子后再发布。

何时使用脚本

主要用途：构建 TypeScript 钩子

如果您的包包括用 TypeScript 编写的 Claude 代码钩子，则必须在发布前将它们构建为 JavaScript：

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

可用脚本类型

脚本	运行时	用例
prepublishOnly	仅在 prpm publish 之前运行	推荐 - 构建钩子，编译资产
prepublish	发布和 npm 安装之前运行	不推荐 - 导致意外的构建

总是使用 prepublishOnly 而不是 prepublish 以避免在用户安装您的包时运行构建。

prepublishOnly 示例

单个钩子：

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

多个钩子：

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

带测试：

{
  "scripts": {
    "prepublishOnly": "npm test && cd packages/hooks && npm run build"
  }
}

发布过程中会发生什么

当您运行 prpm publish 时：

1. PRPM 检查您的 prpm.json 中的 scripts.prepublishOnly
2. 如果找到，从包含 prpm.json 的目录运行脚本
3. 如果脚本成功（退出代码 0），则继续发布
4. 如果脚本失败（非零退出代码），则中止发布

脚本执行细节：

• 工作目录：与 prpm.json 相同的目录
• 超时：默认 5 分钟（300,000ms）
• 环境：继承您的 shell 环境变量
• 输出：实时显示

脚本最佳实践

要做：

• ✅ 使用 prepublishOnly 构建钩子
• ✅ 使用 && 链接命令以满足依赖关系：npm test && npm run build
• ✅ 保持脚本快速（如果可能，在 1 分钟以下）
• ✅ 在发布前在本地测试脚本

不要做：

• ❌ 使用 prepublish（也会在安装时运行）
• ❌ 发布前忘记构建钩子
• ❌ 在单包清单中使用脚本（不支持）
• ❌ 在脚本中放置长时间运行的操作

常见模式

packages/ 目录中的钩子：

{
  "scripts": {
    "prepublishOnly": "cd packages/hooks && npm run build"
  }
}

.claude/ 目录中的钩子：

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

构建多个组件：

{
  "scripts": {
    "prepublishOnly": "npm run build:hooks && npm run build:assets"
  }
}

调试脚本失败

如果您的 prepublishOnly 脚本失败：

1. 检查输出 - 错误消息会显示哪里出了问题
2. 手动运行 - 在您的终端中测试确切的命令
3. 验证工作目录 - 脚本从 prpm.json 位置运行
4. 检查依赖项 - 确保已安装 npm 包

示例调试：

# 手动测试您的 prepublishOnly 脚本
cd /path/to/prpm.json/directory
cd packages/hooks && npm run build

# 如果手动工作但在 PRPM 中失败，请检查：
# - 工作目录假设
# - 环境变量
# - 安装的依赖项

为什么这很重要

没有 prepublishOnly：

• 您可能会忘记在发布前构建钩子
• 发布的包包含过时/旧的 JavaScript
• 用户安装了损坏的钩子
• 手动构建容易出错

有 prepublishOnly：

• 钩子在每次发布前自动构建
• JavaScript 始终与 TypeScript 源匹配
• 防止发布损坏的代码
• 一致的，可靠的发布工作流程

验证清单

发布前验证：

必填字段：

• [ ] 所有包都有 name, version, description
• [ ] 所有包都有 format 和 subtype
• [ ] 所有包都有 files 数组
• [ ] 顶层有 author 和 license

文件验证：

• [ ] files 数组中的所有文件都存在
• [ ] 文件路径相对于存储库根目录
• [ ] 没有缺失或损坏的文件引用

没有重复：

• [ ] 没有重复的包名称
• [ ] 整个清单中的包名称是唯一的

标签：

• [ ] 标签使用 kebab-case
• [ ] 每个包有 3-8 个相关标签
• [ ] 标签包括技术，领域和目的

组织：

• [ ] 私有包首先列出
• [ ] 按格式和子类型分组的包
• [ ] 相关包的一致版本控制

锁文件管理

了解 prpm.lock

prpm.lock 文件是 自动生成的，并跟踪安装的包。它作为您项目中安装的包的真相来源。

重要： 不要将 prpm.lock 中的包添加到 prpm.json：

• prpm.lock 跟踪 安装的依赖项（您使用的包）
• prpm.json 定义 发布的包（您创建和共享的包）

prpm.json vs prpm.lock 的使用时机

使用 prpm.json 时：

• 您要创建要发布到注册表的包
• 您想要为您的包定义元数据
• 您正在设置多包仓库

使用 prpm.lock（自动生成）时：

• 您使用 prpm install 安装包
• 您想要跟踪哪些包已安装
• 您想要在不同环境中重现安装

常见错误：重复依赖

❌ 错误 - 不要将安装的包添加到 prpm.json：

// prpm.json
{
  "name": "my-project",
  "packages": [
    {
      "name": "typescript-safety",  // ❌ 这是安装的包
      "version": "1.0.0",
      "format": "cursor",
      "subtype": "rule",
      "files": [".cursor/rules/typescript-safety.mdc"]
    }
  ]
}

// prpm.lock（自动生成）
{
  "packages": {
    "@prpm/typescript-safety": {  // ✅ 已经在这里跟踪
      "version": "1.0.0",
      "format": "cursor",
      "subtype": "rule"
    }
  }
}

✅ 正确 - prpm.json 仅用于您的包：

// prpm.json - 只有您的包您正在发布
{
  "name": "my-project",
  "packages": [
    {
      "name": "my-custom-rule",  // ✅ 这是您的包
      "version": "1.0.0",
      "format": "cursor",
      "subtype": "rule",
      "files": [".cursor/rules/my-custom-rule.mdc"]
    }
  ]
}

// prpm.lock - 安装的依赖项（自动生成）
{
  "packages": {
    "@prpm/typescript-safety": {  // ✅ 从注册表安装
      "version": "1.0.0",
      "format": "cursor",
      "subtype": "rule"
    }
  }
}

核心原则

1. 锁文件是自动生成的 - 永远不要手动编辑 prpm.lock
2. 分离关注点：
   • prpm.json = 您要发布的
   • prpm.lock = 您要安装的
3. 首先检查锁文件 - 在添加到 prpm.json 之前，检查是否已经在 prpm.lock 中
4. 信任锁文件 - 它是安装包的权威记录

工作流程示例

# 安装包（自动更新 prpm.lock）
prpm install @prpm/typescript-safety

# 这会创建/更新 prpm.lock - 不要添加到 prpm.json！

# 只为您创建的包创建 prpm.json 条目：
# 1. 创建您的自定义规则/技能/代理
# 2. 将条目添加到 prpm.json
# 3. 发布：prpm publish

发布工作流程

1. 验证清单

# 验证 JSON 语法
cat prpm.json | jq . > /dev/null

# 检查重复项
cat prpm.json | jq -r '.packages[].name' | sort | uniq -d

# 验证文件存在
# （见文件验证部分）

2. 提升版本

更新已更改包的版本号。

3. 本地测试

# 测试包安装
prpm install . --dry-run

4. 发布

# 发布所有包
prpm publish

# 或发布特定包
prpm publish --package my-skill

常见错误

❌ 缺少必填字段

{
  "name": "my-skill",
  // 缺少：version, description, format, subtype, files
}

❌ 错误的标签格式

{
  "tags": ["TypeScript", "Code_Quality", "bestPractices"]
  // 应该是：["typescript", "code-quality", "best-practices"]
}

❌ 重复名称

{
  "packages": [
    { "name": "my-skill", "format": "claude" },
    { "name": "my-skill", "format": "cursor" }
    // 第二个应该是："my-skill-rule" 或类似
  ]
}

❌ 缺少文件

{
  "files": [".claude/skills/my-skill/SKILL.md"]
  // 但是 .claude/skills/my-skill/SKILL.md 在存储库中不存在
}

❌ 绝对路径

{
  "files": ["/Users/me/project/.claude/skills/my-skill/SKILL.md"]
  // 应该是：".claude/skills/my-skill/SKILL.md"（相对于项目根目录）
}

❌ 缺少目录前缀

{
  "files": ["agents/my-agent.md"]
  // 应该是：".claude/agents/my-agent.md"（包括 .claude/ 前缀）
}

记住

• prpm.json 仅用于发布您的包/集合，不用于安装的依赖项
• 永远不要将 prpm.lock 中的包添加到 prpm.json - 它们服务于不同的目的
• prpm.lock 跟踪您 安装 的，prpm.json 定义您 发布 的
• 使用 collections 数组捆绑现有的包（按 packageId 引用）
• 使用 packages 数组定义带有文件的包
• 可以在同一个存储库中组合 packages 和 collections
• 总是在提交前验证
• 保持相关包的版本同步
• 使用一致的，可搜索的标签
• 验证所有文件路径存在
• 检查重复名称
• 遵循 semver 进行版本管理

目标： 创建可维护的，组织良好的包清单和策划的集合，便于在 PRPM 注册表中发布和发现。