notion-skills

A skill store for your AI coding agents. Create and collaborate on skills in Notion, then install them on your computer.

Why

AI coding agents (Claude Code, Codex, OpenCode, Cursor, Gemini) all read skills — small SKILL.md files that tell an agent what to do and when. The format is shared, but each agent reads from its own folder, and authoring usually means tending markdown files in git to keep them synced across machines and teammates.

notion-skills puts your skills in a Notion database. You browse a shared store, install only what you want on each machine, and edit skills the way you edit any other Notion page.

• 🏪 Browse a shared store. Pick the skills that fit your workflow instead of syncing everything.
• ✏️ Edit in Notion. Use the rich editor; collaborate live; no IDE, no git, no PR review.
• 👥 Built for teams. One store, shared with everyone; each person installs what's relevant to them.
• 🤖 Generate with your agent. gen hands an idea off to your coding agent and writes you a draft.
• 🎯 Install once, every agent reads it. The same skill works in Claude, Codex, Cursor, and the rest.

Get started

brew install ntn               # the Notion CLI we shell out to
ntn login

npm install -g @brianlovin/notion-skills
notion-skills init             # interactive setup: pick a database + agents

Then:

notion-skills list                    # browse the store
notion-skills install <slug>          # install one skill
notion-skills install --tag featured  # install everything tagged "featured"
notion-skills sync                    # pull updates for installed skills
notion-skills publish <slug>          # share a local skill with the team

Type /skill-name in any agent CLI to invoke an installed skill.

Requires macOS or Linux and Node.js 18+.

Commands

| Command | What it does | |---|---| | init | First-time setup: create or link a Notion skill store. Re-run to add another source. | | list | See what's in the store(s). Filter with --installed, --available, --outdated, --drafts, --tag, --source. Sort with --sort name\|popular\|new. | | install <slug> | Pull a skill onto your machine. Refs are bare (deploy) or qualified (team/deploy). Bulk: --tag, --all (source-scoped). | | uninstall <slug> | Remove from your machine. The Notion page stays. | | sync | Pull updates for installed skills across every source. | | gen <input> | Generate a new skill from a URL, file, or prompt. Local-only until you publish. | | add <owner/repo> | Pull a public skill from a GitHub repo (mirrors skills.sh syntax). Lands as a local draft; --publish chains straight to a Notion source. | | feed | What's new across your stores: newly published skills + updates to skills you have installed. Defaults to the last 7 days; --since 30d, --since 2w, --since 12h for other windows. | | feedback <slug> [message...] | Read or post Notion comments on a skill. Bare reads existing comments newest-first; with a message, posts one. Maintainers see threads where they already live. | | audit [slugs...] | Quality checks (description, body, test markers, agent-routing keywords). Like npm audit. | | publish <slug> | Push a local skill (or edits) to the store. Bulk: --all. Source picker fires for new drafts when 2+ sources exist; --source skips. | | unpublish <slug> | Archive a skill in the store. | | open <slug> | Open the skill in Notion. Use --local to open the file in your editor. | | source | Manage Notion sources: add, list, remove, default, rename. | | doctor | Diagnose problems across every source. --fix repairs safe issues. |

Run any command with --help for the full list of options.

Drafts

A skill is ready or a draft. Drafts aren't yet ready for the team — they live on your machine without a Notion row, or in Notion with the Published checkbox off. Drafts are skipped by default in install flows; pass --drafts to see them or install one by name. Run publish to mark a draft ready.

Multiple sources

A "source" is one Notion database. Most users have one (the team store) and never think about it. Larger workflows want more — engineering store, personal store, a department-specific store. Run notion-skills source add to link or create another database; bare commands target the default source (the first one you set up). Use a qualified ref (team/deploy) or --source <key> when you want to be explicit. Tags are source-scoped (each Notion DB has its own tag set), so --tag always operates on a single source.

When you install two skills with the same slug from different sources, the second one auto-namespaces (personal-deploy) so both can coexist. Override with --as <name>.

What's in a skill?

A directory with a SKILL.md file. You can ship extra files alongside it. The Agent Skills spec defines three optional category directories:

• scripts/ — executable code the agent runs
• references/ — documentation the agent loads on demand
• assets/ — static resources (templates, schemas, etc.)

Files in spec dirs round-trip through Notion as nested sub-pages of a same-named wrapper. Files outside spec dirs become flat root-level child pages.

Supported agents

Claude, Codex, OpenCode, Cursor, Gemini, plus a generic ~/.agents/skills/ catch-all. Skills land as symlinks from one central directory, so every agent on your machine sees the same set.

Troubleshooting

notion-skills doctor is the first stop. Common fixes:

• Auth expired → ntn logout && ntn login
• Schema out of date → notion-skills upgrade
• Reset everything → rm -rf ~/.notion-skills && notion-skills init (your Notion store is untouched)

License

MIT