前言¶

很多团队把 PRD、功能规格写在 Notion 里：需求、验收标准、优先级都齐了，真正开工时却还缺一层「可执行物」——实现计划、按天拆好的任务、以及能回写的进度跟踪。规格页和任务库往往各管各的，链接断了、状态不同步，Spec 就容易停在「写完了但没人拆」的阶段。

notion-spec-to-implementation 正是针对这条链路设计的 Agent Skill：在已连接 Notion MCP 的前提下，让 AI 编程助手按固定工作流读取 Notion 规格，生成实现计划页与任务，并把 Spec、Plan、Tasks 互相链接，后续还能按节奏更新状态。它收录在 OpenAI 的 openai/skills 仓库 .curated 目录中，遵循通用的 SKILL.md 格式，可在 Codex、Cursor、Claude Code 等支持 Agent Skills 的工具里使用。

这是什么¶

一句话定位：把 Notion 里的 PRD / 功能规格，转成带里程碑的实现计划、任务清单，以及可持续的进度更新。

来源归属：OpenAI 维护的 Agent Skills 精选技能（路径为 skills/.curated/notion-spec-to-implementation）。官方描述是：

Turn Notion specs into implementation plans, tasks, and progress tracking; use when implementing PRDs/feature specs and creating Notion plans + tasks from them.

依赖前提很明确：必须通过 Notion 官方远程 MCP（https://mcp.notion.com/mcp）读写工作区。Skill 本身提供工作流与模板；真正的搜索、建页、改页由 Notion MCP 工具完成。

核心功能与亮点¶

根据官方 SKILL.md 与 reference/、examples/，能力可概括为下面几块。

1、定位并解析规格
用 Notion:notion-search 找到 Spec，再用 Notion:notion-fetch 拉取全文。reference/spec-parsing.md 给出了常见结构的抽取方式：需求型 Spec、用户故事、技术设计文档、PRD 等；会提取功能 / 非功能需求、验收标准、优先级、依赖与风险，并把模糊点写进 clarifications，避免直接「瞎拆任务」。

2、按复杂度选计划深度
简单改动走 reference/quick-implementation-plan.md；多阶段功能或迁移走 reference/standard-implementation-plan.md。计划页一般包含：概述、关联 Spec、需求摘要、阶段划分、依赖与风险、成功标准，并通过 Notion:notion-create-pages 写入 Notion。

3、落到任务库
先搜索并确认任务数据库的 schema（含 data_source_id 与必填属性），再按 reference/task-creation.md / task-creation-template.md 建任务。官方建议单任务体量约 1–2 天；任务内容含上下文、目标、验收标准、依赖、资源；属性侧可设置标题（动作动词）、状态、优先级，以及与 Spec、Plan 的关联，必要时带截止日期、故事点、负责人。

4、双向链接与进度回写
Plan 链到 Spec，Tasks 同时链到 Plan 与 Spec；可选在 Spec 上追加简短的 Implementation 区块指向计划与任务（Notion:notion-update-page）。实施过程中按 reference/progress-tracking.md 做日更、阶段小结与状态同步，模板包括进度更新与里程碑总结。

5、附带可复现示例
examples/ 中提供端到端走通示例，例如 api-feature.md（User Profile API）、ui-component.md、database-migration.md，覆盖「搜 Spec → 解析 → 建计划 → 建任务 → 回写 Spec」的完整调用顺序。

安装与启用¶

1. 安装 Skill¶

该 Skill 属于 curated 技能。在 Codex 中可用内置的 $skill-installer 按名称安装：

$skill-installer notion-spec-to-implementation

也可通过 GitHub 目录 URL 安装：

$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/notion-spec-to-implementation

安装后需重启 Codex，才能加载新 Skill。

在 Cursor / Claude Code 等同样支持 Agent Skills 标准的工具中，可把该目录（至少包含 SKILL.md，以及会用到的 reference/、examples/）放到对应 Skills 目录，例如：

• Cursor：项目级 .cursor/skills/notion-spec-to-implementation/，或用户级 ~/.cursor/skills/notion-spec-to-implementation/
• Claude Code：项目级 .claude/skills/notion-spec-to-implementation/，或用户级 ~/.claude/skills/notion-spec-to-implementation/

Cursor 也会兼容加载 .claude/skills/、.codex/skills/ 等路径。目录就位后，Agent 可按描述自动选用，也可在对话里用 /notion-spec-to-implementation 一类方式显式调用（以各工具实际发现名为准）。

官方仓库 README 已标注 openai/skills 为 deprecated，并指向新的 Plugins 相关文档；若你后续改走插件分发，以 OpenAI 当前文档为准。本文描述的能力与安装方式，仍以该 curated 目录下的一手 SKILL.md 为准。

2. 配置 Notion MCP（必需）¶

Skill 的 agents/openai.yaml 声明依赖 Notion MCP。官方工作流第 0 步：若 MCP 未连接导致调用失败，先完成下列 Codex 侧配置：

codex mcp add notion --url https://mcp.notion.com/mcp

启用远程 MCP 客户端（二选一）：

# config.toml
[features]
rmcp_client = true

或：

codex --enable rmcp_client

然后 OAuth 登录：

codex mcp login notion

登录成功后需要重启 Codex，再继续后续步骤。

Notion 官方文档也说明：Notion MCP 是 Notion 托管的远程 MCP，OAuth 授权后，Claude Code、Cursor、Codex 等 MCP 客户端均可搜索、读取、创建与更新你有权限的 Notion 内容。在 Cursor 等客户端中，按各自 MCP 配置方式添加同一端点 https://mcp.notion.com/mcp 并完成授权即可；具体 UI/配置文件字段以该客户端文档为准。

典型用法示例¶

官方默认提示词（见 agents/openai.yaml）可以直接用：

Turn this Notion spec into an implementation plan with milestones, tasks, and dependencies.

中文场景下，也可以说清楚 Spec 名称或链接，例如：

请根据 Notion 里的「User Profile API Specification」，生成实现计划，拆出带依赖的任务，并写回进度跟踪结构。

按官方 Quick start / Workflow，Agent 大致会执行：

1. Notion:notion-search 定位 Spec；多结果时向你确认。
2. Notion:notion-fetch 读取全文，按 spec-parsing.md 抽出需求、验收标准、约束与优先级，并记录缺口与假设。
3. 选择 quick / full 计划模板，用 Notion:notion-create-pages 创建计划页。
4. 找到任务数据库、确认 schema，再批量创建 1–2 天粒度的任务，并设置状态、优先级、关联等属性。
5. 建立 Spec ↔ Plan ↔ Tasks 链接；可选更新 Spec 的 Implementation 小节。
6. 实施中按 progress-tracking.md 更新状态、日更与里程碑总结。

以官方示例 examples/api-feature.md 为例：用户请求「Create an implementation plan for the User Profile API spec」后，Agent 会搜索并拉取「User Profile API Specification」，解析出功能需求（如按 ID 获取资料、更新字段、头像上传、公开资料、按名搜索）、非功能需求（如 p95 延迟、并发、上传大小、合规）与验收标准，再生成分阶段计划（Foundation → Core Endpoints → Avatar → Search → Testing），在任务库中创建多条任务，最后把计划链接写回 Spec。示例中还演示了如何用 data_source_id（形如 collection://...）向任务数据库建页。

适用场景与注意事项¶

适合：

• PRD / 功能 Spec 已经写在 Notion，需要快速落到工程计划与任务库。
• 多阶段功能、API、库表迁移等需要分阶段、带依赖与风险说明的实施。
• 希望 Spec、计划、任务在 Notion 内互相可跳转，并持续回写进度。

使用前注意：

1. 没有 Notion MCP 授权就无法真正读写工作区；Skill 会停在 MCP 配置步骤。
2. 任务库 schema 必须先确认：必填属性、关联字段、data_source_id 不对会导致建任务失败。
3. Spec 含糊时，官方流程要求先写 clarifications，而不是硬拆；质量差的 Spec 拆出来的计划同样不可靠。
4. 任务粒度建议 1–2 天；过大或过碎都会影响跟踪。
5. 进度更新依赖你继续用同一套 MCP + Skill 工作流；它不会替代团队约定的评审与排期决策。
6. 工作区管理员可在 Notion 的 Connections / Admin 能力中管控 MCP 客户端接入，企业环境需确认策略允许。

小结¶

notion-spec-to-implementation 把「Notion Spec → 实现计划 → 任务 → 进度」收成一套可复用的 Agent 工作流，用官方模板约束解析、拆分与回写，减少人工复制粘贴和断链。若你的需求文档已经在 Notion，而日常又用 Codex / Cursor / Claude Code 这类支持 Skills 与 MCP 的助手，它值得直接装上试用。

官方地址：
https://github.com/openai/skills/tree/main/skills/.curated/notion-spec-to-implementation

Notion MCP 说明：
https://developers.notion.com/docs/mcp