Notion Connector
ericrisco/rsc-harness
A skill your agent uses when wiring server code or a cron job to Notion as an ops backend over its HTTP API: pushing or mirroring database rows, two-way sync without duplicates, page blocks, or an…
Audit a Notion integration for recurring identity, access, version, pagination, webhook, and mutation mistakes.
Install Notion Known Pitfalls
$ npx skills add jeremylongshore/tons-of-skills-marketplace --skill notion-known-pitfalls -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install jeremylongshore/tons-of-skills-marketplace notion-known-pitfalls --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/jeremylongshore/tons-of-skills-marketplace.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/.curated/notion-known-pitfalls .claude/skills/notion-known-pitfalls && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "notion-known-pitfalls" agent skill from https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/main/skills/.curated/notion-known-pitfalls into .claude/skills/notion-known-pitfalls/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "notion-known-pitfalls", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/main/skills/.curated/notion-known-pitfallsType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add jeremylongshore/tons-of-skills-marketplace --skill notion-known-pitfalls -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install jeremylongshore/tons-of-skills-marketplace notion-known-pitfalls --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/jeremylongshore/tons-of-skills-marketplace.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/.curated/notion-known-pitfalls .agents/skills/notion-known-pitfalls && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "notion-known-pitfalls" agent skill from https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/main/skills/.curated/notion-known-pitfalls into .agents/skills/notion-known-pitfalls/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "notion-known-pitfalls", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add jeremylongshore/tons-of-skills-marketplace --skill notion-known-pitfalls -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install jeremylongshore/tons-of-skills-marketplace notion-known-pitfalls --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/jeremylongshore/tons-of-skills-marketplace.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/.curated/notion-known-pitfalls .cursor/skills/notion-known-pitfalls && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "notion-known-pitfalls" agent skill from https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/main/skills/.curated/notion-known-pitfalls into .cursor/skills/notion-known-pitfalls/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "notion-known-pitfalls", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/jeremylongshore/tons-of-skills-marketplace.git --path skills/.curated/notion-known-pitfalls--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add jeremylongshore/tons-of-skills-marketplace --skill notion-known-pitfalls -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install jeremylongshore/tons-of-skills-marketplace notion-known-pitfalls --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/jeremylongshore/tons-of-skills-marketplace.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/.curated/notion-known-pitfalls .gemini/skills/notion-known-pitfalls && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "notion-known-pitfalls" agent skill from https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/main/skills/.curated/notion-known-pitfalls into .gemini/skills/notion-known-pitfalls/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "notion-known-pitfalls", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install jeremylongshore/tons-of-skills-marketplace notion-known-pitfallsInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add jeremylongshore/tons-of-skills-marketplace --skill notion-known-pitfalls -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/jeremylongshore/tons-of-skills-marketplace.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/.curated/notion-known-pitfalls .github/skills/notion-known-pitfalls && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "notion-known-pitfalls" agent skill from https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/main/skills/.curated/notion-known-pitfalls into .github/skills/notion-known-pitfalls/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "notion-known-pitfalls", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add jeremylongshore/tons-of-skills-marketplace --skill notion-known-pitfalls -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install jeremylongshore/tons-of-skills-marketplace notion-known-pitfalls --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/jeremylongshore/tons-of-skills-marketplace.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/.curated/notion-known-pitfalls .opencode/skills/notion-known-pitfalls && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "notion-known-pitfalls" agent skill from https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/main/skills/.curated/notion-known-pitfalls into .opencode/skills/notion-known-pitfalls/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "notion-known-pitfalls", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
notion-known-pitfalls- GitHub stars
- 2.8k
- Token cost
- ~964 tokens
- SKILL.md length
- 400 words
- Files
- 2 (incl. references)
- Skills in repo
- 3,342
- Repo updated
- First seen
- Licence
- MIT
At a glance
Audit a Notion integration for recurring identity, access, version, pagination, webhook, and mutation mistakes.
- Works in 6 steps: Inventory all Notion clients, selected… → Trace every database, data-source, page,… → Check pagination, size limits, unknown… → …
- Reviewing a release
- SKILL.md covers Overview, Prerequisites, Current Contract and Authentication, plus 8 more sections
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
What it does
Notion Known Pitfalls is an agent skill from jeremylongshore/tons-of-skills-marketplace. Audit a Notion integration for recurring identity, access, version, pagination, webhook, and mutation mistakes. Use when reviewing a release or investigating confusing failures. Trigger with "review Notion pitfalls", "find Notion integration mistakes", or "check Notion assumptions".
Its SKILL.md is about 960 tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including reference files (for example `references/official-docs.md`). Compatibility notes: Designed for Claude Code; live Notion actions require network access and explicit approval
It sits in Backend & APIs, covering Webhooks. It works with Notion. The repository describes itself as: Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com. The licence is MIT.
When your agent uses it
- Reviewing a release
- Investigating confusing failures
- With review Notion pitfalls
- Find Notion integration mistakes
Example prompts
- “review Notion pitfalls”
- “find Notion integration mistakes”
- “check Notion assumptions”
- “/notion-known-pitfalls”
Requirements
- Compatibility (from SKILL.md): Designed for Claude Code; live Notion actions require network access and explicit approval
- Pre-approved tools (allowed-tools): Read, Glob, Grep, Write, Edit
Workflow steps
6 steps, taken from the first numbered list in SKILL.md.
- Inventory all Notion clients, selected versions, tokens, object IDs, operations, and data flows.
- Trace every database, data-source, page, block, file, search, and webhook assumption to first-party docs or a fixture.
- Check pagination, size limits, unknown fields, error classes, Retry-After, and retry budgets.
- Check idempotency, pre-state, read-back, compensation, and destructive-action approvals.
- Check webhook signature, duplicate, ordering, aggregation, fetch-current, and reconciliation behavior.
- Rank findings by exploitability, data impact, recurrence, and ease of correction.
What it can do on your machine
Read from SKILL.md and the folder at commit cfae287. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves these tools, so the agent can use them without asking each time:
ReadGlobGrepWriteEdit
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md.
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Compatibility
Designed for Claude Code; live Notion actions require network access and explicit approval
From compatibility in the SKILL.md frontmatter.
Context cost
Notion Known Pitfalls loads about 964 tokens when it runs, and up to ~1.5k if it reads all its reference files. Until then it costs about 76 tokens; SKILL.md has 400 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from jeremylongshore/tons-of-skills-marketplace at commit cfae287, republished under its MIT licence (© jeremylongshore). 400 words, ~964 tokens.
Download SKILL.mdSave it as
.claude/skills/notion-known-pitfalls/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.- name
- notion-known-pitfalls
- description
- Audit a Notion integration for recurring identity, access, version, pagination, webhook, and mutation mistakes. Use when reviewing a release or investigating confusing failures. Trigger with "review Notion pitfalls", "find Notion integration mistakes", or "check Notion assumptions".
- allowed-tools
- Read, Glob, Grep, Write, Edit
- compatibility
- Designed for Claude Code; live Notion actions require network access and explicit approval
- argument-hint
- <repository-or-design> <environment> <risk-focus>
- version
- 1.40.0
- license
- MIT
- author
- Jeremy Longshore <jeremy@intentsolutions.io>
- tags
- saas, notion, review
- model
- inherit
- effort
- high
Notion Integration Pitfall Review
Overview
Audit a Notion integration for recurring identity, access, version, pagination, webhook, and mutation mistakes.. This workflow produces an auditable decision or artifact before any live action.
Prerequisites
- Current first-party Notion documentation and the selected integration's tested API-version contract.
- A named workspace owner, content or data owner, and operation owner.
- Synthetic or approved non-production fixtures with secrets and workspace content removed.
Current Contract
Common failures arise from confusing databases with data sources, assuming capabilities equal content access, omitting pagination, pinning stale object shapes, treating webhooks as a ledger, or retrying writes without idempotency. Recheck the dated evidence map before relying on mutable fields, endpoints, versions, limits, or delivery behavior.
Authentication
Check that the code distinguishes connection models, workspace binding, capabilities, shared content, and secret lifecycle.
Instructions
- Inventory all Notion clients, selected versions, tokens, object IDs, operations, and data flows.
- Trace every database, data-source, page, block, file, search, and webhook assumption to first-party docs or a fixture.
- Check pagination, size limits, unknown fields, error classes, Retry-After, and retry budgets.
- Check idempotency, pre-state, read-back, compensation, and destructive-action approvals.
- Check webhook signature, duplicate, ordering, aggregation, fetch-current, and reconciliation behavior.
- Rank findings by exploitability, data impact, recurrence, and ease of correction.
Tool Discipline
Use Read, Glob, and Grep to inspect documentation, configuration, code, fixtures, and evidence. Use Write and Edit only for approved repository artifacts. Invocation alone does not authorize network access, credentials, workspace content, user data, file transfer, deployment, capability or sharing changes, writes, spend, or deletion.
Show full SKILL.md (146 more words)Show less
Approval Boundaries
Require approval before using live credentials or content to confirm a suspected pitfall; repository inspection remains read-only by default.
Error Handling
- Do not fix a 404 by broadening access without proving identity.
- Do not assume a single search or query page is complete.
- Do not silently coerce legacy payloads into current writes.
Output
Return the pitfall inventory, evidence, impact, false-positive notes, corrective action, owner, and verification test. Identify assumptions, owners, expirations, and evidence gaps explicitly.
Examples
- Find a database ID passed to a data-source query.
- Find a webhook handler that trusts delivery order and never reconciles.
Validation
Exercise and record these paths with expected and observed results:
- wrong ID type
- unshared content
- pagination
- unknown fields
- write retry
- webhook replay
Resources
- Current first-party evidence map — recheck dated sources before relying on mutable behavior.
- Treat observed tenant behavior as environment-specific evidence, never a universal Notion guarantee.
© jeremylongshore, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 1 other file (references) in skills/.curated/notion-known-pitfalls of jeremylongshore/tons-of-skills-marketplace.
- SKILL.md
- references/official-docs.md
Open the folder on GitHubat commit cfae287
Compare with similar skills
Notion Known Pitfalls next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Notion Known Pitfalls this skilljeremylongshore/tons-of-skills-marketplace | 2.8k | — | ~964 | Automated safety check: Pass | MIT | |
| Notion Connectorericrisco/rsc-harness | 180 | — | ~2.4k | Automated safety check: Pass | MIT | |
| Novu Design Workflownovuhq/novu | 40k | — | ~2.6k | Automated safety check: Pass | Custom licence | |
| Golivemikehasa/golive-skill | 1.3k | — | ~13k | Automated safety check: Notes | MIT | |
| Stripe Appsfossasia/eventyay | 1.7k | 1 repos | ~3.6k | Automated safety check: Pass | Apache-2.0 | |
| Dingtalk Messageagentscope-ai/ReMe | 3.6k | — | ~1.6k | Automated safety check: Pass | Apache-2.0 |
Similar skills
Novu Design Workflow
novuhq/novu
Design notification workflows the Novu way — choose channels, set severity, decide when a workflow is critical, configure digests, and route based on subscriber state.
Golive
mikehasa/golive-skill
Take an agent-written app from repo to live production on the user's OWN accounts, with providers they choose (hosting, database, auth, payments, email, domain/DNS).
Stripe Apps
fossasia/eventyay
A skill your agent uses when building, modifying, or reviewing a Stripe App — or when the user describes something that implies one (e.g.
Dingtalk Message
agentscope-ai/ReMe
钉钉消息发送技能。支持企业内部机器人（批量单聊/群聊）和 Webhook 自定义机器人两种接入方式，支持多机器人管理，支持文本、Markdown、链接、ActionCard、FeedCard等多种消息类型。
PR Review Provider
yansongda/pay
A skill your agent uses when reviewing PRs that add or modify a payment Provider in yansongda/pay - covers plugin pipeline, multi-tenant safety, signature verification, docs, and naming conventions.
More from jeremylongshore/tons-of-skills-marketplace
All 3,342 skills in this repoPerforming Security Code Review
jeremylongshore/tons-of-skills-marketplace
Execute this skill enables AI assistant to conduct a security-focused code review using the security-agent plugin.
Adapting Transfer Learning Models
jeremylongshore/tons-of-skills-marketplace
Build this skill automates the adaptation of pre-trained machine learning models using transfer learning techniques.
Agent Context Loader
jeremylongshore/tons-of-skills-marketplace
Execute proactive auto-loading: automatically detects and loads agents.md files.
Aggregating Performance Metrics
jeremylongshore/tons-of-skills-marketplace
Aggregate and centralize performance metrics from applications, systems, databases, caches, and services.
Analyzing Capacity Planning
jeremylongshore/tons-of-skills-marketplace
Execute this skill enables AI assistant to analyze capacity requirements and plan for future growth.
Analyzing Database Indexes
jeremylongshore/tons-of-skills-marketplace
Process use when you need to work with database indexing. An agent skill from jeremylongshore/tons-of-skills-marketplace.
Related
Works with
Categories
Questions about Notion Known Pitfalls
What does Notion Known Pitfalls do?
Audit a Notion integration for recurring identity, access, version, pagination, webhook, and mutation mistakes. Notion Known Pitfalls is an agent skill from jeremylongshore/tons-of-skills-marketplace. Audit a Notion integration for recurring identity, access, version, pagination, webhook, and mutation mistakes.
When should I use Notion Known Pitfalls?
Notion Known Pitfalls fits situations like: reviewing a release; investigating confusing failures; with review Notion pitfalls; find Notion integration mistakes.
How do I install Notion Known Pitfalls in Claude Code?
Run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill notion-known-pitfalls -a claude-code`. Or copy the skill folder (skills/.curated/notion-known-pitfalls in jeremylongshore/tons-of-skills-marketplace) into .claude/skills/notion-known-pitfalls in your project. Claude Code loads it when a task matches its description.
How do I install Notion Known Pitfalls in Codex?
Run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill notion-known-pitfalls -a codex`. Or copy the skill folder (skills/.curated/notion-known-pitfalls in jeremylongshore/tons-of-skills-marketplace) into .agents/skills/notion-known-pitfalls in your project. Codex loads it when a task matches its description.
Can I use Notion Known Pitfalls in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill notion-known-pitfalls -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/notion-known-pitfalls, .gemini/skills/notion-known-pitfalls, .github/skills/notion-known-pitfalls and .opencode/skills/notion-known-pitfalls in your project.
What does Notion Known Pitfalls need to run?
SKILL.md names no scripts, command-line tools or credentials: Notion Known Pitfalls is instructions for the agent only. Its frontmatter pre-approves these tools: Read, Glob, Grep, Write, Edit. Compatibility (from SKILL.md): Designed for Claude Code; live Notion actions require network access and explicit approval.
Does Notion Known Pitfalls access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is Notion Known Pitfalls safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Notion Known Pitfalls use?
Notion Known Pitfalls is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Notion Known Pitfalls use?
About 964 tokens (SKILL.md is roughly 3.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 545 tokens, read only when the agent opens those files.
What are the alternatives to Notion Known Pitfalls?
Skills that share tags, products or a category with Notion Known Pitfalls: Notion Connector (ericrisco/rsc-harness, 180 stars), Novu Design Workflow (novuhq/novu, 40k stars), Golive (mikehasa/golive-skill, 1.3k stars) and Stripe Apps (fossasia/eventyay, 1.7k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Notion Known Pitfalls?
jeremylongshore (a GitHub user) maintains it in jeremylongshore/tons-of-skills-marketplace, which has 2,827 GitHub stars. The repository holds 3,342 skills in this directory. The repository was last updated on October 10, 2026.
Source: jeremylongshore/tons-of-skills-marketplace on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.