前言¶

很多團隊把 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