# Notion Provision

> Provision a Notion workspace (section pages + databases) from a YAML schema spec. Idempotent. Use when building a new Notion-based OS from a structured spec.

- Skill: `chiragg-ds/notion-provision` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add chiragg-ds/notion-provision`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chiragg-ds/notion-provision/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: chiragg-ds (https://skillmd.com/u/chiragg-ds)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chiragg-ds/notion-provision

---


# notion-provision

Create Notion section pages and databases from a YAML spec. Idempotent — re-running the same spec against the same root page reuses existing pages/DBs and only adds missing properties.

## Prerequisites

- `NOTION_API_KEY` env var (or `.env` file, or `.vscode/mcp.json`)
- A root page in the target Notion workspace, shared with the integration
- The page's ID (32-char hex, can be UUID-dashed or not)
- `pyyaml` installed in your environment
- `notion-os-toolkit` available (via pip or local sibling repo)

## Steps

1. Ask the user for the path to their YAML spec file (or build one if they describe sections + DBs in natural language).
2. Confirm the root page ID and that the integration is shared on it.
3. Read the spec and validate: required keys are `root_page_id`, `sections[].title`, `sections[].databases[].name`, `sections[].databases[].properties`.
4. Run:
   ```python
   from notion_os_toolkit import auth, client, provisioner
   nc = client.NotionClient(auth.load_token())
   ids = provisioner.provision_from_yaml(nc, "<spec-path>", out_path="ids.json")
   ```
5. If the spec has cross-DB relations, do them in a second pass (each relation property requires the target DB to already exist). Pattern:
   ```python
   nc.update_database(source_id, properties={
       "ClientRelation": {"relation": {"database_id": clients_db_id, "single_property": {}}},
   })
   ```
6. Report back: number of sections created, number of DBs created, path to `ids.json`.

## YAML spec shape

```yaml
root_page_id: "abc123..."
sections:
  - title: CRM
    icon: 👥
    databases:
      - name: Leads
        icon: 🎯
        properties:
          Lead Name: {title: {}}
          Lead Stage:
            select:
              options:
                - {name: Initial Contact}
                - {name: Won}
```

## Input/Output contract

**Input:** spec file path + root page ID
**Output:** `ids.json` mapping section titles + DB names to Notion IDs

## When NOT to use this skill

- If the workspace already exists and you just need to add ONE new DB — call the API directly with `nc.create_database`.
- If the user wants to seed data — use `notion-seed` instead.
- If the user wants helper formulas added — use `notion-helper-formulas`.

## Example invocation

User: "Build me a CRM in Notion with Leads, Clients, and Activities databases."

You: Draft a YAML spec covering those three DBs with reasonable properties. Confirm with user. Provision.

## Reference

- `scripts/run.py` — minimal driver script
- Notion API docs: https://developers.notion.com/reference/create-a-database