notion-workspace
Use this skill as the gateway to the notion-ao-research skill family. Establish connectivity once, register workspace metadata once, then let downstream skills run with stable identifiers and schema context.
Purpose
Initialize a Notion-compatible environment for research operations across agent platforms.
This skill handles:
- MCP connection setup baseline
- Workspace config creation and validation
- Runtime placeholder resolution rules used by all sibling skills
- Skill dispatch to the right specialized workflow
This skill does not perform day-to-day database operations. After setup, route operational requests to the family skill designed for that intent.
Quick Start
Connect MCP
- Configure a Notion MCP server on your platform.
- Verify authentication and tool visibility.
Create workspace config
- Create
NOTION_WORKSPACE.md in project root from the template in examples/workspace-config.md.
- Populate database registry, schema snippets, and project page registry.
Load research skills
- Use this skill for setup and registration only.
- Route daily operations to
notion-ao-ops, notion-ao-bulletin, or notion-page-designer.
Runtime Resolution
All skills in this family must resolve placeholders from the workspace config file at runtime.
Resolution protocol:
- Locate project-root
NOTION_WORKSPACE.md.
- Read the Database Registry table.
- Match the logical database name requested by task intent.
- Extract fields from the matched row:
<DATA_SOURCE_ID> from the registry data_source_id column<TITLE_PROPERTY> from the registry title-property column
- For page-targeted operations, read the Project Pages table and resolve
<PAGE_ID>.
- Use resolved values in tool calls and property payloads.
If NOTION_WORKSPACE.md is missing, stale, or ambiguous, stop execution and request workspace-config refresh before continuing.
Skill Family
| Skill |
Trigger Phrases |
What it does |
| notion-ao-workspace |
"set up Notion", "connect MCP", "workspace config" |
Setup and registration (this skill) |
| notion-ao-ops |
"add entry", "query milestones", "log experiment", "mark complete" |
NL research operations |
| notion-ao-bulletin |
"notion infra", "skill maintenance", "open issue" |
Infrastructure maintenance gate |
| notion-page-designer |
"design a page", "audit layout", "fix formatting" |
Page design and layout |
Workspace Configuration
NOTION_WORKSPACE.md is the shared runtime contract between users and agents.
Why it exists:
- Avoid repeated discovery queries every session
- Prevent hardcoded identifiers in skills
- Keep schema assumptions explicit and auditable
How agents use it:
- Resolve placeholders before any create/query/update operation
- Validate title property and key properties before writing
- Detect schema drift when expected properties/options no longer match
Minimum requirement: maintain one canonical NOTION_WORKSPACE.md per project root and keep it current with Notion-side schema changes.
Operating Guidance
- Prefer standard tool names in examples and workflows:
notion-fetchnotion-create-pagesnotion-update-pagenotion-searchnotion-create-databasenotion-create-view
- Keep this skill platform-neutral. Platform-specific automation belongs in
references/platform-integrations.md.
- Never hardcode project UUIDs in skill logic. Resolve from config at runtime.
Additional Resources
Reference Files
references/setup-guide.md — Multi-platform MCP setup, token creation, verification, and manual config-generation workflow.references/workspace-config-spec.md — Normative format spec for NOTION_WORKSPACE.md, required sections, field semantics, and maintenance protocol.references/platform-integrations.md — Optional platform enhancements and automation patterns.references/schema-design.md — Decision tree for helping users design new database schemas: master tables, input sections, property types, status lifecycles, and views.
Examples
examples/workspace-config.md — Copy-paste, self-documenting template for creating NOTION_WORKSPACE.md from scratch.
1---2name: notion-ao-workspace3description: This skill should be used when the user asks to "set up Notion", "connect Notion MCP", "create a notion workspace config", "configure Notion databases", "design a database", "create a new schema", "help me set up a DB", or "getting started with Notion". Establishes MCP connectivity, creates the workspace registry file, and routes to the correct notion-ao-* skill.4license: CC-BY-NC-SA-4.05---67# notion-workspace89Use this skill as the gateway to the notion-ao-research skill family. Establish connectivity once, register workspace metadata once, then let downstream skills run with stable identifiers and schema context.1011## Purpose1213Initialize a Notion-compatible environment for research operations across agent platforms.1415This skill handles:16- MCP connection setup baseline17- Workspace config creation and validation18- Runtime placeholder resolution rules used by all sibling skills19- Skill dispatch to the right specialized workflow2021This skill does not perform day-to-day database operations. After setup, route operational requests to the family skill designed for that intent.2223## Quick Start24251. **Connect MCP**26 - Configure a Notion MCP server on your platform.27 - Verify authentication and tool visibility.28292. **Create workspace config**30 - Create `NOTION_WORKSPACE.md` in project root from the template in `examples/workspace-config.md`.31 - Populate database registry, schema snippets, and project page registry.32333. **Load research skills**34 - Use this skill for setup and registration only.35 - Route daily operations to `notion-ao-ops`, `notion-ao-bulletin`, or `notion-page-designer`.3637## Runtime Resolution3839All skills in this family must resolve placeholders from the workspace config file at runtime.4041Resolution protocol:421. Locate project-root `NOTION_WORKSPACE.md`.432. Read the **Database Registry** table.443. Match the logical database name requested by task intent.454. Extract fields from the matched row:46 - `<DATA_SOURCE_ID>` from the registry `data_source_id` column47 - `<TITLE_PROPERTY>` from the registry title-property column485. For page-targeted operations, read the **Project Pages** table and resolve `<PAGE_ID>`.496. Use resolved values in tool calls and property payloads.5051If `NOTION_WORKSPACE.md` is missing, stale, or ambiguous, stop execution and request workspace-config refresh before continuing.5253## Skill Family5455| Skill | Trigger Phrases | What it does |56|---|---|---|57| notion-ao-workspace | "set up Notion", "connect MCP", "workspace config" | Setup and registration (this skill) |58| notion-ao-ops | "add entry", "query milestones", "log experiment", "mark complete" | NL research operations |59| notion-ao-bulletin | "notion infra", "skill maintenance", "open issue" | Infrastructure maintenance gate |60| notion-page-designer | "design a page", "audit layout", "fix formatting" | Page design and layout |6162## Workspace Configuration6364`NOTION_WORKSPACE.md` is the shared runtime contract between users and agents.6566Why it exists:67- Avoid repeated discovery queries every session68- Prevent hardcoded identifiers in skills69- Keep schema assumptions explicit and auditable7071How agents use it:72- Resolve placeholders before any create/query/update operation73- Validate title property and key properties before writing74- Detect schema drift when expected properties/options no longer match7576Minimum requirement: maintain one canonical `NOTION_WORKSPACE.md` per project root and keep it current with Notion-side schema changes.7778## Operating Guidance7980- Prefer standard tool names in examples and workflows:81 - `notion-fetch`82 - `notion-create-pages`83 - `notion-update-page`84 - `notion-search`85 - `notion-create-database`86 - `notion-create-view`87- Keep this skill platform-neutral. Platform-specific automation belongs in `references/platform-integrations.md`.88- Never hardcode project UUIDs in skill logic. Resolve from config at runtime.8990## Additional Resources9192### Reference Files9394- **`references/setup-guide.md`** — Multi-platform MCP setup, token creation, verification, and manual config-generation workflow.95- **`references/workspace-config-spec.md`** — Normative format spec for `NOTION_WORKSPACE.md`, required sections, field semantics, and maintenance protocol.96- **`references/platform-integrations.md`** — Optional platform enhancements and automation patterns.97- **`references/schema-design.md`** — Decision tree for helping users design new database schemas: master tables, input sections, property types, status lifecycles, and views.9899### Examples100101- **`examples/workspace-config.md`** — Copy-paste, self-documenting template for creating `NOTION_WORKSPACE.md` from scratch.
rooftop-Owl