skills.rest
alvis
alvisCOMMUNITY
Explore all skills by this author →
Website𝕏@alvishttangGitHub

sync-notion

Synchronize paired local Markdown files and Notion pages with guarded conflict resolution.

4|1|Updated Jul 31, 2025
Search Tags:#markdown#specification#notion#sync#conflict resolution#transport profile#two-way merge
One-click install
npx skills add https://github.com/alvis/.agents --skill sync-notion-alvis
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: sync-notion
Source: https://github.com/alvis/.agents/tree/main/plugins/specification/skills/sync-notion
Command: npx skills add https://github.com/alvis/.agents --skill sync-notion-alvis

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Keeping local Markdown specification files and their Notion page counterparts in sync is error-prone: stale mirrors, ambiguous page identity, and unguarded writes can silently overwrite work. This Skill transports declared local–Notion pairs in a chosen direction while validating transport identity metadata and enforcing guarded, conflict-aware mutations. ## Core Features & Use Cases - Bidirectional Sync Modes: Run validate-metadata, local-to-notion, notion-to-local, or two-way-merge against explicitly declared file/page pairs. - Transport Trust Verification: Validate a destination-owned notion-sync transport profile (executable hash, version, capability vectors, conformance evidence) before any remote operation. - Guarded Conflict Resolution: Classify base/local/remote states, build conflict packets, and require explicit approval plus conditional update/create capabilities before any mutation. - Use Case: A team keeps engineering specifications as local .mdc files mirrored to a Notion database; use this Skill to push approved local changes to Notion only after verifying the remote revision has not drifted. ## Quick Start Sync my local specification file specs/payment-flow.mdc to its paired Notion page using two-way merge with my validated transport profile.

Frequently Asked Questions about sync-notion

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I sync local Markdown files with Notion pages?▼

Declare each local file and Notion page pair, choose a mode (local-to-notion, notion-to-local, or two-way-merge), and supply a validated transport profile. The skill pulls fresh remote state, compares revisions, and mutates only through guarded conditional operations after approval.

How do I validate Notion transport metadata in .mdc files?▼

Run the validate-metadata mode with one or more exact .mdc paths. It read-only checks frontmatter identity keys (ref, parent, last_edited_time) via the bundled script and never reads tokens, loads profiles, or interprets body content.

What is a notion-sync transport profile and why is it required?▼

A transport profile is a destination-owned JSON file declaring the notion-sync executable path, SHA-256, version, capability vectors, and checksum-bound conformance evidence. Every remote operation requires it; missing, unsafe, or unproven profiles are refused as transport_unverified before any Notion query.

What happens when local and Notion versions of a page both changed?▼

The two-way-merge mode performs a three-way comparison of immutable base, local, and fresh remote bytes. Overlapping conflicts produce conflict packets with Keep Local, Keep Remote, and Keep Both candidates; nothing is applied or pushed until each conflict is explicitly resolved and approved.

Why does a sync return refused with provide_conditional_transport?▼

The transport profile declared the required conditional capability (conditional_update for existing pages or conditional_create for new pages) unavailable. Without that atomic precondition the skill refuses before any remote or canonical local mutation; supply a transport that proves the capability.

Can this skill create or interpret Notion page body content?▼

No. Transport bodies are opaque to this skill; semantic body creation or change requires an explicitly selected body-author capability passed as --body-author=<plugin:skill>. It only transports bytes and validates identity metadata, never interpreting body grammar.

Related Skills

Explore More Software Engineering Skills→
VegaStackVegaStack

notion-markdown-sync

Synchronize local markdown files with Notion pages bi-directionally.

Official
Advanced
UniClipboardUniClipboard
1.6k

plan-reviewer

Reviews Markdown implementation plans against repository code through independent adversarial passes.

Official
Intermediate
EndUser123EndUser123

nlm-skill

Orchestrate NotebookLM via CLI and MCP to manage notebooks, sources, and artifacts.

Community
Advanced
harshav167harshav167

appmigrationkit

Migrate app data between iOS and Android using AppMigrationKit extension protocols.

Community
Advanced