for AI agents
A SKILL.md that teaches your agent Notion Arena, in the agent's own language.
One Markdown file your agent reads before it touches anything Notion-shaped. It encodes the honesty policy, the three-channel decision table, every delivery-channel limitation, and the exact install flows — so the agent doesn't have to guess.
- Works with Claude Code, Cursor, Windsurf, Codex, any agent that reads SKILL.md
- Pairs naturally with the MCP server
- One file, no dependencies, MIT licensed
What it teaches the agent
The skill is the "why" — the mental model and the safety rails. The MCP server is the "what" — structured lookups and URL builders. You can use either alone, but they were written together.
The honesty policy
Never fabricate install counts. Never promise a widget can read Notion data. Say “I don't know” before guessing a parameter default.
The three-channel rule
Embed URL for speed, HTML block for offline/frozen templates, native recipe for real workspace data. Match the channel to what the user is actually trying to build.
The sandbox contract
Widgets have zero network and zero access to the parent page. If a request needs shared, synced state across teammates, it is a recipe, not a widget.
Plan-before-you-install
For native recipes, always run a dry-run plan first and show it to the user. Only request a Notion token after they have seen the request count and the manual steps.
Four steps to a smarter agent
- 1
Install the skill
Use the skills CLI (Vercel skills.sh), copy the file manually, or install via your agent's plugin marketplace.
- 2
Decide scope
Project scope (recommended) — the skill travels with the repo under .claude/skills/. Personal scope — available across every project in ~/.claude/skills/.
- 3
Pair with MCP (optional)
The skill tells the agent how to think about Notion Arena; the MCP server gives it structured tools. Together they cover browse, configure and install in one shot.
- 4
Ask for anything Notion-related
“Add a pomodoro timer to my dashboard”, “Give me an offline habit tracker”, “Install a CRM pipeline on this page” — the agent reads the skill, picks the right channel, and hands you the URL or the install plan.
npx skills add SynergyFlowLabs/notion-arena --skill notion-arenaWorks with Claude Code, Cursor and Windsurf. Add --all to install every skill in the repo.
mkdir -p .claude/skills
cp skills/notion-arena/SKILL.md \
.claude/skills/notion-arena/SKILL.mdDrop SKILL.md into ~/.claude/skills/notion-arena/ to make it personal.
Or just paste this prompt into your agent
Don't want to touch config files? Paste the block below into any coding agent (Claude Code, Cursor agent, Cascade, Codex) and it will read the skill from the local checkout and follow the rules in this session without a permanent install.
Teach yourself Notion Arena now. Read the skill at skills/notion-arena/SKILL.md and internalise its rules. When I next ask for something Notion-related, follow the skill exactly:
- Start by figuring out which channel I need: Embed URL for speed, HTML block for offline/templates I sell, native recipe for real workspace data.
- If I ask for a widget, search_components / get_component to pick the right slug and configure it sensibly (25-min pomodoro, brand accent, theme=auto unless I say otherwise).
- For native recipes, always show me the dry-run install plan before asking for a Notion token or parent page ID. List every manual step explicitly.
- Never tell me a widget can read or write Notion data — the HTML-block sandbox has no network and no bridge to the parent page.
- When you hand me a URL or a file, also tell me the three-step install path (/embed → paste, or /html → upload) so I don't have to look it up.
- Defaults: prefer HTML block for templates I sell or share (frozen, offline) and Embed URL for my own dashboards (auto-updates). Ask once if it's not obvious.Want the full skill reference, the decision matrix, and the worked examples? Read the skills documentation
Pair it with the MCP server.
The skill tells the agent how to reason about Notion Arena; the MCP server gives it ten structured tools to act on that reasoning. Most teams install both.