概述

pm-skills 是一个面向产品经理（Product Manager）的技能框架与文档站点，托管于 GitHub 仓库 product-on-purpose/pm-skills。该项目旨在将产品管理工作中常见的流程拆解为可复用的技能（Skills）、标准化的工作流（Workflows）以及可自动化执行的子代理（Sub-agents）。

资料来源：package.json:2

技术栈

pm-skills 基于现代前端技术构建文档站点，核心技术选型如下：

项目要求 Node.js 版本不低于 22.12.0，采用 ES Module（"type": "module"）规范。

资料来源：package.json:3-18

核心架构

pm-skills 的架构围绕三大核心概念展开：工作流（Workflows）、技能（Skills） 和 子代理（Sub-agents）。

graph TD
    A[pm-skills 项目] --> B[Workflows 工作流]
    A --> C[Skills 技能库]
    A --> D[Sub-agents 子代理]
    
    B --> B1[多技能引导序列]
    B --> B2[PM 标准流程定义]
    
    C --> C1[define-hypothesis]
    C --> C2[更多技能模块]
    
    D --> D1[pm-critic 评审代理]
    D --> D2[pm-skill-auditor 审计代理]
    D --> D3[pm-changelog-curator 变更日志代理]
    D --> D4[pm-release-conductor 发布代理]

资料来源：_workflows/README.md:1-10

内容组织

文档结构

项目采用 Astro Starlight 构建文档站点，内容目录结构如下：

内容配置支持通过 glob 模式加载 Markdown/MDX 文件，并自动排除以下内容：

• docs/internal/：Gitignored 的发布计划与内部笔记
• docs/templates/：包含 <placeholder> 语法的模板文件
• docs//README.md：GitHub 目录自动渲染页面（避免重复）
• 遗留样本文件：符合 sample_*_legacy_* 或 sample_*_orbit_* 模式的文件

资料来源：src/content.config.ts:1-80

技能输出样本

library/skill-output-samples/ 目录包含真实场景下的子代理输出样本，用于展示各子代理的标准输出格式与行为模式。

每个样本包含：

• Frontmatter 元数据：title、description、artifact、version、repo_version、agent_version、created、status、thread、context
• Scenario 场景：触发子代理的背景信息
• Output 输出：子代理的实际输出内容
• Notes 笔记：样本的演示说明

资料来源：library/sub-agent-samples/README.md:1-30

子代理体系

代理分类

叙事线程

子代理输出跨越三个叙事线程，用于验证代理在不同产品场景下的一致性表现：

资料来源：library/sub-agent-samples/README.md:80-100

工作流定义

_workflows/ 目录采用 Markdown 格式定义多技能工作流，每个文件描述一个产品管理流程的引导式技能序列。

链接约定

工作流文件使用 仓库相对路径 引用技能：

[`define-hypothesis`](../skills/define-hypothesis/SKILL.md)

此约定确保 AI 代理（Copilot、Cursor、Windsurf）和仓库浏览器可直接解析链接。

资料来源：_workflows/README.md:8-15

编辑规范

工作流内容直接在 _workflows/ 目录编辑，不要直接修改 docs/workflows/，后者由 scripts/generate-workflow-pages.py 脚本自动生成。

AI 代理工作区

_agent-context/codex/ 目录定义了 Codex 工作区的策略规范：

持久化文件（Git 跟踪）

本地文件（Git 忽略）

资料来源：_agent-context/codex/README.md:1-40

样式与渲染

自定义样式

项目通过 src/styles/custom.css 实现 Starlight 主题定制：

• Mermaid 图表：最大宽度 100%，SVG 高度自适应
• 图表优化：线条宽度 1.75px、节点圆角 6px、聚类填充透明度 0.4

主题变量

Astro 配置文件中定义了 Mermaid 主题变量（lineColor 与 fontFamily），确保图表在浅色与深色模式下的一致呈现。

资料来源：src/styles/custom.css:1-35

构建流程

NPM 脚本

构建流程包含后处理步骤 scripts/post-build-strip-md-links.mjs，用于清理生成的 Markdown 链接。

资料来源：package.json:7-12

扩展字段

内容配置为文档和样本定义了丰富的 Frontmatter 扩展字段：

资料来源：src/content.config.ts:50-75

快速开始

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 生产构建
npm run build

访问本地开发服务器（默认 http://localhost:4321）查看文档站点。

概述

pm-skills 是一个面向产品经理（PM）的技能库与文档站点，基于 Astro Starlight 构建。该项目为产品管理全生命周期提供结构化的技能指导，覆盖从发现机会到持续迭代的完整流程。

技能库采用 Markdown 文件组织，每个技能独立成篇，支持 AI 代理（如 Copilot、Cursor、Windsurf）直接调用和解析。

资料来源：package.json:3-7

技能库架构

技能分类

技能库按产品管理流程阶段划分为七大类别：

资料来源：src/content.config.ts:15-25

目录结构

技能文件采用统一目录布局，每个技能目录下包含核心文档：

skills/
├── discover/
│   └── SKILL.md
├── define/
│   ├── define-hypothesis/
│   │   └── SKILL.md
│   └── SKILL.md
├── develop/
├── deliver/
├── measure/
├── iterate/
└── foundation/

技能文件使用 repo-relative 路径 进行内部引用，确保 AI 代理和仓库浏览器直接解析：

[`define-hypothesis`](../skills/define-hypothesis/SKILL.md)

资料来源：_workflows/README.md:9-13

内容加载机制

Astro 内容集合配置

技能库通过 Astro 内容集合加载，支持 Markdown 和 MDX 格式：

loader: glob({
  pattern: [
    'docs/**/*.{md,mdx}',
    '!docs/internal/**',
    '!docs/templates/**',
    '!docs/**/README.md',
    'library/skill-output-samples/**/sample_*.md',
  ],
  base: '.',
})

资料来源：src/content.config.ts:15-25

Slug 生成规则

系统自动处理路径转换，生成干净的 URL slug：

资料来源：src/content.config.ts:26-40

技能内容 Schema

通用字段

每个技能文档支持以下标准 frontmatter 字段：

资料来源：src/content.config.ts:45-60

技能输出样本库

样本分类

技能库包含真实场景的技能输出样本，按三个叙事线程组织：

资料来源：library/sub-agent-samples/README.md:85-90

子代理能力

技能库通过子代理扩展功能，每个子代理专注于特定任务：

资料来源：library/sub-agent-samples/README.md:17-24

工作流集成

工作流定义

工作流是多技能的有序组合，定义产品管理常见流程：

[`define-hypothesis`](../skills/define-hypothesis/SKILL.md)

每个 .md 文件定义一个多技能工作流，指导 AI 代理完成完整的产品管理流程。

资料来源：_workflows/README.md:5-10

工作流与技能关系

graph TD
    A[工作流定义] --> B[discover 技能]
    A --> C[define 技能]
    A --> D[develop 技能]
    A --> E[deliver 技能]
    A --> F[measure 技能]
    A --> G[iterate 技能]
    
    B --> H[pm-critic 评审]
    C --> H
    D --> H
    E --> H
    F --> H
    G --> H
    
    H --> I[pm-skill-auditor 审计]
    I --> J[pm-changelog-curator 变更整理]
    J --> K[pm-release-conductor 发布]

可视化样式

Mermaid 图表集成

技能库全面支持 Mermaid 图表，通过 astro-mermaid 集成：

{
  "astro-mermaid": "~2.0.1",
  "overrides": {
    "mermaid": "^11.15.0"
  }
}

资料来源：package.json:18-22

图表样式定制

自定义样式提供更好的可读性：

.mermaid .edgePath path,
.mermaid .flowchart-link {
  stroke-width: 1.75px;
}
.mermaid .node rect {
  rx: 6;
  ry: 6;
}
.mermaid .cluster rect {
  fill-opacity: 0.4;
}

资料来源：src/styles/custom.css:14-25

文档生成与发布

构建流程

项目使用自动化构建流程：

{
  "build": "astro build && node scripts/post-build-strip-md-links.mjs"
}

构建后脚本移除 Markdown 链接，生成最终静态站点。

资料来源：package.json:12

节点版本要求

{
  "engines": {
    "node": ">=22.12.0"
  }
}

资料来源：package.json:8

快速入门

1. 浏览技能：访问 /skills/ 目录查看所有可用技能
2. 选择阶段：根据产品管理流程阶段选择对应技能
3. 查看样本：参考 /samples/ 目录中的实际输出样本
4. 使用工作流：通过 /workflows/ 中的工作流串联多个技能

相关资源

• 子代理库样本 - 各子代理的真实输出示例
• 工作流定义 - 多技能组合的工作流
• 发布运行手册 - 发布流程指南

概述

技能（Skill）是 pm-skills 项目中 PM（产品经理）工作流程的核心执行单元。每个技能定义了一个具体的、可复用的产品管理实践或决策框架，供 AI Agent 在不同场景下调用。技能以 Markdown 文件形式存储在仓库的 skills/ 目录下，具有标准化的结构、元数据和引用机制。

技能的设计目标是使 PM 工作流程原子化、可组合、可追溯。通过统一的技能格式，AI Agent（如 Codex、Claude）能够理解并执行从需求假设定义到产品决策验证的完整链条。

技能核心结构

文件组成

一个完整的技能包含以下文件：

资料来源：docs/templates/skill-template/SKILL.md

主文件元数据（Frontmatter）

每个技能的主文件必须包含 YAML frontmatter，定义技能的身份信息：

概述

pm-skills 项目采用分层分类体系来组织产品管理技能（PM Skills），通过技能家族（Skill Families）和技能契约（Skills Contract）机制实现技能的结构化管理。该体系是项目架构的核心支柱，为 AI 代理提供标准化的技能调用接口和一致性的输出格式。

技能分类体系的核心目标是：

• 建立产品管理领域的技能分类标准
• 为不同叙事线程（Threads）提供统一的技能调用框架
• 通过技能契约确保子代理输出的结构一致性

资料来源：library/sub-agent-samples/README.md

技能家族架构

技能家族定义

技能家族是相关技能的逻辑分组，每个家族定义了特定产品管理场景下的技能集合。根据项目结构，主要的技能家族包括：

资料来源：docs/reference/skill-families/index.md

技能契约机制

技能契约（Skills Contract）是定义技能家族行为规范的核心文档，每个契约包含：

graph TD
    A[技能契约] --> B[输入规范]
    A --> C[输出格式]
    A --> D[状态封装]
    A --> E[评级标准]
    
    B --> B1[工件类型]
    B --> B2[上下文要求]
    
    C --> C1[结构化输出]
    C --> C2[元数据字段]
    
    D --> D1[Status 信封]
    D --> D2[分类标签]
    
    E --> E1[P0-P3 优先级]
    E --> E2[验收标准]

资料来源：docs/reference/skill-families/design-sprint-skills-contract.md

技能契约类型详解

Foundation Sprint 技能契约

Foundation Sprint 技能家族聚焦于产品管理的基础活动，涵盖从概念到验证的完整链路。

#### 核心技能

#### 契约规范

Foundation Sprint 技能契约定义了标准化的输入输出格式。输入端接受工件（Artifact）类型，包括产品需求文档、OKR 设置、用户研究数据等。输出端采用分层状态封装（Status Envelope）模式，确保子代理输出的一致性。

资料来源：docs/reference/skill-families/foundation-sprint-skills-contract.md

Design Sprint 技能契约

Design Sprint 技能家族服务于快速设计和验证流程，强调短周期、高密度的迭代模式。

#### 契约特点

graph LR
    A[问题定义] --> B[原型设计]
    B --> C[用户测试]
    C --> D[数据分析]
    D -->|快速反馈| A
    
    E[Design Sprint 契约] --> F[时限约束]
    E --> G[原型标准]
    E --> H[测试协议]

Design Sprint 契约相比 Foundation Sprint 增加了以下约束：

• 时限约束：明确规定各阶段的完成时间窗口
• 原型标准：定义可测试原型的最低要求
• 测试协议：标准化用户测试的流程和数据收集方式

资料来源：docs/reference/skill-families/design-sprint-skills-contract.md

Meeting Skills 契约

Meeting Skills 家族专注于会议相关的技能定义和输出规范。

#### 契约结构

资料来源：docs/reference/skill-families/meeting-skills-contract.md

分类维度

按叙事线程分类

pm-skills 围绕三个叙事线程组织内容，每个线程代表不同的产品管理上下文：

graph TD
    P[产品管理技能] --> B[Brainshelf]
    P --> S[Storevine]
    P --> W[Workbench]
    
    B --> B1[消费者 PKM 应用]
    B --> B2[个人知识管理]
    
    S --> S1[B2B 活动分析]
    S --> S2[数据产品管理]
    
    W --> W1[内部平台工具]
    W --> W2[开发者体验]

• Brainshelf：面向消费者的个人知识管理应用场景
• Storevine：B2B 活动分析平台的产品管理场景
• Workbench：内部平台工具团队的开发者体验场景

资料来源：library/sub-agent-samples/README.md

按子代理分类

系统中的四个核心子代理分别承担不同的评审和执行职责：

资料来源：library/sub-agent-samples/README.md

分类元数据

Frontmatter 字段

技能文档和样本输出使用统一的 frontmatter 字段定义：

资料来源：src/content.config.ts

分类标识系统

项目采用分层分类标识系统，通过 classification 字段区分不同类型的技能定义：

graph TD
    C[Classification] --> C1[skill]
    C --> C2[sub-agent]
    C --> C3[workflow]
    C --> C4[sample]
    
    C1 --> C1A[foundation]
    C1 --> C1B[design-sprint]
    C1 --> C1C[meeting]
    
    C2 --> C2A[critic]
    C2 --> C2B[auditor]
    C2 --> C2C[curator]
    C2 --> C2D[conductor]

分类体系的工程实现

内容配置架构

技能分类通过 Astro 内容集合（Content Collections）实现：

export const collections = {
  docs: defineCollection({
    loader: glob({
      pattern: [
        'docs/**/*.{md,mdx}',
        'library/skill-output-samples/**/sample_*.md',
      ],
    }),
    schema: docsSchema({
      extend: z.object({
        classification: z.string().optional(),
        thread: z.string().optional(),
        artifact: z.string().optional(),
      }),
    }),
  }),
};

资料来源：src/content.config.ts

样式与渲染

技能分类文档的渲染遵循 Starlight 主题规范，通过自定义 CSS 实现 Mermaid 图表和技能契约的可视化展示：

.mermaid svg {
  max-width: 100%;
  height: auto;
}

.mermaid .node rect {
  rx: 6;
  ry: 6;
}

资料来源：src/styles/custom.css

使用指南

调用技能的正确路径

在技能文档中使用仓库相对路径引用相关技能：

[`define-hypothesis`](../skills/define-hypothesis/SKILL.md)

这种方式确保 AI 代理可以直接解析和调用技能定义。

资料来源：_workflows/README.md

样本输出的分类标记

子代理样本输出按照以下规范标记分类信息：

总结

技能分类体系是 pm-skills 项目的基础架构，通过技能家族、技能契约和叙事线程三个维度实现了产品管理技能的结构化组织。该体系确保了不同子代理输出的可预测性和一致性，同时为 AI 代理提供了标准化的技能调用接口。开发者应遵循既定的分类规范，通过技能契约定义新技能，并通过统一的 frontmatter 字段确保分类元数据的完整性。

概述

pm-skills 是一个基于 Starlight 构建的产品管理技能文档站点，通过 AI Agent 子代理（Sub-agent）系统实现对产品管理（PM）工作流程的结构化支持。技能生命周期管理涵盖了从技能定义、验证、迭代优化到最终发布评审的完整流程。

当前仓库包含多类子代理，用于支持不同的 PM 工作场景：

资料来源：library/sub-agent-samples/README.md:1-30

三条叙事主线

pm-skills 通过三条叙事主线（Thread）贯穿整个技能库和子代理示例系统，每条主线代表不同的产品管理场景上下文：

这三条主线确保同一子代理在不同场景下能产生结构一致的输出（统一的 P0/P1/P2/P3 优先级语法、D26 规范的 Status 信封结构），而场景差异仅影响被审阅产物的内容本身。

资料来源：library/sub-agent-samples/README.md:85-100

技能文件结构

技能目录组织

每个 PM 技能作为独立目录存储在 skills/ 下，包含标准化文件结构：

skills/
└── <skill-name>/
    └── SKILL.md        # 技能定义文件

技能链接规范

工作流文件（_workflows/ 目录）使用仓库相对路径引用技能：

[`define-hypothesis`](../skills/define-hypothesis/SKILL.md)

这种格式确保 AI 代理（Copilot、Cursor、Windsurf）和仓库浏览器可直接解析链接。

资料来源：_workflows/README.md:14-16

内容集合架构

pm-skills 使用 Astro Starlight 构建文档站点，内容通过 src/content.config.ts 中的 collections 配置管理：

export const collections = {
  docs: defineCollection({
    loader: glob({
      pattern: [
        'docs/**/*.{md,mdx}',
        '!docs/internal/**',
        '!docs/templates/**',
        '!docs/**/README.md',
        'library/skill-output-samples/**/sample_*.md',
        '!library/skill-output-samples/**/sample_*_legacy_*.md',
        '!library/skill-output-samples/**/sample_*_orbit_*.md',
      ],
      base: '.',
    }),
    // ...
  }),
};

内容加载规则

资料来源：src/content.config.ts:30-45

Slug 生成策略

内容加载器使用自定义 generateId 函数处理路径前缀，确保 URL 整洁：

资料来源：src/content.config.ts:55-75

子代理样本体系

样本文件规范

每个子代理样本文件包含标准化的 Frontmatter 元数据：

系统概述

pm-skills 的子代理系统包含四个核心子代理，分别对应产品管理工作流中的不同环节：

资料来源：library/sub-agent-samples/README.md:1-40

子代理线程模型

子代理系统基于三个叙事线程（Thread）来组织示例和场景，每个线程代表不同的产品管理上下文：

• Brainshelf：消费级 PKM（个人知识管理）应用场景
• Storevine：B2B 营销分析平台场景
• Workbench：内部平台工具团队场景

这种设计确保同一子代理在不同业务上下文中产生结构一致的输出，同时内容贴合实际场景需求。

graph TD
    subgraph 叙事线程
        B[brainshelf<br/>消费级 PKM]
        S[storevine<br/>B2B 分析平台]
        W[workbench<br/>平台工具团队]
    end
    
    subgraph 子代理能力
        C[pm-critic<br/>对抗性审查]
        A[pm-skill-auditor<br/>技能审计]
        L[pm-changelog-curator<br/>变更日志整理]
        R[pm-release-conductor<br/>发布协调]
    end
    
    B --> C
    S --> C
    W --> C
    
    B --> A
    S --> A
    W --> A
    
    B --> L
    S --> L
    W --> L
    
    B --> R
    S --> R
    W --> R

资料来源：library/sub-agent-samples/README.md:130-145

子代理详细规格

pm-critic

pm-critic 是对抗性审查子代理，负责对产品文档和决策进行严格的质量检查。

典型场景：

• PRD（产品需求文档）审查
• OKR（目标与关键成果）设定审核
• 会议决策回顾

问题分级标准：

资料来源：library/sub-agent-samples/README.md:30-35

pm-skill-auditor

pm-skill-auditor 负责审计技能定义的健康状态，确保技能定义的完整性和文件系统的一致性。

检测类型：

• 上下文漂移检测：CONTEXT.md 声明与文件系统实际状态不匹配
• 孤岛检测：存在命令但无对应技能定义，或存在技能定义但无对应命令
• 预发布审计：在发布周期中期进行前瞻性检查

pm-changelog-curator

pm-changelog-curator 根据提交记录自动生成符合规范的变更日志。

输出格式遵循语义化版本规范：

• Added：新功能
• Changed：功能变更
• Fixed：问题修复
• Security：安全更新
• Known Limitations：已知限制

资料来源：library/sub-agent-samples/README.md:45-50

pm-release-conductor

pm-release-conductor 协调多阶段发布流程，执行门控验证（Gate）并管理失败恢复。

门控层级：

资料来源：library/sub-agent-samples/README.md:55-60

示例样本规范

每个子代理的示例样本（Sample）遵循统一的文档结构：

# Frontmatter 元数据
title: 样本标题
description: 场景描述
artifact: 子代理输出类型
version: 版本号
repo_version: 仓库版本
agent_version: 代理版本
created: 创建日期
status: sample
thread: 叙事线程
context: 上下文信息

文档结构：

1. Scenario 部分：描述触发子代理调用的具体场景
2. Output 部分：子代理的实际输出结果
3. Notes 部分：说明样本演示的内容及其在 3-线程目录中的定位

资料来源：library/sub-agent-samples/README.md:65-75

内容配置与集成

子代理系统通过 Astro 内容配置与文档站点深度集成：

// src/content.config.ts
schema: docsSchema({
  extend: z.object({
    // 样本特定字段 (W7)
    artifact: z.string().optional(),
    repo_version: z.string().or(z.number()).optional(),
    skill_version: z.string().or(z.number()).optional(),
    created: z.string().or(z.date()).optional(),
    status: z.string().optional(),
    thread: z.string().optional(),
    context: z.string().optional(),
  }),
})

样本文件加载规则：

• 匹配模式：library/skill-output-samples/**/sample_*.md
• 排除模式：
• sample_*_legacy_*.md：历史遗留样本
• sample_*_orbit_*.md：Orbit 线程样本

资料来源：src/content.config.ts:1-70

依赖关系

子代理系统基于以下技术栈构建：

资料来源：package.json:1-25

样式定制

子代理输出文档中的 Mermaid 图表使用自定义样式：

/* Mermaid SVG polish */
.mermaid svg {
  max-width: 100%;
  height: auto;
}
.mermaid .edgePath path,
.mermaid .flowchart-link {
  stroke-width: 1.75px;
}
.mermaid .node rect {
  rx: 6;
  ry: 6;
}
.mermaid .cluster rect {
  fill-opacity: 0.4;
}

资料来源：src/styles/custom.css:1-35

子代理调用流程

子代理通过标准化的调用模式与外部 AI 代理（Copilot、Cursor、Windsurf 等）集成：

graph LR
    A[外部 AI 代理] -->|调用| B[pm-skills 子代理]
    B -->|审查/审计/生成| C[标准化输出]
    C --> D[用户文档]
    
    E[技能定义] -->|被审计| B
    F[提交记录] -->|被分析| B
    G[产品文档] -->|被审查| B

相关文档路径

资料来源：_workflows/README.md:1-20

概述

工作流系统（Workflows）是 pm-skills 项目中用于定义产品管理（Product Management）流程的核心组件。它通过多技能引导序列（multi-skill workflow）为常见的产品管理流程提供结构化的指导路径。

每个工作流由 .md 文件定义，包含一系列产品管理技能的编排，指导用户完成特定的产品管理任务。资料来源：_workflows/README.md:1-10

架构设计

双目录结构

pm-skills 采用源目录与生成目录分离的架构：

graph LR
    A["_workflows/ <br/> (源目录)"] -->|generate-workflow-pages.py| B["docs/workflows/ <br/> (生成目录)"]
    A -->|直接使用| C["AI Agents <br/> (Copilot/Cursor/Windsurf)"]

资料来源：_workflows/README.md:13-17

链接约定

工作流文件使用仓库相对路径（repo-relative paths）来引用技能：

[`define-hypothesis`](../skills/define-hypothesis/SKILL.md)

这种设计使工作流文件能够被 AI 代理（Copilot、Cursor、Windsurf）和仓库浏览器直接使用。资料来源：_workflows/README.md:7-10

工作流类型

预定义工作流

工作流结构

每个工作流文件遵循统一的结构：

graph TD
    A["工作流文件"] --> B["元数据 (Frontmatter)"]
    A --> C["技能序列"]
    A --> D["步骤说明"]
    B -->|title| E["工作流名称"]
    B -->|description| F["工作流描述"]
    C --> G["技能1"]
    C --> H["技能2"]
    C --> I["技能N"]

生成机制

生成脚本

工作流文档从 _workflows/ 目录生成到 docs/workflows/ 目录，使用专用脚本：

scripts/generate-workflow-pages.py

编辑规则：

• 直接编辑 _workflows/ 中的工作流内容
• 不要直接编辑 docs/workflows/ 中的文件
• 这些文件由生成脚本自动更新

资料来源：_workflows/README.md:13-17

生成配置

在 src/content.config.ts 中，工作流文件被纳入 Astro 内容集合：

pattern: [
  'docs/**/*.{md,mdx}',
  'library/skill-output-samples/**/sample_*.md',
  // ...
]

资料来源：src/content.config.ts:7-16

工作流与子代理系统

子代理类型

工作流系统与子代理（Sub-agents）系统协同工作：

资料来源：library/sub-agent-samples/README.md:1-20

执行流程

sequenceDiagram
    participant U as 用户
    participant W as 工作流
    participant S as 子代理
    participant A as AI Agent
    
    U->>W: 选择工作流
    W->>A: 加载技能序列
    A->>S: 调用子代理
    S->>A: 返回结果
    A->>U: 展示结果

使用指南

编辑工作流

1. 打开 _workflows/ 目录下的目标工作流文件
2. 编辑工作流内容和技能序列
3. 提交更改
4. 生成脚本自动更新 docs/workflows/ 目录

在 AI 代理中使用

工作流文件可直接被 AI 代理使用：

[`define-hypothesis`](../skills/define-hypothesis/SKILL.md)

引用技能时使用仓库相对路径，确保代理能够正确定位技能文件。

资料来源：docs/guides/using-workflows.md

工作流最佳实践

• 保持工作流文件简洁明了
• 使用一致的技能引用格式
• 在技能序列中包含清晰的步骤说明
• 定期审计工作流与实际流程的匹配度

相关资源

概述

pm-skills 的工具家族包含多个核心工具，每个工具对应一个独立的产品管理方法论或工作流程。这些工具被设计为可组合、可扩展的模块，支持从需求发现到产品发布的完整生命周期管理。

工具家族的核心组成

资料来源：docs/concepts/foundation-sprint.md

核心工具详解

Foundation Sprint

Foundation Sprint 是一个结构化的需求发现框架，用于在项目初期明确问题和目标。它强调从用户痛点出发，通过系统化的方法论建立产品基础。

核心阶段：

1. 问题发现 - 识别并定义核心用户问题
2. 假设构建 - 形成可验证的产品假设
3. 边界明确 - 界定解决方案的范围和约束

资料来源：docs/guides/using-foundation-sprint.md

Design Sprint

Design Sprint 是一个高强度的时间boxed工作坊方法，通常在5天内完成从问题理解到可测试原型的完整流程。

标准流程：

graph TD
    A[理解问题<br/>Day 1] --> B[发散方案<br/>Day 2]
    B --> C[决策选择<br/>Day 3]
    C --> D[原型制作<br/>Day 4]
    D --> E[用户测试<br/>Day 5]

资料来源：docs/concepts/design-sprint.md

工具编排与工作流

工具家族支持多种编排模式，允许不同工具之间协同工作以完成复杂的产品管理任务。

工作流类型

pm-skills 定义了标准化的多工具工作流，通过预定义的 .md 文件描述引导序列。

链接约定：

工作流文件使用仓库相对路径引用技能：

[`define-hypothesis`](../skills/define-hypothesis/SKILL.md)

资料来源：_workflows/README.md

工作流生成机制

工作流内容在 _workflows/ 目录中编辑和维护，通过 scripts/generate-workflow-pages.py 脚本自动生成到 docs/workflows/ 目录。

graph LR
    A[_workflows/*.md] -->|生成脚本| B[docs/workflows/]
    B --> C[静态站点]

子代理体系

工具家族包含一组专门的 PM 子代理，每个子代理负责特定的分析或执行任务。

子代理类型

资料来源：library/sub-agent-samples/README.md

子代理样本模式

每个子代理样本包含标准化的元数据结构：

• Frontmatter 字段： title、description、artifact、version、created、status、thread、context
• 场景部分： 触发子代理调用的具体情况
• 输出部分： 实际的子代理输出（分级、发现、草案）
• 注释部分： 样本演示内容和分类说明

叙事线程架构

工具家族通过三条叙事线程覆盖不同的产品管理场景上下文。

线程定义

资料来源：library/sub-agent-samples/README.md

方法论对比

工具家族中的不同工具适用于不同的场景和目标。选择合适的方法论对于有效的产品管理至关重要。

Workshop 方法对比

资料来源：docs/reference/workshop-method-comparison.md

技术架构

文档生成架构

工具家族的内容通过 Astro Starlight 框架进行管理和发布。

graph TD
    A[源文件<br/>docs/, library/] --> B[内容配置<br/>src/content.config.ts]
    B --> C[Starlight 加载器]
    C --> D[静态站点生成]
    D --> E[用户文档站点]

内容集合配置

内容集合使用 Astro 的 glob 加载器，支持以下模式：

pattern: [
  'docs/**/*.{md,mdx}',
  '!docs/internal/**',
  '!docs/templates/**',
  '!docs/**/README.md',
  'library/skill-output-samples/**/sample_*.md'
]

资料来源：src/content.config.ts

自定义字段扩展

Schema 扩展包含以下 pm-skills 特定字段：

使用指南

选择合适的工具

1. 明确目标 - 确定当前的产品管理目标
2. 评估场景 - 匹配目标与工具能力
3. 组合使用 - 必要时组合多个工具

工具集成模式

工具家族支持三种主要集成模式：

独立使用： 单个工具独立解决特定问题，适用于局部优化。

串联工作： 多个工具按顺序使用，形成完整的流程链条。

并行协作： 多个工具同时运行，处理不同的分析维度。

最佳实践

• 优先使用结构化的工作流定义文档
• 子代理输出遵循统一的 P0/P1/P2/P3 问题分级标准
• 保持叙事线程的一致性，确保上下文连贯
• 定期审计工具家族的使用效果

扩展工具家族

添加新工具到家族中需要：

1. 在 skills/ 目录创建工具定义
2. 实现标准化的 SKILL.md 模板
3. 添加样本输出到 library/skill-output-samples/
4. 更新工作流文档以包含新工具

概述

pm-skills 是一个基于 Astro Starlight 框架构建的产品管理技能文档站点，旨在为产品经理提供系统化的技能、工作流和子代理（sub-agent）指导。 资料来源：package.json:5-8

项目采用现代化前端技术栈，通过 Markdown 文件驱动的文档系统，支持 Mermaid 图表渲染，并集成了 AI 代理（Codex、Claude 等）的协作工作区。 资料来源：src/content.config.ts:1-4

环境要求

系统依赖

项目 package.json 中明确指定了 Node.js 引擎要求，低于 22.12.0 的版本将无法正常运行构建脚本。 资料来源：package.json:7-10

核心依赖包

资料来源：package.json:13-20

安装步骤

1. 克隆仓库

git clone https://github.com/product-on-purpose/pm-skills.git
cd pm-skills

2. 安装依赖

npm install

该命令会根据 package.json 中的依赖声明自动安装所有必要的包。

3. 开发模式启动

npm run dev

启动后访问 http://localhost:4321 查看本地文档站点。开发模式支持热重载，文档修改后页面会自动刷新。

4. 构建生产版本

npm run build

构建过程包含两个步骤：

1. astro build - 生成静态站点
2. node scripts/post-build-strip-md-links.mjs - 移除 Markdown 链接的后处理脚本

资料来源：package.json:11-15

5. 预览构建结果

npm run preview

平台配置

文档内容配置

pm-skills 使用 Astro 的内容集合（Content Collections）系统管理文档。核心配置位于 src/content.config.ts。 资料来源：src/content.config.ts:1-6

#### 内容集合架构

graph TD
    A[docs/ 目录] --> B[Markdown/MDX 文件]
    A --> C[library/skill-output-samples/]
    B --> D[skills/ 技能定义]
    B --> E[guides/ 使用指南]
    B --> F[workflows/ 工作流]
    B --> G[reference/ 参考文档]
    C --> H[sample_*.md 示例输出]
    D --> I[define-hypothesis/]
    D --> J[utility-pm-*/]

#### 内容加载规则

content.config.ts 中定义的内容加载器使用 glob 模式匹配，支持以下文件包含和排除逻辑： 资料来源：src/content.config.ts:35-43

#### 自定义 Slug 生成

系统采用自定义 ID 生成策略，将不同路径的前缀统一处理为干净的 slug： 资料来源：src/content.config.ts:45-57

自定义字段模式

内容集合扩展了 Starlight 的 docsSchema，支持以下 pm-skills 专用字段： 资料来源：src/content.config.ts:63-82

Mermaid 图表配置

项目在 src/styles/custom.css 中为 Mermaid 图表定义了统一的视觉风格： 资料来源：src/styles/custom.css:1-32

#### 样式规则

/* 图表容器 */
.mermaid {
  max-width: 100%;
}

/* SVG 自适应 */
.mermaid svg {
  max-width: 100%;
  height: auto;
}

/* 连线样式 */
.mermaid .edgePath path,
.mermaid .flowchart-link {
  stroke-width: 1.75px;
}

/* 节点圆角 */
.mermaid .node rect {
  rx: 6;
  ry: 6;
}

/* 集群背景透明度 */
.mermaid .cluster rect {
  fill-opacity: 0.4;
}

这些样式在浅色和深色模式下均生效，覆盖所有图表类型（流程图、序列图、甘特图等）。

AI 代理集成

Codex 工作区策略

仓库为 Codex AI 代理维护了一个专用工作区 _agent-context/codex/，其中包含以下策略文件： 资料来源：_agent-context/codex/README.md:1-8

本地忽略文件

以下文件类型被 Git 忽略，仅在本地保留： 资料来源：_agent-context/codex/README.md:11-13

• PLANNING/** - 探索性规划草稿
• TODO.md - 临时任务
• AGENTS/SESSION-LOG/ - 会话日志目录

会话日志规范

会话交接文件按以下命名规范存储： 资料来源：_agent-context/codex/README.md:19-21

AGENTS/SESSION-LOG/YYYY-MM-DD[_HH-MM]_codex_<scope>.md

文件名中包含模型名称（_codex_），使 Claude 和 Codex 的会话可以在同一目录下按日期共存。

工作流与技能系统

工作流定义

工作流文件位于 _workflows/ 目录，每个 .md 文件定义一个多技能工作流，指导用户完成常见的产品管理流程。 资料来源：_workflows/README.md:1-8

#### 链接约定

工作流文件使用仓库相对路径引用技能： 资料来源：_workflows/README.md:10-13

[`define-hypothesis`](../skills/define-hypothesis/SKILL.md)

此约定确保 AI 代理（Copilot、Cursor、Windsurf 等）和仓库浏览器可以直接使用这些链接。

#### 编辑策略

• 在 _workflows/ 目录编辑工作流内容
• 不要直接编辑 docs/workflows/ 目录
• docs/workflows/ 文件由 scripts/generate-workflow-pages.py 脚本从源目录自动生成

子代理库

library/sub-agent-samples/ 目录包含每个 pm-skills 子代理的真实输出示例： 资料来源：library/sub-agent-samples/README.md:1-12

#### 叙事线程

示例覆盖三个叙事场景： 资料来源：library/sub-agent-samples/README.md:92-101

常见问题排查

节点版本不匹配

如果遇到构建错误，首先检查 Node.js 版本：

node --version

确保版本 >= 22.12.0。

内容未出现在站点

检查 src/content.config.ts 中的 glob 模式是否正确匹配目标文件，确保文件不在排除列表中。

Mermaid 图表不渲染

确保 astro-mermaid 依赖已正确安装，且 Mermaid 语法符合规范。样式问题可参考 src/styles/custom.css 中的自定义规则。

设计目标与核心价值

样本输出库的核心价值体现在以下几个方面：

1. 行为验证：通过真实输出样本验证子代理的批评、审计、变更日志生成和发布流程控制等能力
2. 规范参照：为 AI 代理（Copilot、Cursor、Windsurf）提供可学习的标准输出模式
3. 回归测试：在代码变更后可通过对比样本输出检测行为漂移
4. 文档支撑：为用户指南和贡献者文档提供具体案例

资料来源：library/sub-agent-samples/README.md:1-15

目录结构

样本输出库采用分层目录结构，按子代理类型和叙事线程进行双重分类：

library/sub-agent-samples/
├── pm-critic/
│   ├── sample_pm-critic_brainshelf_prd-review.md
│   ├── sample_pm-critic_storevine_okr-review.md
│   └── sample_pm-critic_workbench_meeting-recap-review.md
├── pm-skill-auditor/
│   ├── sample_pm-skill-auditor_brainshelf_pre-release.md
│   ├── sample_pm-skill-auditor_storevine_drift-detection.md
│   └── sample_pm-skill-auditor_workbench_cross-cutting.md
├── pm-changelog-curator/
│   ├── sample_pm-changelog-curator_brainshelf_minor-release.md
│   ├── sample_pm-changelog-curator_storevine_patch-release.md
│   └── sample_pm-changelog-curator_workbench_feature-release.md
└── pm-release-conductor/
    ├── sample_pm-release-conductor_brainshelf_clean-run.md
    ├── sample_pm-release-conductor_storevine_gate-failure.md
    └── sample_pm-release-conductor_workbench_chained-run.md

资料来源：library/sub-agent-samples/README.md:18-33

子代理类型

pm-skills 项目定义了四个核心子代理，每个子代理产生特定类型的输出样本：

资料来源：library/sub-agent-samples/README.md:34-45

叙事线程体系

样本输出库采用三个叙事线程（Thread）作为场景化背景，确保样本输出覆盖不同产品管理上下文：

Brainshelf - 消费级 PKM 应用

个人知识管理（PKM）应用场景，捕获消费者产品管理上下文。典型问题域包括：

• 文档完整性验证
• 假设定义与验证
• 竞品分析

资料来源：library/sub-agent-samples/README.md:118-120

Storevine - B2B 营销分析平台

B2B 营销分析平台场景，捕获数据分析与数据产品管理上下文。典型问题域包括：

• OKR 设置与评审
• 聚合计数器管理
• 上下文漂移检测

资料来源：library/sub-agent-samples/README.md:122-124

Workbench - 内部平台工具团队

内部平台与开发者体验（DX）管理上下文。典型问题域包括：

• 会议决策追踪
• 跨切面技能审计
• 链式发布编排

资料来源：library/sub-agent-samples/README.md:126-128

样本文件结构

每个样本文件采用标准化 YAML frontmatter 元数据格式：

Pitfall Log / 踩坑日志

项目：product-on-purpose/pm-skills

摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 pm-skills 与安装入口 skills 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令: npx skills
• 防护动作: 页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | github_repo:1130952330 | https://github.com/product-on-purpose/pm-skills | repo=pm-skills; install=skills

2. 安装坑 · 来源证据：[F-14] Workflow Builder (/workflow-builder)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[F-14] Workflow Builder (/workflow-builder)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_fd2240d9f58c49edbcc147428ff9b561 | https://github.com/product-on-purpose/pm-skills/issues/133 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 来源证据：[F-15] Ad-Hoc Skill Chaining (/chain)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[F-15] Ad-Hoc Skill Chaining (/chain)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_151a0a8448c84b81b626bf03b88d2714 | https://github.com/product-on-purpose/pm-skills/issues/134 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：v2.11.1 - skills.sh CLI Compatibility Patch

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.11.1 - skills.sh CLI Compatibility Patch
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_55aa5dc614634b48a39a0310a9b5fd45 | https://github.com/product-on-purpose/pm-skills/releases/tag/v2.11.1 | 来源类型 github_release 暴露的待验证使用条件。

5. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1130952330 | https://github.com/product-on-purpose/pm-skills | host_targets=claude, claude_code

6. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1130952330 | https://github.com/product-on-purpose/pm-skills | README/documentation is current enough for a first validation pass.

7. 维护坑 · 来源证据：[M-21] Explore release-please Integration

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[M-21] Explore release-please Integration
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_acdd9d4cd91c449f964bf1924ec0b6e1 | https://github.com/product-on-purpose/pm-skills/issues/136 | 来源类型 github_issue 暴露的待验证使用条件。

8. 维护坑 · 来源证据：v2.12.0 OKR Skills Launch

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v2.12.0 OKR Skills Launch
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f2a160e56ca04946816b63eab92a85cd | https://github.com/product-on-purpose/pm-skills/releases/tag/v2.12.0 | 来源类型 github_release 暴露的待验证使用条件。

9. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1130952330 | https://github.com/product-on-purpose/pm-skills | last_activity_observed missing

10. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作: 下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1130952330 | https://github.com/product-on-purpose/pm-skills | no_demo; severity=medium

11. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1130952330 | https://github.com/product-on-purpose/pm-skills | no_demo; severity=medium

12. 安全/权限坑 · 来源证据：v2.13.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.13.1
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e5dab862059242fd8f82b7814ef33eb8 | https://github.com/product-on-purpose/pm-skills/releases/tag/v2.13.1 | 来源类型 github_release 暴露的待验证使用条件。

13. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作: issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1130952330 | https://github.com/product-on-purpose/pm-skills | issue_or_pr_quality=unknown

14. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1130952330 | https://github.com/product-on-purpose/pm-skills | release_recency=unknown