企业官网建设流程全解析

PM Skills Marketplace 贡献指南：从 frontmatter 规范到自动化校验的插件开发实战

【免费下载链接】pm-skillsPM Skills Marketplace: 100+ agentic skills, commands, and plugins — from discovery to strategy, execution, launch, and growth.项目地址: https://gitcode.com/GitHub_Trending/pm/pm-skills

本文以CONTRIBUTING.md为骨架，系统讲解 PM Skills Marketplace（9 个插件、68 个技能、42 个命令的 PM 技能市场）的贡献流程、技能/命令/插件的目录结构与 frontmatter 规范、命名约束、跨插件引用禁令，并结合仓库根目录的 validate_plugins.py 校验器源码，深入剖析每一项规则背后的自动化实现与判定逻辑。读完本文，你将能独立提交一个符合规范、可通过校验的 skill 或 command，并掌握该仓库为保障插件兼容性而设计的工程约束。

一、仓库是什么：技能市场的基本架构

在动手贡献之前，先理解 PM Skills Marketplace 的三层结构（详见仓库根目录 README.md 与 CLAUDE.md）：

• Skills（名词）：领域知识与分析框架，Claude 在对话相关时自动加载，无需显式调用。例如 pm-execution/skills/create-prd/SKILL.md 是完整的 PRD 撰写框架，pm-execution/skills/pre-mortem 是风险预演框架。
• Commands（动词）：用户以/command-name触发的端到端工作流，一个命令往往串联多个技能。例如 pm-execution/commands/write-prd.md 会调用create-prd技能产出 8 段式 PRD。
• Plugins（插件）：将同领域的技能与命令打包成可安装单元。仓库共 9 个插件，每个插件目录形如pm-execution/，内含.claude-plugin/plugin.json清单、skills/与commands/子目录及独立 README.md。

为什么贡献规范如此强调"名词 vs 动词"？因为这是整个市场被 AI 助手（Claude Code、Cowork、Codex CLI 等）正确解析的根基：技能是"被自动加载的知识"，命令是"用户显式触发的流程"，二者的加载时机与触发方式完全不同。

二、贡献流程：先开 issue 还是直接提 PR？

CONTRIBUTING.md 给出了两条清晰的分流规则：

仓库维护者是 Paweł Huryn（pawel@productcompass.pm，来自 The Product Compass Newsletter）。值得注意：每位贡献者都会被公开列出，这也是开源署名文化的一部分。

结合 CLAUDE.md 中的运维规范，一次完整的贡献通常还包含隐性的后续步骤：

1. 改动技能/命令后，运行校验器：python3 validate_plugins.py
2. 若增删了技能或命令，同步更新README.md中的计数
3. 若总量变化，同步更新marketplace.json描述中的计数
4. 按版本同步规则统一 bump 版本号（详见下文第六节）

三、核心规范一：frontmatter 的必填与推荐字段

CONTRIBUTING.md 明确要求：

Every skill needs frontmatter withnameanddescription. Every command needsdescriptionandargument-hint.

这两条规则在 validate_plugins.py 中以配置常量形式落地（第 36-41 行）：

# Required skill frontmatter fields REQUIRED_SKILL_FIELDS = ["name", "description"] # Required command frontmatter fields REQUIRED_COMMAND_FIELDS = ["description"] RECOMMENDED_COMMAND_FIELDS = ["argument-hint"]

注意其中的层级差异：技能的name+description均为必填；命令的description为必填，argument-hint虽在贡献指南中被要求，但在校验器中属于推荐字段（缺失只产生 warning 而非 error）。

3.1 技能 frontmatter 实例

以 pm-execution/skills/create-prd/SKILL.md 的真实 frontmatter 为例：

--- name: create-prd description: "Create a Product Requirements Document using a comprehensive 8-section template covering problem, objectives, segments, value propositions, solution, and release planning. Use when writing a PRD, documenting product requirements, preparing a feature spec, or reviewing an existing PRD." ---

校验器对description的判定细节（validate_plugins.py 第 210-228 行）：

• 长度 < 30 字符 → warning（"Description is very short"）
• 不含触发短语（trigger、use when、use for）→ info 提示（"Description lacks explicit trigger phrases"）
• 全文词数 > 3000 → 提示过长，建议使用渐进式披露（progressive disclosure），将细节放入references/引用文件
• 全文词数 < 50 → warning，内容过少

实践要点：技能的description应包含"何时使用该技能"的触发语义。例如create-prd的描述中 "Use when writing a PRD..." 正是为了让 Claude 在对话涉及 PRD 撰写时自动加载该技能。

3.2 命令 frontmatter 实例

以 pm-execution/commands/write-prd.md 为例：

--- description: Create a comprehensive Product Requirements Document from a feature idea or problem statement argument-hint: "<feature or problem statement>" ---

argument-hint是命令的"参数提示"，用户在终端输入/write-prd时，Claude Code 会展示<feature or problem statement>作为参数占位提示。校验器对命令描述长度要求相对宽松（< 10 字符才告警，第 257 行），因为命令描述面向的是"短而可执行"。

渐进式披露原则（CLAUDE.md 明确说明）：frontmatter 是"始终加载"的部分，必须保持精简；详细步骤放在 SKILL.md 正文中（被触发时才加载）。这正是create-prd将 8 段模板放在正文而非 frontmatter 的原因。

四、核心规范二：name必须匹配目录名

Skillnamemust match its directory name.

这条约定源自 agentskills.io 规范（校验器 docstring 中有明确标注）。校验器在 validate_plugins.py 第 206-208 行 强制执行：

# Name must match directory name (agentskills.io spec) if fm.get("name") and fm["name"] != skill_name: result.error(f"Name mismatch: frontmatter says '{fm['name']}' but directory is '{skill_name}'")

同理，插件的plugin.json中的name也必须匹配插件目录名（第 137-140 行）。这意味着目录名、frontmattername、manifestname三者必须完全一致，例如目录pm-execution/skills/create-prd/↔ frontmattername: create-prd↔ manifestname: pm-execution。

五、核心规范三：命令禁止跨插件引用

No cross-plugin references in commands. Suggest follow-ups in natural language only.

这是仓库最重要的架构约束之一，其背后有明确的工程理由（CLAUDE.md 第 50-51 行）：插件是独立安装的单元——用户可能只装了pm-execution而没有装pm-marketing-growth。若write-prd.md里硬编码了对/growth-strategy这类其他插件命令的引用，用户实际未安装该插件时引用就会失效。

因此命令的"后续建议"必须以自然语言形式出现。以 pm-execution/commands/write-prd.md 第 101-108 行为例，PRD 生成后建议的后续动作全部是自然语言问句：

• "Should Irun a pre-mortemon this PRD?"
• "Want me tobreak this into user storiesfor engineering?"

校验器对此有专门的交叉引用检查（validate_plugins.py 第 289-310 行）：它扫描命令正文中形如**skill-name** skill的模式，若引用的技能不在同一插件内，则发出 warning（"references skill X not found in this plugin"）。而同插件内的引用是允许的——因为同一插件的技能与命令总是捆绑发布（CLAUDE.md 第 51 行 "Intra-plugin 'Uses' references are fine"）。

六、提交前的守门员：运行校验器

CONTRIBUTING.md 要求提交前必须执行：

python3 validate_plugins.py

校验器从仓库根目录运行，自动发现所有包含.claude-plugin/目录的插件（第 483-486 行），对每个插件执行五类检查（第 315-353 行）：

6.1 理解输出：三级告警与退出码

校验器将结果分为三级（第 96-113 行）：

• ERROR（✗）：必须修复。存在任何 error 时，该插件显示 FAIL，脚本最终以退出码 1 结束（第 501-503 行），可作为 CI 门禁。
• WARN（⚠）：应当修复，如描述过短、版本号不符合x.y.zsemver、README 缺失、跨插件技能引用、技能字数异常等。
• INFO（ℹ）：仅供参考，如技能字数统计、引用的技能清单、作者推荐字段缺失等。

一个值得了解的细节：frontmatter 解析器（parse_yaml_frontmatter）是"简易实现"——仅支持扁平的key: value行式 YAML，以---分隔。因此 frontmatter 中请保持扁平结构，不要使用嵌套 YAML 或复杂类型，否则可能被误判。

6.2 校验器判断依赖的权威依据

校验器的行为严格对齐 Claude Code 插件规范（plugin.json清单格式）、agentskills.io 规范（skill 命名）与 Claude Code plugins 参考文档，这些依据在脚本头部 docstring（第 7-15 行）中一一列出。这意味着：通过该校验器，基本等同于满足 Anthropic 生态的插件合规要求。

七、完整清单：一次合格贡献的自检表

综合 CONTRIBUTING.md 与 CLAUDE.md，提交前请逐项核对：

结构层面

• 新技能：在pm-{plugin}/skills/{skill-name}/SKILL.md建目录与文件
• 新命令：在pm-{plugin}/commands/{command-name}.md建文件
• 技能是名词（领域知识），命令是动词（工作流）

frontmatter 层面

• 技能含name+description，name与目录名完全一致
• 命令含description+argument-hint
• description 含触发短语（"Use when..."），保持精简（渐进式披露）

引用与内容层面

• 命令中不硬编码其他插件的命令/技能引用，后续建议用自然语言
• 同插件内的技能引用使用**skill-name** skill格式

同步与验证层面

• python3 validate_plugins.py无 ERROR
• 增删技能/命令后更新根 README.md 与各插件 README 中的计数
• 总量变化时同步marketplace.json描述
• 统一 bump 版本号（当前全部为 2.0.0，marketplace.json与 9 个plugin.json必须同步，不可单独升级某个插件）

八、许可证与贡献者署名

CONTRIBUTING.md 明确：贡献即表示同意贡献内容遵循 MIT License。仓库的 LICENSE 采用标准 MIT 协议（Copyright (c) 2026 Pawel Huryn），允许自由使用、复制、修改、合并、发布、分发、再许可和销售，前提是保留上述版权声明与许可声明。同时每位贡献者都会被公开列出，请确保 PR 描述中准确署名。

结语

CONTRIBUTING.md 虽然篇幅精炼，却浓缩了这个技能市场的全部"架构宪法"：名词/动词二分法决定了内容组织方式，frontmatter 必填字段保证了 AI 助手的自动加载与参数提示能力，name 匹配目录约束维护了引用链路的确定性，跨插件引用禁令保障了插件独立安装的健壮性，而 validate_plugins.py 则把这一切固化为可自动执行的检查。遵循本文梳理的规范与自检清单，你的贡献就能在提交的第一时间通过校验，并长期稳定运行在 Claude Code、Cowork 及其他兼容生态中。

【免费下载链接】pm-skillsPM Skills Marketplace: 100+ agentic skills, commands, and plugins — from discovery to strategy, execution, launch, and growth.项目地址: https://gitcode.com/GitHub_Trending/pm/pm-skills