For AI agents

Skill reference

A SKILL.md is the part of your agent's system prompt it reads when it detects it is working in a domain. The Notion Arena skill encodes the mental model, the safety rails, and the decision table that stops an agent from promising a widget can do things a Notion widget cannot do.

Install

Via skills CLI (recommended)

# One specific skill
npx skills add SynergyFlowLabs/notion-arena --skill notion-arena

# Every skill in the repo
npx skills add SynergyFlowLabs/notion-arena --all

# Pin a specific agent
npx skills add SynergyFlowLabs/notion-arena --skill notion-arena --agent cursor
npx skills add SynergyFlowLabs/notion-arena --skill notion-arena --agent windsurf

Manual install

Copy skills/notion-arena/SKILL.md from this repository into one of:

.claude/skills/notion-arena/SKILL.md — travels with the project (recommended for teams).
~/.claude/skills/notion-arena/SKILL.md — personal, available across every project.
.cursor/skills/notion-arena/ — for Cursor. Other agents read the same Markdown conventions; drop it into whichever skills folder your agent expects.

Versioning the skill

The installed SKILL.md is a snapshot. When you pull a new version of this repo, re-run skills add (or re-copy the file) to refresh the copy your agent reads.

What the skill encodes

When to trigger

The front-matter description field lists the triggers: Notion widget, embed, dashboard component, timer, tracker, kanban, CRM, installing into Notion, adding to Notion, building a template or system, and any reference to notion-arena.

The four policies

Honesty policy — never fabricate install counts; never promise a widget can read/write Notion data; if the workflow needs shared state, escalate to a recipe.
Three-channel rule — Embed URL for speed, HTML block for offline/frozen, native recipe for real data. Match the channel to the goal.
Sandbox contract — zero network, zero parent-page access, localStorage per-browser only.
Plan-before-you-install — always run a dry-run plan for native recipes and show it to the user before requesting a Notion token.

Reference material included

All 8 categories with emoji and when to reach for each.
The full widget contract (zero external requests, dual config source, theme and accent, namespaced storage, reduced motion).
Install flows for all three channels, including the exact File Upload API sequence for HTML blocks and the two-pass database/relation/rollup sequence for recipes.
Three worked examples (Pomodoro, CRM pipeline, offline habit tracker).
Authoring notes for contributors who want to add a new widget.

Customising the skill

SKILL.md is Markdown — edit it freely. Teams typically pin one or two project-specific choices:

Set NOTION_ARENA_SITE_URL to your self-hosted deployment so the agent hands out links pointing at your domain.
Add an approved-categories list (e.g. only dashboards and trackers) if you want the agent to ignore everything else.
Set a default accent color and theme so generated URLs match your workspace style without being asked.
Add house-specific install rules (e.g. "always deliver as HTML block in templates we sell").

The MCP server picks up NOTION_ARENA_SITE_URL from its own env block; customising the skill file alone does not change the server's behaviour — set the env on both sides if you self-host.

Pairing with the MCP server

The skill tells the agent how to think. The MCP server gives it structured tools. Without the skill the agent can still browse the catalog (the tools are self-describing), but it may choose the wrong channel or promise sandbox powers it does not have. Without the server the agent can still read the SKILL.md and hand out URLs, but it will have to fetch the catalog JSON over HTTP itself. Most teams install both.

The MCP install guide lives at /docs/mcp.