如何为pm-skills贡献一个新技能？完整开发流程与验证脚本使用指南
如何为pm-skills贡献一个新技能？完整开发流程与验证脚本使用指南
【免费下载链接】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
pm-skills（PM Skills Marketplace）是一个面向产品管理者的 AI 技能市场，收录了 9 大插件、68 个技能与 42 个命令。想为 pm-skills 贡献一个新技能并不复杂：按现有目录结构编写 SKILL.md、遵循 frontmatter 规范、最后运行官方验证脚本 validate_plugins.py 即可。本文带你走完整条开发流程，让你第一次提交 PR 就能顺利通过审查。
快速了解 pm-skills 的项目结构
动手前先搞清楚"技能"和"命令"的区别，这是贡献指南 CONTRIBUTING.md 中最重要的两条约定：
| 概念 | 比喻 | 存放位置 | 加载方式 |
|---|---|---|---|
| Skill（技能） | 名词：领域知识 | skills/{技能名}/SKILL.md | 话题相关时自动加载 |
| Command（命令） | 动词：工作流 | commands/{命令名}.md | 用户通过/命令名触发 |
以 pm-data-analytics 插件为例，它的技能 sql-queries 负责"自然语言转 SQL"的领域知识，而命令 write-query.md 则把该技能串成/write-query工作流。两者各司其职，很多命令还会复用同一个技能。
贡献前的第一步：选对入口
CONTRIBUTING.md 对贡献渠道有明确分工：
- Bug、错别字等小改动—— 直接开 PR
- 新技能、新命令或较大改动—— 先开一个 Issue 讨论方案，再动手
同时记住两条硬性规范：
- 每个技能必须有 YAML frontmatter，包含
name和description； - 技能的
name必须与目录名完全一致。
仓库结构约定详见 CLAUDE.md，它是项目维护的唯一事实来源，每个插件都遵循相同的骨架：
pm-{插件名}/ ├── .claude-plugin/plugin.json ← 插件清单 ├── skills/{技能名}/SKILL.md ← 一个技能一个文件夹 ├── commands/{命令名}.md ← 一个命令一个文件 └── README.md ← 插件说明文档五步完成一个新技能的开发
第 1 步：克隆仓库
git clone https://gitcode.com/GitHub_Trending/pm/pm-skills cd pm-skills第 2 步：创建技能目录与 SKILL.md
在目标插件下新建skills/你的技能名/目录，并创建 SKILL.md。frontmatter 是最容易出错的地方，参考 validate_plugins.py 的校验规则，正确写法是：
--- name: your-skill-name description: "技能是做什么的。Use when 什么场景下触发该技能。" --- # 技能标题 正文写框架步骤、使用示例……三个细节决定成败：
name必须与目录名一字不差；description建议 30 字符以上，并包含 "use when / use for" 等触发词，AI 才会在对的时机加载它；- 正文保持在 50~3000 词之间，过长可拆分到 references/ 子目录做渐进式披露。
第 3 步：（可选）编写配套命令
若需要一个/命令来驱动该技能，在commands/下新建.md文件，frontmatter 需要description和argument-hint两个字段。注意：命令中禁止硬引用其他插件，跨插件的后续步骤只能用自然语言建议（如"要不要我帮你设计增长循环？"）。
第 4 步：同步文档与版本号
按 CLAUDE.md 的运维流程，新增/删除技能后要做三件事：
- 更新对应插件 README 和根 README.md 中的技能计数；
- 同步 .claude-plugin/marketplace.json 中的总数描述；
- 统一提升版本号——所有插件与 marketplace.json 必须保持同一版本（当前均为 2.0.0）。
第 5 步：运行验证脚本 validate_plugins.py
这是提交前的最后一道关卡，也是 pm-skills 对每个贡献者的明确要求。
验证脚本 validate_plugins.py 使用指南
在仓库根目录执行：
python3 validate_plugins.py可选地传入目录参数来校验指定位置：python3 validate_plugins.py /路径/。脚本会自动找出所有包含.claude-plugin/的插件目录并逐一检查，退出码为 0 表示全部通过。
它到底检查了什么？
| 检查项 | 错误（必须修） | 警告（建议修） |
|---|---|---|
| 插件清单 plugin.json | 缺少 name/version/description、名称与目录不符 | 版本不符合 semver、缺少 keywords、author 字段不全 |
| 技能 SKILL.md | 缺 frontmatter、缺 name/description、名称与目录不符 | 描述过短、正文过长（>3000 词）或过短（<50 词） |
| 命令 .md | 缺 frontmatter、缺 description | 缺少推荐字段 argument-hint |
| 交叉引用 | — | 命令引用了本插件中不存在的技能 |
报告末尾会给出✓ ALL CHECKS PASSED或✗ N ERRORS的总结。只要出现 ERROR，PR 大概率会被打回；WARN 不阻断合并，但建议一并处理。脚本的完整校验逻辑可查阅 validate_plugins.py。
提交前自检清单 ✅
- 技能
name与目录名一致 - frontmatter 必填字段齐全（技能：name+description；命令：description+argument-hint）
- 描述包含触发词，长度达标
- 没有跨插件硬引用
- 插件 README 与根 README 计数已更新
- 各插件版本号与 marketplace.json 保持同步
python3 validate_plugins.py零错误- PR 聚焦单一改动（一个 PR 只做一个变更）
常见问题
Q：我的贡献会被署名吗？会。CONTRIBUTING.md 明确每位贡献者都会被公开列出，且贡献按 LICENSE（MIT）授权。
Q：只想贡献纯技能，不想写命令，可以吗？完全可以。像 prioritization-frameworks 这类技能就是独立的参考型知识，AI 在相关话题下会自动调用，无需任何命令。
Q：Windows 上验证脚本中文/特殊字符显示异常？脚本已内置 Windows UTF-8 输出兼容处理，直接运行即可。
掌握"技能是名词、命令是动词"的核心心智模型，再加上验证脚本这道自动门禁，你为 pm-skills 贡献的第一个新技能很快就会合入。动手前记得：先开 Issue 讨论，保持 PR 聚焦，验证通过再提交 🚀
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考