`), convert `
` to Notion's `
` (same), and strip unsupported tags.
9. **Do NOT include the page title in the body content.** The title goes into the `Name` property only.
---
### Step 5: Create or Update the Page in Notion
**For new pages (no existing `notion_page_id`):**
Use `CallMcpTool` with `notion-create-pages`:
```json
{
"server": "user-Notion",
"toolName": "notion-create-pages",
"arguments": {
"parent": {
"data_source_id": "21764093-21d9-81a8-baca-000b9e5d9228"
},
"pages": [
{
"properties": {
"Name": "
",
"Document Type": "",
"Document Status": ""
},
"content": ""
}
]
}
}
```
**For updates (existing `notion_page_id` in frontmatter):**
Use `CallMcpTool` with `notion-update-page`:
```json
{
"server": "user-Notion",
"toolName": "notion-update-page",
"arguments": {
"page_id": "",
"command": "replace_content",
"new_str": ""
}
}
```
Then update properties if they changed:
```json
{
"server": "user-Notion",
"toolName": "notion-update-page",
"arguments": {
"page_id": "",
"command": "update_properties",
"properties": {
"Name": "",
"Document Type": "",
"Document Status": ""
}
}
}
```
---
### Step 6: Record the Sync
After a successful push, update the local MD file's YAML frontmatter.
**If the file has no frontmatter yet, add one at the top:**
```yaml
---
notion_page_id: ""
notion_url: ""
document_type: ""
synced_at: ""
---
```
**If the file already has frontmatter, update these fields:**
- `notion_page_id` - keep the same (or set for first sync)
- `notion_url` - keep the same (or set for first sync)
- `document_type` - update if changed
- `synced_at` - update to current timestamp
This frontmatter is what enables idempotent syncs. On the next `/sync-to-notion-doc` run, the skill detects the `notion_page_id` and updates instead of creating a duplicate.
---
### Step 7: Confirm to User
After a successful sync, report:
> Synced to Notion.
> - **Page:** [Document Title](notion_url)
> - **Type:** Document Type
> - **Status:** Document Status
> - **Action:** Created new page / Updated existing page
If multiple files were synced (folder scan), provide a summary table.
---
## Error Handling
| Error | Action |
|-------|--------|
| File not found | Tell the user the path does not exist |
| Notion MCP not connected | Tell the user to run `/connect-mcps connect to notion` |
| Notion API error on create | Show the error, suggest checking the Notion workspace permissions |
| Notion API error on update (page not found) | The page may have been deleted in Notion. Ask the user if they want to create a new page instead. Remove the stale `notion_page_id` from frontmatter. |
| File has no content (empty) | Tell the user the file is empty and skip |
---
## Duplicate Prevention
The skill uses `notion_page_id` in the local file's YAML frontmatter as the single source of truth for sync state.
- **No `notion_page_id`** = new page, use `notion-create-pages`
- **Has `notion_page_id`** = existing page, use `notion-update-page`
Before creating a new page, optionally search Notion for a page with the same title to warn about potential duplicates:
```json
{
"server": "user-Notion",
"toolName": "notion-search",
"arguments": {
"query": "",
"data_source_url": "collection://21764093-21d9-81a8-baca-000b9e5d9228"
}
}
```
If a match is found, ask: "A page with this title already exists in Notion. Do you want to update it or create a new one?"
---
## Notion Documentation DB Schema Reference
The target database uses this schema:
| Property | Type | Values |
|----------|------|--------|
| Name | title | Document name (from first H1) |
| Document Type | select | Specification, Discovery, PRD, Policy, Standard, Standard Operating Procedure (SOP), Strategy, User Research |
| Document Status | select | Draft, Dev Review, Approved for Dev, In Dev, In Production, Archived |
| Product Lead | person | (optional, set manually in Notion) |
| Engineering Lead | person | (optional, set manually in Notion) |
| UX Lead | person | (optional, set manually in Notion) |
| GTM Lead | person | (optional, set manually in Notion) |
| Owner | person | (optional, set manually in Notion) |
| Author | person | (optional, set manually in Notion) |
| Document Version (1) | text | (optional, can be set if version info is in frontmatter) |
Person fields require Notion user IDs and cannot be set from Markdown content. They should be assigned manually in Notion after sync.
---
## Integration with Other Skills
This skill works with every skill that creates files in `outputs/`:
- `/prd-draft` creates files in `outputs/prds/` -> classify as PRD
- `/launch-checklist` creates files in `outputs/launches/` -> classify as Specification
- `/user-research-synthesis` creates files in `outputs/research-synthesis/` -> classify as User Research
- `/decision-doc` creates files in `outputs/decisions/` -> classify as Discovery
- `/write-prod-strategy` creates files in `outputs/roadmaps/` or strategy docs -> classify as Strategy
- `/status-update` creates files in `outputs/status-updates/` -> classify as Specification
After any of these skills completes, the assistant can offer: "Want me to push this to Notion?"
The user can either:
1. Say yes to sync immediately from `outputs/`.
2. Move the file to `notion-docs/` first and sync later.
---
## Notion-Flavored Markdown Quick Reference
For the complete spec, always fetch: `notion://docs/enhanced-markdown-spec`
Key differences from standard Markdown:
- **Tables** use XML (``, ``, ``) not pipe syntax
- **Toggles** use `` / ``
- **Callouts** use ``
- **Colors** use `{color="Color"}` attribute on blocks or `` for inline
- **Empty lines** need `` (blank lines are stripped)
- **Indentation** uses tabs, not spaces
- **Page title** goes in properties, not in page content
|