# https://github.com/product-on-purpose/pm-skills 项目说明书

生成时间: 2026-05-21 19:54:48 UTC

## 目录

- [项目介绍](#project-introduction)
- [技能库概览](#skill-library-overview)
- [技能结构解析](#skill-anatomy)
- [技能分类体系](#skill-categories)
- [技能生命周期管理](#skill-lifecycle)
- [子代理系统](#sub-agents)
- [工作流系统](#workflows)
- [工具家族](#tool-families)
- [安装与平台配置](#installation-guide)
- [样本输出库](#sample-outputs)

<a id='project-introduction'></a>

## 项目介绍

### 相关页面

相关主题：[技能库概览](#skill-library-overview), [安装与平台配置](#installation-guide)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/product-on-purpose/pm-skills/blob/main/README.md)
- [package.json](https://github.com/product-on-purpose/pm-skills/blob/main/package.json)
- [_workflows/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/README.md)
- [library/sub-agent-samples/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)
- [_agent-context/codex/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/_agent-context/codex/README.md)
- [src/content.config.ts](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts)
- [src/styles/custom.css](https://github.com/product-on-purpose/pm-skills/blob/main/src/styles/custom.css)
</details>

# 项目介绍

## 概述

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

资料来源：[package.json:2](https://github.com/product-on-purpose/pm-skills/blob/main/package.json)

## 技术栈

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

| 技术选型 | 版本 | 用途 |
|---------|------|------|
| Astro | ^6.3.0 | 静态站点生成框架 |
| @astrojs/starlight | ~0.39.0 | 文档主题与 UI 组件 |
| astro-mermaid | ~2.0.1 | Mermaid 图表渲染 |
| Mermaid | ^11.15.0 | 流程图与架构图绘制 |
| sharp | ^0.34.5 | 图片处理优化 |
| devalue | ^5.8.1 | 序列化库 |

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

资料来源：[package.json:3-18](https://github.com/product-on-purpose/pm-skills/blob/main/package.json)

## 核心架构

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

```mermaid
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](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/README.md)

## 内容组织

### 文档结构

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

| 目录 | 说明 |
|------|------|
| `docs/` | 用户文档（skills、guides、concepts、contributing 等） |
| `library/` | 示例输出与子代理样本库 |
| `_workflows/` | 工作流定义源文件 |
| `_agent-context/` | AI 代理工作区策略文档 |
| `scripts/` | 构建与生成脚本 |

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

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

资料来源：[src/content.config.ts:1-80](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts)

### 技能输出样本

`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](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

## 子代理体系

### 代理分类

| 子代理名称 | 功能 | 样本数量 |
|-----------|------|---------|
| `pm-critic` | 对 PRD、OKR、会议记录进行对抗性评审 | 3 |
| `pm-skill-auditor` | 跨技能审计与漂移检测 | 3 |
| `pm-changelog-curator` | 生成规范化的变更日志 | 3 |
| `pm-release-conductor` | 协调发布流程与门控检查 | 3 |

### 叙事线程

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

| 线程 | 产品类型 | 场景特征 |
|------|---------|---------|
| **Brainshelf** | 消费者 PKM（个人知识管理）应用 | 消费级产品 PM 语境 |
| **Storevine** | B2B 营销分析平台 | 数据产品 PM 语境 |
| **Workbench** | 内部平台工具团队 | 平台/DX PM 语境 |

资料来源：[library/sub-agent-samples/README.md:80-100](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

## 工作流定义

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

### 链接约定

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

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

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

资料来源：[_workflows/README.md:8-15](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/README.md)

### 编辑规范

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

## AI 代理工作区

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

### 持久化文件（Git 跟踪）

| 文件 | 用途 |
|------|------|
| `CONTEXT.md` | 稳定的当前状态事实 |
| `DECISIONS.md` | 已接受的决策与理由 |
| `WRAP-SESSION_TEMPLATE.md` | 会话交接模板 |
| `WORKTREE-PRIMER.md` | 清洁分支工作流指南 |

### 本地文件（Git 忽略）

| 路径/文件 | 用途 |
|----------|------|
| `PLANNING/**` | 探索性规划草稿 |
| `TODO.md` | 临时任务清单 |
| `AGENTS/SESSION-LOG/` | 会话日志目录 |

资料来源：[_agent-context/codex/README.md:1-40](https://github.com/product-on-purpose/pm-skills/blob/main/_agent-context/codex/README.md)

## 样式与渲染

### 自定义样式

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

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

### 主题变量

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

资料来源：[src/styles/custom.css:1-35](https://github.com/product-on-purpose/pm-skills/blob/main/src/styles/custom.css)

## 构建流程

### NPM 脚本

| 命令 | 功能 |
|------|------|
| `npm run dev` | 启动开发服务器（热重载） |
| `npm run build` | 生产构建（含 Markdown 链接清理） |
| `npm run preview` | 预览生产构建结果 |
| `npm run astro` | 调用 Astro CLI |

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

资料来源：[package.json:7-12](https://github.com/product-on-purpose/pm-skills/blob/main/package.json)

## 扩展字段

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

| 字段 | 类型 | 说明 |
|------|------|------|
| `generated` | boolean | 内容是否由脚本生成 |
| `source` | string | 原始来源 |
| `phase` | string | 所属阶段 |
| `classification` | string | 分类 |
| `version` | string/number | 版本号 |
| `updated` | string/Date | 更新时间 |
| `artifact` | string | 子代理输出类型 |
| `created` | string/Date | 创建时间 |
| `status` | string | 样本状态 |
| `thread` | string | 叙事线程 |
| `context` | string | 上下文信息 |
| `tags` | string[] | 标签数组 |
| `metadata` | object | 额外元数据 |

资料来源：[src/content.config.ts:50-75](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts)

## 快速开始

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 生产构建
npm run build
```

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

---

<a id='skill-library-overview'></a>

## 技能库概览

### 相关页面

相关主题：[技能结构解析](#skill-anatomy), [技能分类体系](#skill-categories), [项目介绍](#project-introduction)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/content.config.ts](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts)
- [library/sub-agent-samples/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)
- [_workflows/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/README.md)
- [src/styles/custom.css](https://github.com/product-on-purpose/pm-skills/blob/main/src/styles/custom.css)
- [package.json](https://github.com/product-on-purpose/pm-skills/blob/main/package.json)
</details>

# 技能库概览

## 概述

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

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

资料来源：[package.json:3-7](https://github.com/product-on-purpose/pm-skills/blob/main/package.json)

## 技能库架构

### 技能分类

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

| 技能类别 | 用途 | 示例技能 |
|---------|------|---------|
| discover | 发现问题与机会 | 用户研究、竞品分析 |
| define | 定义问题与目标 | 定义假设、绘制用户旅程 |
| develop | 方案构思与设计 | 原型设计、功能规划 |
| deliver | 交付与发布 | 发布计划、变更管理 |
| measure | 度量与评估 | 指标定义、数据分析 |
| iterate | 迭代优化 | 优先级排序、复盘总结 |
| foundation | 基础工具与方法论 | OKR 设定、会议主持 |

资料来源：[src/content.config.ts:15-25](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts)

### 目录结构

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

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

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

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

资料来源：[_workflows/README.md:9-13](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/README.md)

## 内容加载机制

### Astro 内容集合配置

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

```typescript
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](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts)

### Slug 生成规则

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

| 源文件 | 生成 Slug |
|--------|----------|
| `docs/skills/index.md` | `skills` |
| `docs/skills/define-hypothesis/SKILL.md` | `skills/define-hypothesis/SKILL` |
| `library/skill-output-samples/` 下的文件 | `samples/...` |

资料来源：[src/content.config.ts:26-40](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts)

## 技能内容 Schema

### 通用字段

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

| 字段 | 类型 | 说明 |
|------|------|------|
| `title` | string | 技能标题 |
| `description` | string | 技能描述 |
| `generated` | boolean | 是否为生成内容 |
| `source` | string | 来源引用 |
| `phase` | string | 所属阶段 |
| `classification` | string | 分类标识 |
| `version` | string \| number | 技能版本 |
| `updated` | string \| Date | 更新时间 |
| `tags` | string[] | 标签列表 |
| `draft` | boolean | 是否为草稿 |

资料来源：[src/content.config.ts:45-60](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts)

## 技能输出样本库

### 样本分类

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

| 线程 | 应用场景 | 产品类型 |
|------|----------|----------|
| **Brainshelf** | 消费者 PKM 应用 | 个人知识管理 App |
| **Storevine** | B2B 活动分析平台 | 数据分析产品 |
| **Workbench** | 内部平台工具团队 | 平台/DX 产品 |

资料来源：[library/sub-agent-samples/README.md:85-90](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

### 子代理能力

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

| 子代理 | 职能 | 输出类型 |
|--------|------|----------|
| `pm-critic` | 对抗性评审 | 问题分级（P0-P3） |
| `pm-skill-auditor` | 技能审计 | 跨技能一致性检查 |
| `pm-changelog-curator` | 变更日志整理 | 版本发布草稿 |

资料来源：[library/sub-agent-samples/README.md:17-24](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

## 工作流集成

### 工作流定义

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

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

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

资料来源：[_workflows/README.md:5-10](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/README.md)

### 工作流与技能关系

```mermaid
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` 集成：

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

资料来源：[package.json:18-22](https://github.com/product-on-purpose/pm-skills/blob/main/package.json)

### 图表样式定制

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

```css
.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](https://github.com/product-on-purpose/pm-skills/blob/main/src/styles/custom.css)

## 文档生成与发布

### 构建流程

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

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

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

资料来源：[package.json:12](https://github.com/product-on-purpose/pm-skills/blob/main/package.json)

### 节点版本要求

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

资料来源：[package.json:8](https://github.com/product-on-purpose/pm-skills/blob/main/package.json)

## 快速入门

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

## 相关资源

- [子代理库样本](../library/sub-agent-samples/index.md) - 各子代理的真实输出示例
- [工作流定义](../_workflows/index.md) - 多技能组合的工作流
- [发布运行手册](../docs/contributing/release-runbook.md) - 发布流程指南

---

<a id='skill-anatomy'></a>

## 技能结构解析

### 相关页面

相关主题：[技能生命周期管理](#skill-lifecycle), [技能分类体系](#skill-categories)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/reference/pm-skill-anatomy.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/reference/pm-skill-anatomy.md)
- [docs/reference/frontmatter-schema.yaml](https://github.com/product-on-purpose/pm-skills/blob/main/docs/reference/frontmatter-schema.yaml)
- [docs/templates/skill-template/SKILL.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/templates/skill-template/SKILL.md)
- [docs/templates/skill-template/references/TEMPLATE.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/templates/skill-template/references/TEMPLATE.md)
- [docs/templates/skill-template/references/EXAMPLE.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/templates/skill-template/references/EXAMPLE.md)
</details>

# 技能结构解析

## 概述

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

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

## 技能核心结构

### 文件组成

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

| 文件 | 说明 | 必需 |
|------|------|------|
| `SKILL.md` | 技能主定义文件，包含元数据和执行指南 | 是 |
| `references/` | 目录，包含 `TEMPLATE.md` 和 `EXAMPLE.md` | 是 |

资料来源：[docs/templates/skill-template/SKILL.md]()

### 主文件元数据（Frontmatter）

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

```yaml
---
title: 技能标题
description: 技能简短描述（1-2 句话）
version: 1.0.0
created: YYYY-MM-DD
status: draft | published | deprecated
source: 初始来源或灵感引用
skill_version: 当前版本号
context: 适用场景标签（如 brainshelf、storevine、workbench）
---
```

支持的扩展字段包括：

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `title` | 字符串 | 技能显示标题 |
| `description` | 字符串 | 简短功能描述 |
| `version` | 字符串或数字 | 语义化版本号 |
| `created` | 字符串或日期 | 创建时间 |
| `status` | 枚举 | 技能状态：draft、published、deprecated |
| `source` | 字符串 | 来源引用 |
| `skill_version` | 字符串或数字 | 技能特定版本 |
| `context` | 字符串 | 适用场景 |
| `generated` | 布尔值 | 是否为生成内容 |
| `classification` | 字符串 | 技能分类 |
| `tags` | 字符串数组 | 标签列表 |
| `metadata` | 对象 | 自定义元数据 |

资料来源：[docs/reference/frontmatter-schema.yaml]()
资料来源：[src/content.config.ts:25-70]()

### 正文结构

技能主文件正文遵循标准化的文档结构：

```markdown
## 目的
说明技能解决的问题和价值

## 触发条件
何时应该使用此技能

## 使用指南
技能的详细执行步骤

## 变体与场景
不同情境下的适配方式
```

## 引用系统

### references 目录结构

每个技能必须包含 `references/` 子目录，用于存放扩展文档：

```
skills/技能名称/
├── SKILL.md
└── references/
    ├── TEMPLATE.md    # 该技能的模板文档
    └── EXAMPLE.md     # 该技能的示例文档
```

资料来源：[docs/templates/skill-template/SKILL.md]()

### 引用命名规范

| 文件名 | 用途 | 内容特点 |
|--------|------|----------|
| `TEMPLATE.md` | 模板参考 | 展示如何创建该技能的变体或扩展 |
| `EXAMPLE.md` | 实际示例 | 真实场景的应用案例 |

### 跨技能引用

技能之间可以相互引用，使用仓库相对路径：

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

这种链接格式确保 AI Agent 和文档系统都能正确解析技能间关系。资料来源：[_workflows/README.md:15-17]()

## 技能分类体系

pm-skills 项目采用多层分类体系组织技能：

### 场景分类（Thread）

| 场景 | 说明 | 典型用例 |
|------|------|----------|
| `brainshelf` | 消费者 PKM（个人知识管理）应用 | 产品重 surfaced PRD 评审 |
| `storevine` | B2B 活动分析平台 | Q2 OKR 设置与验证 |
| `workbench` | 内部平台工具团队 | Sprint 回顾与决策追踪 |

资料来源：[library/sub-agent-samples/README.md:60-74]()

### 问题优先级体系

技能执行过程中使用 P0-P3 优先级标记问题：

| 优先级 | 含义 | 处理要求 |
|--------|------|----------|
| P0 | 阻断性问题 | 必须立即修复 |
| P1 | 重要缺陷 | 下一迭代修复 |
| P2 | 次要问题 | 计划内修复 |
| P3 | 建议改进 | 视情况处理 |

资料来源：[library/sub-agent-samples/README.md:6-11]()

## 技能执行流程

技能的执行通过子代理（Sub-Agent）系统完成，不同类型的技能由相应的子代理处理：

```mermaid
graph TD
    A[用户触发] --> B{技能类型判断}
    B -->|PRD 评审| C[pm-critic]
    B -->|技能审计| D[pm-skill-auditor]
    B -->|变更日志| E[pm-changelog-curator]
    B -->|发布流程| F[pm-release-conductor]
    C --> G[问题评级 P0-P3]
    D --> G
    E --> H[生成输出]
    F --> H
    G --> I[状态信封]
    I --> H
```

资料来源：[library/sub-agent-samples/README.md:1-45]()

### 子代理职责

| 子代理 | 功能 | 输出类型 |
|--------|------|----------|
| `pm-critic` | 对抗性评审，捕获合同完整性、可证伪性、实验设计问题 | 评审报告 |
| `pm-skill-auditor` | 跨技能审计，检测漂移和结构问题 | 审计发现 |
| `pm-changelog-curator` | 自动生成变更日志 | 草稿文档 |
| `pm-release-conductor` | 执行发布门控流程 | 门控状态 |

## 技能与工作流的关系

### 工作流定义

工作流（Workflow）是由多个技能组成的引导序列，定义在 `_workflows/` 目录中。每个工作流文件（`.md`）使用技能引用链接构建执行路径。

```mermaid
graph LR
    subgraph 工作流示例
        W1[define-hypothesis] --> W2[design-experiment]
        W2 --> W3[analyze-results]
        W3 --> W4[decide-pivot]
    end
```

资料来源：[_workflows/README.md:1-8]()

### 链接规范

工作流文件中的技能链接必须使用仓库相对路径：

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

此格式确保 AI Agent 和 GitHub 目录浏览器都能正确解析。

## 文档生成机制

pm-skills 使用 Astro Starlight 构建文档站点，技能文件通过内容收集器加载：

```typescript
// src/content.config.ts
const collections = {
  docs: defineCollection({
    loader: glob({
      pattern: [
        'docs/**/*.{md,mdx}',
        'library/skill-output-samples/**/sample_*.md',
        // ...
      ],
      base: '.',
    }),
    schema: docsSchema({
      extend: z.object({ /* pm-skills 扩展字段 */ })
    }),
  }),
};
```

资料来源：[src/content.config.ts:1-80]()

### 内容加载规则

| 规则 | 说明 |
|------|------|
| `docs/**` | 文档主目录 |
| `!docs/internal/**` | 排除内部工作文件 |
| `!docs/templates/**` | 排除模板目录 |
| `!docs/**/README.md` | 排除目录着陆页 |

## 技能模板使用

创建新技能时应基于技能模板，遵循以下步骤：

1. 复制 `docs/templates/skill-template/` 目录结构
2. 修改 `SKILL.md` 的 frontmatter 元数据
3. 填写正文各节内容
4. 完善 `references/` 中的模板和示例
5. 将新技能放置于 `skills/` 目录相应分类下

### 模板字段说明

| 字段 | 填写要求 |
|------|----------|
| `title` | 使用动词短语，准确描述技能行为 |
| `description` | 限 1-2 句话，说明技能解决的问题 |
| `version` | 遵循语义化版本 `MAJOR.MINOR.PATCH` |
| `status` | 新技能初始为 `draft`，审核通过后改为 `published` |

资料来源：[docs/templates/skill-template/references/TEMPLATE.md]()
资料来源：[docs/templates/skill-template/references/EXAMPLE.md]()

## 最佳实践

### 技能编写规范

- **原子性**：每个技能应专注于单一职责
- **可组合性**：技能应能与其他技能组合形成工作流
- **可测试性**：技能应有明确的成功/失败判定标准
- **文档完整性**：所有字段必须填写，引用必须有效

### 状态管理

| 状态 | 使用场景 |
|------|----------|
| `draft` | 开发中或审核中的技能 |
| `published` | 已完成审核，可正式使用的技能 |
| `deprecated` | 已废弃，不建议新项目使用 |

### 版本控制

技能版本遵循语义化版本规范：

- **MAJOR**：不兼容的 API 变更
- **MINOR**：向后兼容的功能添加
- **PATCH**：向后兼容的问题修复

## 相关资源

- 技能目录：`skills/`
- 工作流目录：`_workflows/`
- 子代理定义：`agents/`
- 运行时组件参考：[docs/reference/runtime-components.md]()
- 发布运行手册：[docs/contributing/release-runbook.md]()

---

<a id='skill-categories'></a>

## 技能分类体系

### 相关页面

相关主题：[技能库概览](#skill-library-overview), [技能结构解析](#skill-anatomy)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/reference/categories.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/reference/categories.md)
- [docs/reference/skill-families/index.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/reference/skill-families/index.md)
- [docs/reference/skill-families/design-sprint-skills-contract.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/reference/skill-families/design-sprint-skills-contract.md)
- [docs/reference/skill-families/foundation-sprint-skills-contract.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/reference/skill-families/foundation-sprint-skills-contract.md)
- [docs/reference/skill-families/meeting-skills-contract.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/reference/skill-families/meeting-skills-contract.md)
</details>

# 技能分类体系

## 概述

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

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

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

资料来源：[library/sub-agent-samples/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

## 技能家族架构

### 技能家族定义

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

| 技能家族 | 描述 | 典型场景 |
|---------|------|---------|
| Foundation Sprint Skills | 基础产品管理技能集 | 需求定义、假设验证、用户研究 |
| Design Sprint Skills | 设计冲刺相关技能 | 快速原型、用户测试、设计决策 |
| Meeting Skills | 会议与协作技能 | 会议复盘、决策追踪、团队沟通 |
| Utility PM Roles | 跨场景工具技能 | 发布管理、变更日志、技能审计 |

资料来源：[docs/reference/skill-families/index.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/reference/skill-families/index.md)

### 技能契约机制

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

```mermaid
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](https://github.com/product-on-purpose/pm-skills/blob/main/docs/reference/skill-families/design-sprint-skills-contract.md)

## 技能契约类型详解

### Foundation Sprint 技能契约

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

#### 核心技能

| 技能名称 | 功能描述 | 触发条件 |
|---------|---------|---------|
| define-hypothesis | 定义可验证的产品假设 | 新功能规划、问题分析 |
| user-research | 用户研究整合 | 需求调研、用户反馈分析 |
| okr-review | OKR 设置审查 | 季度规划、目标对齐 |
| prd-review | 产品需求文档审查 | 需求评审、PRD 验收 |

#### 契约规范

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

资料来源：[docs/reference/skill-families/foundation-sprint-skills-contract.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/reference/skill-families/foundation-sprint-skills-contract.md)

### Design Sprint 技能契约

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

#### 契约特点

```mermaid
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](https://github.com/product-on-purpose/pm-skills/blob/main/docs/reference/skill-families/design-sprint-skills-contract.md)

### Meeting Skills 契约

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

#### 契约结构

| 字段 | 类型 | 说明 |
|-----|------|-----|
| title | string | 会议标题 |
| decisions | array | 会议决策清单 |
| action_items | array | 行动项列表 |
| owner | string | 决策责任人 |
| status | enum | 决策状态（待处理/进行中/已完成）|

资料来源：[docs/reference/skill-families/meeting-skills-contract.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/reference/skill-families/meeting-skills-contract.md)

## 分类维度

### 按叙事线程分类

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

```mermaid
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](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

### 按子代理分类

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

| 子代理 | 职责 | 输出类型 |
|-------|------|---------|
| pm-critic | 对抗性评审 | 问题发现与评级 |
| pm-skill-auditor | 技能一致性审计 | 漂移检测报告 |
| pm-changelog-curator | 变更日志整理 | 发布说明草稿 |
| pm-release-conductor | 发布流程编排 | 门控流程执行 |

资料来源：[library/sub-agent-samples/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

## 分类元数据

### Frontmatter 字段

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

| 字段 | 类型 | 说明 |
|-----|------|-----|
| title | string | 文档标题 |
| version | string/number | 版本号 |
| artifact | string | 工件类型 |
| status | string | 状态标识 |
| thread | string | 叙事线程 |
| classification | string | 分类标识 |
| created | string/Date | 创建时间 |

资料来源：[src/content.config.ts](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts:58-78)

### 分类标识系统

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

```mermaid
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）实现：

```typescript
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](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts:1-20)

### 样式与渲染

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

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

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

资料来源：[src/styles/custom.css](https://github.com/product-on-purpose/pm-skills/blob/main/src/styles/custom.css:15-27)

## 使用指南

### 调用技能的正确路径

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

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

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

资料来源：[_workflows/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/README.md)

### 样本输出的分类标记

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

| 标记项 | 示例值 | 说明 |
|-------|-------|------|
| thread | brainshelf/storevine/workbench | 叙事上下文 |
| artifact | grading/report/draft/flow | 输出工件类型 |
| status | sample | 标识为样本输出 |

## 总结

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

---

<a id='skill-lifecycle'></a>

## 技能生命周期管理

### 相关页面

相关主题：[技能结构解析](#skill-anatomy)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [_workflows/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/README.md)
- [_agent-context/codex/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/_agent-context/codex/README.md)
- [library/sub-agent-samples/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)
- [package.json](https://github.com/product-on-purpose/pm-skills/blob/main/package.json)
- [src/content.config.ts](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts)
- [src/styles/custom.css](https://github.com/product-on-purpose/pm-skills/blob/main/src/styles/custom.css)
</details>

# 技能生命周期管理

## 概述

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

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

| 子代理 | 用途 | 触发场景 |
|--------|------|----------|
| `pm-critic` | 对抗性评审 | PRD 审查、OKR 审查、会议复盘审查 |
| `pm-skill-auditor` | 技能审计 | 预发布审计、漂移检测、跨切面检查 |
| `pm-changelog-curator` | 变更日志整理 | 版本发布变更记录生成 |
| `pm-release-conductor` | 发布协调 | 发布流程编排、门控管理 |

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

## 三条叙事主线

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

| 叙事主线 | 产品类型 | PM 场景特点 |
|----------|----------|-------------|
| **Brainshelf** | 消费级 PKM（个人知识管理）应用 | 消费产品 PM 上下文 |
| **Storevine** | B2B 营销分析平台 | 数据产品 / 分析 PM 上下文 |
| **Workbench** | 内部平台工具团队 | 平台 / 开发者体验（DX）PM 上下文 |

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

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

## 技能文件结构

### 技能目录组织

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

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

### 技能链接规范

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

```markdown
[`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 配置管理：

```typescript
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: '.',
    }),
    // ...
  }),
};
```

### 内容加载规则

| 模式 | 说明 |
|------|------|
| `docs/**/*.{md,mdx}` | 文档主内容 |
| `!docs/internal/**` | 排除内部文件（gitignored） |
| `!docs/templates/**` | 排除模板文件 |
| `!docs/**/README.md` | 排除 GitHub 目录自动渲染页 |
| `library/skill-output-samples/**/sample_*.md` | 包含技能输出样本 |
| `!sample_*_legacy_*.md` / `!sample_*_orbit_*.md` | 排除历史遗留样本 |

资料来源：[src/content.config.ts:30-45]()

### Slug 生成策略

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

| 源文件路径 | 生成 Slug |
|------------|-----------|
| `docs/foo/bar.md` | `foo/bar` |
| `docs/skills/index.md` | `skills` |
| `library/skill-output-samples/define-hypothesis/sample_X.md` | `samples/define-hypothesis/sample_X` |
| `docs/README.md` | `readme`（统一小写） |

资料来源：[src/content.config.ts:55-75]()

## 子代理样本体系

### 样本文件规范

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

```yaml
---
title: <样本标题>
description: <场景描述>
artifact: <子代理输出类型>
version: <版本号>
repo_version: <仓库版本>
created: <创建日期>
status: sample
thread: <brainshelf|storevine|workbench>
context: <上下文说明>
---
```

### 样本结构

每个样本文件包含三个主要部分：

1. **Scenario（场景）**：触发子代理调用的具体情况（产物、受众、触发器）
2. **Output（输出）**：子代理的实际输出（分级、发现、草稿、门控流程）
3. **Notes（备注）**：样本演示内容和与三线程目录的关联

资料来源：[library/sub-agent-samples/README.md:47-62]()

## 技能输出样本示例

以下是各子代理在不同叙事主线下的典型输出场景：

| 子代理 | 叙事主线 | 典型场景 | 输出特点 |
|--------|----------|----------|----------|
| `pm-critic` | Brainshelf | PRD 审查 | 1 P0 + 3 P1 + 2 P2 + 1 P3，覆盖契约完整性、可证伪性、实验设计 |
| `pm-critic` | Storevine | OKR 审查 | 2 P0 拒绝协议捕获（伪造基线 + 功能交付 KR） |
| `pm-critic` | Workbench | 会议复盘审查 | 1 P0 家族契约违反：决策无负责人 |
| `pm-skill-auditor` | Brainshelf | 预发布审计 | 2 P1 前瞻性发现 + 3 P2 周期内预期漂移 |
| `pm-skill-auditor` | Storevine | 漂移检测 | 1 P0 CONTEXT.md 声明与文件系统派生不匹配 |
| `pm-skill-auditor` | Workbench | 跨切面检查 | 1 P0 孤立命令 + 1 P1 缺失配对 |
| `pm-changelog-curator` | Brainshelf | 次要版本草稿 | 50 commits；5 Added + 2 Changed + 1 Fixed + 2 Security + 1 Known Limitations |
| `pm-changelog-curator` | Storevine | 补丁版本草稿 | 3 commits；2 Fixed + 1 Security |
| `pm-changelog-curator` | Workbench | 功能版本草稿 | 80 commits；多轨形态跨越子代理 + 内容 + hooks + 解析器 |
| `pm-release-conductor` | Brainshelf | 干净运行 | 全部 6 个门控首次通过；基线形态 |
| `pm-release-conductor` | Storevine | 门控失败恢复 | G0 聚合计数器漂移 + 维护者恢复（失败恢复循环；无绕过；G0 幂等性） |
| `pm-release-conductor` | Workbench | 链式干跑 | 审计员在 G0 + G2.5；策展人在 G2；分层 Status 信封 |

资料来源：[library/sub-agent-samples/README.md:18-35]()

## 发布门控系统

`pm-release-conductor` 子代理实现了多层级发布门控（Gate）系统：

### 门控层级

| 门控层级 | 触发时机 | 检查内容 |
|----------|----------|----------|
| G0 | 初始阶段 | 审计员执行基线检查 |
| G2 | 中期阶段 | 策展人执行变更日志验证 |
| G2.5 | 中后期 | 审计员执行补充检查 |
| G3 | 最终阶段 | 综合评审 |

### 门控状态信封

每个门控结果使用统一的状态信封结构（符合 D26 规范）：

```json
{
  "status": "PASS|FAIL|WARNING",
  "gate": "G0|G2|G2.5|G3",
  "findings": [...],
  "recommendations": [...]
}
```

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

## 技术栈与构建系统

pm-skills 采用以下技术栈：

| 组件 | 版本 | 用途 |
|------|------|------|
| Astro | ^6.3.0 | 静态站点生成器 |
| @astrojs/starlight | ~0.39.0 | 文档框架 |
| astro-mermaid | ~2.0.1 | Mermaid 图表集成 |
| sharp | ^0.34.5 | 图片处理 |
| Mermaid | ^11.15.0 | 图表渲染 |
| Node.js | >=22.12.0 | 运行时要求 |

资料来源：[package.json:1-25]()

### 构建流程

```bash
npm run build    # 执行 astro build + post-build-strip-md-links 脚本
npm run dev      # 开发服务器
npm run preview  # 预览构建结果
```

资料来源：[package.json:10-15]()

## 可视化样式配置

### Mermaid 图表样式

文档站点的 Mermaid 图表使用自定义样式规则：

```css
.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:18-35]()

## 工作流与技能协调

### 多技能工作流定义

`_workflows/` 目录定义了多技能工作流，作为常见 PM 流程的引导式技能序列。每个 `.md` 文件对应一个完整的工作流定义，使用仓库相对路径引用相关技能文件。

### 子代理任务分配

| 子代理 | 典型任务 | 协调关系 |
|--------|----------|----------|
| `pm-critic` | 质量把关 | 上游输入评审 |
| `pm-skill-auditor` | 一致性检查 | 中游验证 |
| `pm-changelog-curator` | 版本记录 | 下游文档化 |
| `pm-release-conductor` | 流程编排 | 全局协调 |

资料来源：[_workflows/README.md:1-20]()

## 最佳实践

### 技能文件编辑

- 直接编辑 `docs/` 目录下的内容
- **不要**直接编辑 `docs/workflows/` 目录下的文件（这些由脚本自动生成）
- 使用 `scripts/generate-workflow-pages.py` 脚本从 `_workflows/` 目录生成工作流页面

### 代理会话管理

Codex 工作区使用以下策略管理会话：

- **持久化文件**（由 git 追踪）：`CONTEXT.md`、`DECISIONS.md`、`WRAP-SESSION_TEMPLATE.md`、`WORKTREE-PRIMER.md`
- **本地文件**（被 gitignore）：`PLANNING/**`、`TODO.md`
- **会话日志**：写入共享的 `AGENTS/SESSION-LOG/` 目录

资料来源：[_agent-context/codex/README.md:5-20]()

## 总结

技能生命周期管理在 pm-skills 项目中体现为：

1. **结构化技能定义**：每个 PM 技能以标准化目录结构存储在 `skills/` 下
2. **多场景验证**：通过三条叙事主线（Brainshelf、Storevine、Workbench）确保技能在不同上下文中的一致性
3. **自动化质量保障**：子代理系统（pm-critic、pm-skill-auditor 等）覆盖从设计到发布的全流程
4. **版本化文档系统**：基于 Astro Starlight 的文档站点支持技能输出样本的持续积累
5. **发布门控机制**：多层级门控系统确保发布质量，失败恢复机制保障流程健壮性

---

<a id='sub-agents'></a>

## 子代理系统

### 相关页面

相关主题：[工作流系统](#workflows), [工具家族](#tool-families)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [library/sub-agent-samples/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)
- [src/content.config.ts](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts)
- [package.json](https://github.com/product-on-purpose/pm-skills/blob/main/package.json)
- [src/styles/custom.css](https://github.com/product-on-purpose/pm-skills/blob/main/src/styles/custom.css)
- [_workflows/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/README.md)
- [_agent-context/codex/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/_agent-context/codex/README.md)
</details>

# 子代理系统

子代理系统是 pm-skills 项目中的核心模块化组件架构，旨在为产品管理流程提供专业化、可复用的 AI 辅助能力。每个子代理（Sub-agent）专注于特定的产品管理任务，通过标准化的接口与主系统集成。

## 系统概述

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

| 子代理名称 | 主要职能 | 输出产物 |
|---|---|---|
| `pm-critic` | 对 PRDs、OKRs、会议决策等进行对抗性审查 | 分级审查报告（P0/P1/P2/P3 问题标注） |
| `pm-skill-auditor` | 审计技能定义的完整性和一致性 | 审计报告（漂移检测、孤岛检测） |
| `pm-changelog-curator` | 根据提交记录生成规范的变更日志 | CHANGELOG 草稿 |
| `pm-release-conductor` | 协调发布流程中的多阶段门控验证 | 发布流程状态报告 |

资料来源：[library/sub-agent-samples/README.md:1-40](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

## 子代理线程模型

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

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

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

```mermaid
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](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

## 子代理详细规格

### pm-critic

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

**典型场景：**

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

**问题分级标准：**

| 级别 | 含义 | 示例问题类型 |
|---|---|---|
| P0 | 致命问题 | 契约完整性违规、基线数据伪造 |
| P1 | 严重问题 | 可证伪性不足、实验设计缺陷 |
| P2 | 一般问题 | 文档完整性缺失 |
| P3 | 轻微问题 | 格式规范问题 |

资料来源：[library/sub-agent-samples/README.md:30-35](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

### 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](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

### pm-release-conductor

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

**门控层级：**

| 门控级别 | 验证内容 | 失败策略 |
|---|---|---|
| G0 | 聚合计数器校验 | 失败后维护者介入恢复 |
| G1 | 基础构建验证 | 自动重试 |
| G2 | 变更日志完整性 | 需人工审批 |
| G2.5 | 跨代理协同验证 | 条件性通过 |

资料来源：[library/sub-agent-samples/README.md:55-60](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

## 示例样本规范

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

```yaml
# 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](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

## 内容配置与集成

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

```typescript
// 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](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts)

## 依赖关系

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

| 依赖项 | 版本 | 用途 |
|---|---|---|
| Astro | ^6.3.0 | 文档框架 |
| @astrojs/starlight | ~0.39.0 | 文档主题 |
| astro-mermaid | ~2.0.1 | Mermaid 图表渲染 |
| mermaid | ^11.15.0 | 图表生成 |
| sharp | ^0.34.5 | 图像处理 |

资料来源：[package.json:1-25](https://github.com/product-on-purpose/pm-skills/blob/main/package.json)

## 样式定制

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

```css
/* 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](https://github.com/product-on-purpose/pm-skills/blob/main/src/styles/custom.css)

## 子代理调用流程

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

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

## 相关文档路径

| 文档类型 | 路径 |
|---|---|
| 概念文档 | `docs/concepts/sub-agents.md` |
| 运行时组件参考 | `docs/reference/runtime-components.md` |
| 子代理兼容性矩阵 | `docs/reference/sub-agent-compatibility.md` |
| 子代理定义 | `agents/` |
| 示例样本库 | `library/sub-agent-samples/` |

资料来源：[_workflows/README.md:1-20](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/README.md)

---

<a id='workflows'></a>

## 工作流系统

### 相关页面

相关主题：[子代理系统](#sub-agents), [工具家族](#tool-families)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [_workflows/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/README.md)
- [docs/workflows/index.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/workflows/index.md)
- [docs/guides/using-workflows.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/guides/using-workflows.md)
- [docs/guides/workflows-guide.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/guides/workflows-guide.md)
- [_workflows/feature-kickoff.md](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/feature-kickoff.md)
- [_workflows/sprint-planning.md](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/sprint-planning.md)
- [_workflows/product-strategy.md](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/product-strategy.md)
</details>

# 工作流系统

## 概述

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

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

## 架构设计

### 双目录结构

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

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

| 目录 | 用途 | 可编辑性 |
|------|------|----------|
| `_workflows/` | 工作流定义源文件 | 可直接编辑 |
| `docs/workflows/` | 生成的文档站点 | 自动生成，不可手动编辑 |

资料来源：[_workflows/README.md:13-17]()

### 链接约定

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

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

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

## 工作流类型

### 预定义工作流

| 工作流 | 描述 | 源文件 |
|--------|------|--------|
| Feature Kickoff | 功能启动流程 | [`_workflows/feature-kickoff.md`](_workflows/feature-kickoff.md) |
| Sprint Planning | 冲刺规划流程 | [`_workflows/sprint-planning.md`](_workflows/sprint-planning.md) |
| Product Strategy | 产品战略流程 | [`_workflows/product-strategy.md`](_workflows/product-strategy.md) |

### 工作流结构

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

```mermaid
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/` 目录，使用专用脚本：

```bash
scripts/generate-workflow-pages.py
```

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

资料来源：[_workflows/README.md:13-17]()

### 生成配置

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

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

资料来源：[src/content.config.ts:7-16]()

## 工作流与子代理系统

### 子代理类型

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

| 子代理 | 功能 | 与工作流的关系 |
|--------|------|----------------|
| `pm-critic` | 对抗性审查 | 工作流产出的评审 |
| `pm-skill-auditor` | 技能审计 | 工作流合规性检查 |
| `pm-changelog-curator` | 变更日志整理 | 发布流程的一部分 |
| `pm-release-conductor` | 发布编排 | 工作流执行协调 |

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

### 执行流程

```mermaid
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 代理使用：

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

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

资料来源：[docs/guides/using-workflows.md]()

### 工作流最佳实践

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

## 相关资源

| 资源 | 路径 | 描述 |
|------|------|------|
| 工作流索引 | `docs/workflows/index.md` | 所有工作流的入口页面 |
| 使用指南 | `docs/guides/using-workflows.md` | 详细的使用说明 |
| 工作流指南 | `docs/guides/workflows-guide.md` | 工作流系统完整指南 |
| 技能系统 | `skills/` | 工作流引用的技能定义 |
| 子代理库 | `library/sub-agent-samples/` | 子代理输出示例 |

---

<a id='tool-families'></a>

## 工具家族

### 相关页面

相关主题：[工作流系统](#workflows), [技能分类体系](#skill-categories)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/concepts/foundation-sprint.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/concepts/foundation-sprint.md)
- [docs/concepts/design-sprint.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/concepts/design-sprint.md)
- [docs/guides/using-foundation-sprint.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/guides/using-foundation-sprint.md)
- [docs/guides/using-design-sprint.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/guides/using-design-sprint.md)
- [docs/reference/workshop-method-comparison.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/reference/workshop-method-comparison.md)
</details>

# 工具家族

工具家族（Tool Family）是 pm-skills 项目中用于组织和管理产品管理（PM）相关技能的层次化分类体系。该体系通过结构化的方法论框架，将不同的产品管理工作流、技能模板和子代理整合为统一的工具体系。

## 概述

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

### 工具家族的核心组成

| 工具名称 | 类型 | 主要用途 |
|---------|------|---------|
| Foundation Sprint | 概念工具 | 需求发现与问题定义 |
| Design Sprint | 概念工具 | 快速原型与方案验证 |
| PM 子代理 | 执行代理 | 自动化评审与审查 |
| 工作流编排 | 流程工具 | 多工具协同作业 |

资料来源：[docs/concepts/foundation-sprint.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/concepts/foundation-sprint.md)

## 核心工具详解

### Foundation Sprint

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

**核心阶段：**

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

资料来源：[docs/guides/using-foundation-sprint.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/guides/using-foundation-sprint.md)

### Design Sprint

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

**标准流程：**

```mermaid
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](https://github.com/product-on-purpose/pm-skills/blob/main/docs/concepts/design-sprint.md)

## 工具编排与工作流

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

### 工作流类型

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

**链接约定：**

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

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

资料来源：[_workflows/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/README.md)

### 工作流生成机制

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

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

## 子代理体系

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

### 子代理类型

| 子代理 | 功能 | 输出类型 |
|-------|------|---------|
| pm-critic | 对抗性评审 | 问题分级报告 |
| pm-skill-auditor | 技能审计 | 审计发现清单 |
| pm-changelog-curator | 变更日志整理 | 格式化的变更条目 |
| pm-release-conductor | 发布流程控制 | 门控状态信封 |

资料来源：[library/sub-agent-samples/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

### 子代理样本模式

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

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

## 叙事线程架构

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

### 线程定义

| 线程 | 上下文领域 | 描述 |
|-----|-----------|------|
| Brainshelf | 消费者 PKM 应用 | 个人知识管理场景 |
| Storevine | B2B 营销分析平台 | 数据产品分析场景 |
| Workbench | 内部平台工具团队 | 平台/DX 产品场景 |

资料来源：[library/sub-agent-samples/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

## 方法论对比

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

### Workshop 方法对比

| 方法 | 目标 | 时长 | 输出物 |
|-----|------|------|--------|
| Foundation Sprint | 问题定义与假设构建 | 1-2 周 | 需求文档、假设列表 |
| Design Sprint | 原型验证与方案选择 | 5 天 | 可测试原型、验证结论 |
| 敏捷冲刺 | 增量交付与迭代 | 2-4 周 | 可部署功能 |

资料来源：[docs/reference/workshop-method-comparison.md](https://github.com/product-on-purpose/pm-skills/blob/main/docs/reference/workshop-method-comparison.md)

## 技术架构

### 文档生成架构

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

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

### 内容集合配置

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

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

资料来源：[src/content.config.ts](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts)

### 自定义字段扩展

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

| 字段 | 类型 | 用途 |
|-----|------|------|
| generated | boolean | 标记自动生成内容 |
| source | string | 原始来源引用 |
| phase | string | 生命周期阶段 |
| classification | string | 内容分类 |
| version | string/number | 版本标识 |

## 使用指南

### 选择合适的工具

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

### 工具集成模式

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

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

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

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

## 最佳实践

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

## 扩展工具家族

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

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

---

<a id='installation-guide'></a>

## 安装与平台配置

### 相关页面

相关主题：[项目介绍](#project-introduction), [样本输出库](#sample-outputs)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/product-on-purpose/pm-skills/blob/main/package.json)
- [src/content.config.ts](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts)
- [src/styles/custom.css](https://github.com/product-on-purpose/pm-skills/blob/main/src/styles/custom.css)
- [_workflows/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/_workflows/README.md)
- [_agent-context/codex/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/_agent-context/codex/README.md)
- [library/sub-agent-samples/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)

> **注意**：以下文件在仓库中存在但本次检索未返回实际内容，页面基于现有上下文推理：
> - `docs/getting-started/index.md`
> - `docs/getting-started/quickstart.md`
> - `docs/getting-started/platforms.md`
> - `scripts/sync-claude.md`
> - `.claude-plugin/plugin.json`

</details>

# 安装与平台配置

## 概述

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

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

## 环境要求

### 系统依赖

| 组件 | 最低版本 | 说明 |
|------|----------|------|
| Node.js | >= 22.12.0 | 必须使用 LTS 或更新版本 |
| npm/yarn/pnpm | 最新稳定版 | 用于包管理 |

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

### 核心依赖包

| 包名 | 版本 | 用途 |
|------|------|------|
| astro | ^6.3.0 | 文档站点框架 |
| @astrojs/starlight | ~0.39.0 | Starlight 文档主题 |
| astro-mermaid | ~2.0.1 | Mermaid 图表集成 |
| sharp | ^0.34.5 | 图片处理优化 |

资料来源：[package.json:13-20]()

## 安装步骤

### 1. 克隆仓库

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

### 2. 安装依赖

```bash
npm install
```

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

### 3. 开发模式启动

```bash
npm run dev
```

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

### 4. 构建生产版本

```bash
npm run build
```

构建过程包含两个步骤：

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

资料来源：[package.json:11-15]()

### 5. 预览构建结果

```bash
npm run preview
```

## 平台配置

### 文档内容配置

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

#### 内容集合架构

```mermaid
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]()

| 模式类型 | 路径模式 | 说明 |
|----------|----------|------|
| 包含 | `docs/**/*.{md,mdx}` | 文档目录下的所有 Markdown 文件 |
| 排除 | `!docs/internal/**` | 内部工作文件（gitignored） |
| 排除 | `!docs/templates/**` | 模板目录 |
| 排除 | `!docs/**/README.md` | 目录级 README 文件 |
| 包含 | `library/skill-output-samples/**/sample_*.md` | 技能输出示例 |
| 排除 | `!library/skill-output-samples/**/sample_*_legacy_*.md` | 历史遗留示例 |
| 排除 | `!library/skill-output-samples/**/sample_*_orbit_*.md` | Orbit 相关示例 |

#### 自定义 Slug 生成

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

| 原始路径 | 生成 Slug |
|----------|-----------|
| `docs/foo/bar.md` | `foo/bar` |
| `docs/skills/index.md` | `skills` |
| `library/skill-output-samples/define-hypothesis/sample_X.md` | `samples/define-hypothesis/sample_X` |
| `docs/section/README.md` | `section/readme` |

### 自定义字段模式

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

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `generated` | boolean | 标记是否为自动生成内容 |
| `source` | string | 原始来源路径 |
| `phase` | string | 开发阶段 |
| `classification` | string | 分类标签 |
| `version` | string \| number | 版本号（支持 semver 格式） |
| `updated` | string \| Date | 更新时间 |
| `artifact` | string | 子代理输出类型 |
| `repo_version` | string \| number | 仓库版本 |
| `created` | string \| Date | 创建时间 |
| `status` | string | 状态标记 |
| `thread` | string | 叙事线程（brainshelf/storevine/workbench） |
| `context` | string | 上下文描述 |

### Mermaid 图表配置

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

#### 样式规则

```css
/* 图表容器 */
.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]()

| 文件 | 用途 |
|------|------|
| `CONTEXT.md` | 稳定的当前状态事实 |
| `DECISIONS.md` | 已接受的决策及理由 |
| `WRAP-SESSION_TEMPLATE.md` | 交接模板 |
| `WORKTREE-PRIMER.md` | 干净分支工作流指南 |

### 本地忽略文件

以下文件类型被 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]()

```markdown
[`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]()

| 子代理 | 功能 |
|--------|------|
| `pm-critic` | 对 PRD、OKR、会议纪要进行对抗性审查 |
| `pm-skill-auditor` | 审计技能定义的完整性和一致性 |
| `pm-changelog-curator` | 生成符合规范的变更日志草稿 |
| `pm-release-conductor` | 编排发布流程的门控检查 |

#### 叙事线程

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

| 线程 | 场景 | 上下文 |
|------|------|--------|
| **Brainshelf** | 消费者 PKM 应用 | 产品经理的消费品视角 |
| **Storevine** | B2B 营销分析平台 | 数据产品的 PM 视角 |
| **Workbench** | 内部平台工具团队 | 平台/DX 的 PM 视角 |

## 常见问题排查

### 节点版本不匹配

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

```bash
node --version
```

确保版本 >= 22.12.0。

### 内容未出现在站点

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

### Mermaid 图表不渲染

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

---

<a id='sample-outputs'></a>

## 样本输出库

### 相关页面

相关主题：[技能结构解析](#skill-anatomy), [安装与平台配置](#installation-guide)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [library/sub-agent-samples/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/library/sub-agent-samples/README.md)
- [src/content.config.ts](https://github.com/product-on-purpose/pm-skills/blob/main/src/content.config.ts)
- [library/skill-output-samples/README.md](https://github.com/product-on-purpose/pm-skills/blob/main/library/skill-output-samples/README.md)
- [package.json](https://github.com/product-on-purpose/pm-skills/blob/main/package.json)
</details>

# 样本输出库

样本输出库（Skill Output Samples Library）是 pm-skills 项目中用于存储、分类和展示子代理（sub-agent）实际输出的标准化示例集合。该库为项目维护者、AI 代理和人类审查者提供了可验证的参考基准，确保子代理在不同场景下的行为符合预期规范。

## 设计目标与核心价值

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

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 项目定义了四个核心子代理，每个子代理产生特定类型的输出样本：

| 子代理名称 | 功能描述 | 输出类型 | 样本数量 |
|---|---|---|---|
| `pm-critic` | 对 PRD、OKR、会议决策等进行对抗性评审 | 分级评审报告（P0-P3） | 3 |
| `pm-skill-auditor` | 审计技能定义的完整性和一致性 | 审计发现清单 | 3 |
| `pm-changelog-curator` | 根据提交历史生成变更日志 | 结构化变更条目 | 3 |
| `pm-release-conductor` | 控制多阶段发布门控流程 | 门控状态信封 | 3 |

资料来源：[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 元数据格式：

```yaml
---
title: <样本标题>
description: <样本描述>
artifact: <子代理输出类型>
version: <版本号>
repo_version: <仓库版本>
agent_version: <代理版本>
created: <创建日期>
status: sample
thread: <叙事线程>
context: <场景上下文>
---
```

关键字段说明：

| 字段 | 类型 | 说明 |
|---|---|---|
| `title` | string | 样本的人类可读标题 |
| `artifact` | string | 子代理输出类型（如 grading-report、audit-findings） |
| `thread` | string | 叙事线程标识（brainshelf/storevine/workbench） |
| `status` | string | 固定值 `sample`，标识文件类型 |
| `created` | string/date | ISO 格式日期，YAML 可能解析为 Date 对象 |

资料来源：[library/sub-agent-samples/README.md:54-68]()

## 问题严重性分级

样本输出遵循统一的 P0-P3 问题严重性分级体系：

| 级别 | 名称 | 说明 | 典型示例 |
|---|---|---|---|
| P0 | 关键 | 必须立即修复，如合同违规、拒绝协议失效 | 伪造基线数据、关键决策缺失所有者 |
| P1 | 重要 | 应在当前周期内修复 | 前瞻性审计发现、实验设计缺陷 |
| P2 | 中等 | 应在合理周期内修复 | 预期漂移、可验证性不足 |
| P3 | 低 | 建议改进 | 文档清晰度、格式一致性 |

资料来源：[library/sub-agent-samples/README.md:34-50]()

## 工作流程

样本从创建到发布的完整工作流程如下：

```mermaid
graph TD
    A[场景定义] --> B[子代理执行]
    B --> C[输出捕获]
    C --> D[前端元数据标注]
    D --> E[样本文件写入]
    E --> F[内容配置加载]
    F --> G[文档站点发布]
    
    H[维护者审查] --> I{命名规范检查}
    I -->|通过| E
    I -->|失败| J[重命名排除]
    
    J --> K[保留磁盘历史]
    K -.-> L[不发布到站点]
```

### 样本命名约定

样本文件名遵循严格的命名模式：

```
sample_<sub-agent>_<thread>_<scenario>.md
```

示例：
- `sample_pm-critic_brainshelf_prd-review.md`
- `sample_pm-release-conductor_workbench_chained-run.md`

不符合命名模式的文件将被内容配置排除，不发布到文档站点，但保留在磁盘上供历史参考。

资料来源：[src/content.config.ts:25-30]()

## 内容配置集成

样本输出库通过 Astro 内容加载器与文档站点深度集成。配置位于 `src/content.config.ts`：

```typescript
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: '.',
})
```

### 排除规则

以下文件被排除在站点发布之外：

| 排除模式 | 原因 |
|---|---|
| `sample_*_legacy_*.md` | 历史遗留样本（9个），保留磁盘记录 |
| `sample_*_orbit_*.md` | Orbit 线程样本（2个），保留磁盘记录 |
| `docs/internal/**` | 发布计划和工作笔记，不对外公开 |
| `docs/templates/**` | 使用 `<placeholder>` 语法导致 YAML 解析问题 |

资料来源：[src/content.config.ts:18-30]()

### Slug 生成规则

样本文件的 URL slug 通过 `generateId` 函数自动生成：

```javascript
// library/skill-output-samples/define-hypothesis/sample_X.md
// → slug: 'samples/define-hypothesis/sample_X'
```

| 原始路径 | 生成 Slug |
|---|---|
| `docs/foo/bar.md` | `foo/bar` |
| `docs/skills/index.md` | `skills` |
| `library/skill-output-samples/define-hypothesis/sample_X.md` | `samples/define-hypothesis/sample_X` |

资料来源：[src/content.config.ts:36-45]()

## 示例场景说明

### PRD 对抗性评审

`pm-critic` 子代理对 Brainshelf 应用的产品需求文档进行评审，输出包含：
- 1 个 P0 合同完整性问题
- 3 个 P1 可证伪性设计缺陷
- 2 个 P2 实验设计问题
- 1 个 P3 文档清晰度建议

资料来源：[library/sub-agent-samples/README.md:35-36]()

### 发布门控流程

`pm-release-conductor` 子代理在 Workbench 项目中执行链式干运行：
- 审计门控 G0 和 G2.5 阶段
- 变更日志门控 G2 阶段
- 分层 Status 信封输出

资料来源：[library/sub-agent-samples/README.md:48-49]()

## 扩展前端字段

样本文件支持额外的 YAML 前端字段，由 Astro schema 定义：

```typescript
schema: docsSchema({
  extend: z.object({
    generated: z.boolean().optional(),
    source: z.string().optional(),
    phase: z.string().optional(),
    classification: z.string().optional(),
    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(),
    tags: z.array(z.string()).optional(),
    draft: z.boolean().optional(),
  }),
})
```

这些字段支持：
- `generated`: 标记自动生成的内容
- `source`: 溯源引用
- `phase`: 处理阶段
- `tags`: 分类标签

资料来源：[src/content.config.ts:56-77]()

## 技术栈依赖

样本输出库的展示依赖于以下技术组件：

| 组件 | 版本 | 用途 |
|---|---|---|
| Astro | ^6.3.0 | 静态站点生成框架 |
| @astrojs/starlight | ~0.39.0 | 文档主题系统 |
| astro-mermaid | ~2.0.1 | Mermaid 图表渲染 |
| mermaid | ^11.15.0 | 图表定义语言 |

资料来源：[package.json:1-20]()

## 维护指南

### 添加新样本

1. 在对应的 `library/sub-agent-samples/<sub-agent>/` 目录创建文件
2. 使用 `sample_<agent>_<thread>_<scenario>.md` 命名模式
3. 填写标准化的 YAML frontmatter
4. 在 `Scenario` 部分描述触发场景
5. 在 `Output` 部分展示实际代理输出
6. 在 `Notes` 部分说明样本的演示目的

### 样本验证清单

- [ ] 文件名符合命名约定
- [ ] frontmatter 包含所有必需字段
- [ ] P0-P3 分级与实际内容一致
- [ ] 场景上下文与叙事线程匹配
- [ ] 无敏感信息泄露

## 相关资源

- 子代理定义：[agents/](../../agents/)
- 技能定义：[skills/](../../skills/)
- 运行时组件：[docs/reference/runtime-components.md](../../docs/reference/runtime-components.md)
- 对抗性评审指南：[docs/guides/adversarial-review.md](../../docs/guides/adversarial-review.md)
- 发布手册：[docs/contributing/release-runbook.md](../../docs/contributing/release-runbook.md)

资料来源：[library/sub-agent-samples/README.md:130-137]()

---

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: product-on-purpose/pm-skills; human_manual_source: deepwiki_human_wiki -->