custom-blocks · makenotion — Claude Code skill for Notion App custom blocks
A skill that routes your agent through the Notion App SDK docs before it touches custom block code. Useful when a project has interactive browser blocks.
npx skills add makenotion/notion-cookbook --skill custom-blocks -a claude-codeWhat custom-blocks does
The skill carries no logic of its own. It tells the agent to open node_modules/@notionhq/apps/skills/custom-blocks/SKILL.md before creating, editing or debugging custom block code, resolving that path from the App project root, and to follow what the file says.
Missing file? The agent installs project dependencies first. Still missing? @notionhq/apps needs a release that ships the skill. Until the SDK skill is readable, the agent stops — that is the hard edge here, and it means a stale dependency blocks all custom block work.
It is marked user-invocable: false, so you cannot call it from the chat. It fires on its own when the task involves custom blocks.
What it helps with
- scaffold a custom block for a Notion App
- debug an interactive block that stopped rendering
- port block code to a newer SDK release
- trace why a block fails in the browser
- install project dependencies before editing block code
Example prompts for the agent
- Add a Notion App custom block that renders a counter
- Fix the custom block — it no longer opens in the browser
- Update
@notionhq/appsand confirm the custom blocks SDK skill is present
How to install custom-blocks
1Skills CLI (Vercel)
npx skills add makenotion/notion-cookbook --skill custom-blocks -a claude-code2Manually: put the files in place
~/.claude/skills/custom-blocks/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/custom-blocks/
1Skills CLI (Vercel)
npx skills add makenotion/notion-cookbook --skill custom-blocks -a codex2Manually: put the files in place
.agents/skills/custom-blocks/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add makenotion/notion-cookbook --skill custom-blocks -a cursor2Manually: put the files in place
.cursor/skills/custom-blocks/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install makenotion/notion-cookbook custom-blocks2Manually: put the files in place
.github/skills/custom-blocks/SKILL.md1Skills CLI (Vercel)
npx skills add makenotion/notion-cookbook --skill custom-blocks -a gemini-cli2Platform CLI
gemini skills install https://github.com/makenotion/notion-cookbook --path apps/agents/skills/custom-blocksManually: put the files in place
.devin/skills/custom-blocks/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add makenotion/notion-cookbook --skill custom-blocks -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about custom-blocks
How do I install custom-blocks in Claude Code?
Run npx skills add makenotion/notion-cookbook --skill custom-blocks -a claude-code. The skill file lands at ~/.claude/skills/custom-blocks/SKILL.md.
What does custom-blocks do?
Before any custom block work, the agent reads node_modules/@notionhq/apps/skills/custom-blocks/SKILL.md and follows the instructions inside.
Why can't I invoke the skill manually?
It is flagged user-invocable: false. The agent picks it up on its own when a task involves Notion App custom blocks.
Source text
SKILL.md · MIT
--- name: custom-blocks description: Build interactive browser custom blocks declared by a Notion App. user-invocable: false --- # App custom blocks Before creating, modifying, or troubleshooting custom block code, read `node_modules/@notionhq/apps/skills/custom-blocks/SKILL.md`. Resolve this path relative to the App project root. Follow the instructions in that file. If the file is missing, install the project dependencies. If it remains missing, update `@notionhq/apps` to a release that includes the skill. Do not continue with custom block changes until you can read the SDK skill.
© makenotion · MIT · makenotion/notion-cookbook
Similar skills
All skills for Agent setup: memory, context, orchestration →custom-blocks by other authors comes first.
