Preface¶

Many teams write PRDs and feature specifications in Notion: once requirements, acceptance criteria, and priorities are all in place, there is still a missing layer of “executable artifacts” when starting real development—implementation plans, tasks broken down by day, and progress tracking that can be written back. Specification pages and task libraries often operate independently, with broken links and out-of-sync statuses, leaving Specs stuck in the “written but not yet broken down” phase.

notion-spec-to-implementation is exactly the Agent Skill designed for this workflow: on the premise that Notion MCP is already connected, let the AI programming assistant read Notion specifications according to a fixed workflow, generate implementation plan pages and tasks, link Spec, Plan, and Tasks together, and subsequently update the status at a regular pace. It is included in the .curated directory of OpenAI’s openai/skills repository, follows the universal SKILL.md format, and can be used in tools that support Agent Skills such as Codex, Cursor, and Claude Code.

What It Is¶

One-sentence positioning: Convert PRD / feature specifications in Notion into implementation plans with milestones, task lists, and sustainable progress updates.

Source attribution: A curated Agent Skill maintained by OpenAI (path: skills/.curated/notion-spec-to-implementation). The official description is:

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

The dependency premise is clear: you must read and write the workspace through the official Notion remote MCP (https://mcp.notion.com/mcp). The Skill itself provides the workflow and templates; real search, page creation, and page modification are completed by the Notion MCP tool.

Core Features and Highlights¶

Based on the official SKILL.md, reference/ and examples/, the capabilities can be summarized into the following sections.

Locate and parse specifications
Use Notion:notion-search to find the Spec, then use Notion:notion-fetch to pull the full text. reference/spec-parsing.md provides extraction methods for common structures: requirement Specs, user stories, technical design documents, PRDs, etc. It will extract functional/non-functional requirements, acceptance criteria, priorities, dependencies and risks, and write ambiguous points into clarifications to avoid directly “blindly splitting tasks”.
Select plan depth according to complexity
Simple changes follow reference/quick-implementation-plan.md; multi-stage functions or migrations follow reference/standard-implementation-plan.md. The plan page generally includes: overview, associated Spec, requirement summary, phase division, dependencies and risks, success criteria, and is written to Notion via Notion:notion-create-pages.
Translate to task library
First search and confirm the schema of the task database (including data_source_id and required attributes), then create tasks according to reference/task-creation.md / task-creation-template.md. The official recommendation is that a single task should be about 1–2 days in size; the task content includes context, objectives, acceptance criteria, dependencies, resources; attributes can set title (action verb), status, priority, and association with Spec and Plan, with due dates, story points, and responsible persons as needed.
Two-way linking and progress backwriting
Link the Plan to the Spec, and link Tasks to both the Plan and the Spec; optionally add a short Implementation block on the Spec pointing to the plan and tasks (Notion:notion-update-page). During the implementation process, perform daily updates, phase summaries and status synchronization according to reference/progress-tracking.md, and the templates include progress updates and milestone summaries.
Includes reproducible examples
examples/ provides end-to-end walkthrough examples, such as api-feature.md (User Profile API), ui-component.md, database-migration.md, covering the complete call sequence of “search Spec → parse → create plan → create task → write back to Spec”.

Installation and Enable¶

1. Install the Skill¶

This Skill belongs to curated skills. In Codex, you can use the built-in $skill-installer to install by name:

$skill-installer notion-spec-to-implementation

You can also install via the GitHub directory URL:

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

You need to restart Codex after installation to load the new Skill.

In tools that also support the Agent Skills standard such as Cursor / Claude Code, you can put this directory (at least containing SKILL.md, and the required reference/ and examples/) into the corresponding Skills directory, for example:
- Cursor: project-level .cursor/skills/notion-spec-to-implementation/, or user-level ~/.cursor/skills/notion-spec-to-implementation/
- Claude Code: project-level .claude/skills/notion-spec-to-implementation/, or user-level ~/.claude/skills/notion-spec-to-implementation/

Cursor is also compatible with loading paths such as .claude/skills/ and .codex/skills/. After the directory is in place, the Agent can automatically select it according to the description, or call it explicitly in the conversation with a method like /notion-spec-to-implementation (subject to the actual discovery name of each tool).

The official repository README has marked openai/skills as deprecated and pointed to the new Plugins-related documentation; if you switch to plugin distribution later, please refer to OpenAI’s current documentation. The capabilities and installation methods described in this article are still subject to the original SKILL.md under this curated directory.

2. Configure Notion MCP (Required)¶

The Skill’s agents/openai.yaml declares a dependency on Notion MCP. Step 0 of the official workflow: if the call fails due to an unconnected MCP, complete the following Codex-side configuration first:

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

Enable the remote MCP client (choose one of the two):

# config.toml
[features]
rmcp_client = true

Or:

codex --enable rmcp_client

Then log in via OAuth:

codex mcp login notion

You need to restart Codex after a successful login before proceeding with the subsequent steps.

Notion’s official documentation also states that Notion MCP is a remote MCP hosted by Notion. After OAuth authorization, MCP clients such as Claude Code, Cursor, and Codex can search, read, create, and update Notion content that you have permission to access. In clients such as Cursor, you can add the same endpoint https://mcp.notion.com/mcp according to their respective MCP configuration methods and complete authorization; please refer to the client’s documentation for specific UI/configuration file fields.

Typical Usage Examples¶

The official default prompt (see agents/openai.yaml) can be used directly:

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

In Chinese scenarios, you can also specify the Spec name or link clearly, for example:

Please generate an implementation plan based on the "User Profile API Specification" in Notion, break down tasks with dependencies, and write back the progress tracking structure.

According to the official Quick start / Workflow, the Agent will roughly execute:
1. Notion:notion-search to locate the Spec; confirm with you when there are multiple results.
2. Notion:notion-fetch to read the full text, extract requirements, acceptance criteria, constraints and priorities according to spec-parsing.md, and record gaps and assumptions.
3. Select the quick / full plan template, and use Notion:notion-create-pages to create the plan page.
4. Find the task database, confirm the schema, then batch create tasks with a granularity of 1–2 days, and set attributes such as status, priority, and association.
5. Establish Spec ↔ Plan ↔ Tasks links; optionally update the Implementation section of the Spec.
6. Update status, daily updates and milestone summaries according to progress-tracking.md during implementation.

Take the official example examples/api-feature.md as an example: after the user requests “Create an implementation plan for the User Profile API spec”, the Agent will search and pull the “User Profile API Specification”, parse out functional requirements (such as getting profiles by ID, updating fields, avatar upload, public profiles, searching by name), non-functional requirements (such as p95 latency, concurrency, upload size, compliance) and acceptance criteria, then generate a phased plan (Foundation → Core Endpoints → Avatar → Search → Testing), create multiple tasks in the task library, and finally write the plan link back to the Spec. The example also demonstrates how to use data_source_id (in the form of collection://...) to create pages in the task database.

Applicable Scenarios and Notes¶

Applicable scenarios:
- PRD / feature Specs have been written in Notion, and need to be quickly translated into engineering plans and task libraries.
- Implementations that require phased and dependency/risk descriptions, such as multi-stage functions, APIs, and database table migrations.
- Hope that Specs, plans, and tasks can be linked to each other in Notion and progress can be continuously written back.

Precautions before use:
1. Without Notion MCP authorization, you cannot really read and write the workspace; the Skill will stop at the MCP configuration step.
2. The task database schema must be confirmed first: incorrect required attributes, associated fields, or data_source_id will cause task creation failures.
3. When the Spec is vague, the official process requires writing clarifications first instead of splitting tasks hard; plans split from low-quality Specs will also be unreliable.
4. The recommended task granularity is 1–2 days; too large or too small will affect tracking.
5. Progress updates depend on you continuing to use the same set of MCP + Skill workflow; it will not replace team-agreed reviews and scheduling decisions.
6. Workspace administrators can control MCP client access in Notion’s Connections / Admin capabilities, and confirm that policies allow access in enterprise environments.

Summary¶

notion-spec-to-implementation bundles the workflow of “Notion Spec → Implementation Plan → Tasks → Progress” into a reusable Agent workflow, uses official templates to constrain parsing, splitting, and backwriting, and reduces manual copy-pasting and broken links. If your requirement documents are already in Notion, and you usually use assistants that support Skills and MCP such as Codex / Cursor / Claude Code, it is worth installing and trying directly.

Official address:
https://github.com/openai/skills/tree/main/skills/.curated/notion-spec-to-implementation

Notion MCP instructions:
https://developers.notion.com/docs/mcp

Use notion-spec-to-implementation to split Notion PRD into executable plans