notion-clipper-skill

Clip web pages to Notion. Fetches any URL via Chrome CDP, converts HTML to Markdown, then to Notion blocks, and saves to user-specified Notion database or page. Use when user wants to save/clip a webpage to Notion, or mentions "clip to notion", "save page to notion", "网页剪藏到Notion".

Security Scan

The skill's code, instructions, and requirements are coherent with its stated purpose (launch Chrome via CDP, render a page, convert to Markdown and push to Notion); no obvious misdirection or hidden endpoints were found, but it does auto-install npm dependencies and writes browser/profile data to disk so take usual precautions.

Purpose & Capability

The skill name/description match the implementation: it launches a local Chrome instance via CDP, renders and extracts page HTML, converts HTML→Markdown→Notion blocks, and calls the Notion API. Required artifacts (Chrome, a Notion integration key) and reading a local API key file are consistent with the stated functionality.

Instruction Scope

The SKILL.md tells the agent to run npm install (if node_modules missing) and then run the TypeScript entry with npx tsx. That is within scope for a code-based clipper but grants the agent permission to install and execute dependencies at runtime. The instructions also ask the user to store the Notion API key at ~/.config/notion/api_key and to unset proxy env vars — both are consistent with operation, though the key is stored in plaintext on disk.

Install Mechanism

There is no formal install spec; instead the runtime instructions auto-run `npm install` in the skill's scripts folder and use `npx -y tsx` at runtime. That causes packages to be fetched from the public npm registry (package-lock is included which helps reproducibility), and some dependencies (e.g., esbuild) have install scripts/binary downloads. This is expected for a Node-based tool but increases risk compared to a pure instruction-only skill because remote code and native binaries can be downloaded and executed.

Credentials

The only credential the skill needs is the Notion integration API key (the code reads a file at a path resolved by paths.ts). It optionally respects NOTION_CLIPPER_CHROME_PATH to locate Chrome. There are no unrelated secrets requested. Storing the API key as a plaintext local file is functional but carries the usual risk if other processes can read that file.

Persistence & Privilege

always:false and the skill is user-invocable (normal). The implementation creates/writes data: node_modules in the skill directory (from npm install) and a Chrome user-data-dir profile (a per-skill profile directory) for the spawned browser. That means cookies, local storage, or logged-in sessions could persist in that profile between runs — expected for a clipper but something users should be aware of.

Assessment

This skill appears to do what it says, but before installing or running it consider: - The SKILL.md runs `npm install` and `npx -y tsx` at runtime. That will download and install packages (and native installer scripts) from npm. Review scripts/package.json and package-lock.json if you want reproducibility, or run in a sandbox/container. - The skill reads your Notion integration key from a plaintext file (~/.config/notion/api_key). Use a dedicated, limited-scope Notion integration and be prepared to revoke the key if you stop trusting the skill. - The tool creates a Chrome user-data-dir for its headful browsing; cookies and logged-in sessions can be stored there and persist between runs. If you need ephemeral behavior, remove the profile dir after use or run inside an isolated environment. - If you want extra caution: inspect the package.json and the top-level files, run `npm ci` yourself in an isolated environment, or run the script in a disposable VM/container. If anything looks unexpected, do not provide your real Notion API key.

Notion Clipper

Clip any web page to Notion. Uses Chrome CDP for full JavaScript rendering, converts to Markdown, then to Notion blocks.

Prerequisites

1. Notion API Key: Create an integration at https://notion.so/my-integrations
2. Store the key:

mkdir -p ~/.config/notion
echo "ntn_your_key_here" > ~/.config/notion/api_key

3. Share target database/page with your integration (click "..." → "Connect to" → your integration name)

First Time Setup

Dependencies are auto-installed when the script runs. No manual setup needed.

Agent Execution Instructions

CRITICAL: Always use the command pattern below. It auto-installs dependencies on first run.

1. Determine this SKILL.md file's directory path as SKILL_DIR
2. Command pattern (package.json in scripts/; always run lazy install first):

(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts <args>)

3. Replace ${SKILL_DIR} with the actual path (e.g. /Users/xxx/.claude/skills/notion-clipper-skill)

Usage

IMPORTANT - Use this command pattern for best results:

# Recommended: Clear proxy env vars and use tsx runtime
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && unset http_proxy https_proxy all_proxy && npx -y tsx main.ts <url> --database-name "Resources")

Why this pattern?

• unset http_proxy https_proxy all_proxy - Avoids ECONNREFUSED from proxy conflicts
• tsx runtime - Node.js runtime that properly handles direct connections (bun has proxy issues)
• (test -d node_modules || npm install) - Auto-installs dependencies if missing

If you encounter network issues:

1. Close any VPN/proxy software
2. Switch to a stable network (mobile hotspot often works)
3. Use the recommended command pattern above

# Clip to a Notion database by NAME (recommended - searches for database)
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts <url> --database-name "Resource")

# Clip to a Notion database by ID
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts <url> --database <database_id>)

# Clip to an existing page (appends blocks)
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts <url> --page <page_id>)

# List all accessible databases
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts --list-databases)

# For pages requiring login (wait mode)
(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && npx -y tsx main.ts <url> --database-name "Resource" --wait)

Options

Option	Description
<url>	URL to clip
--database-name, -n <name>	Target database by name (searches for match)
--database, -d <id>	Target Notion database by ID
--page, -p <id>	Target Notion page ID (appends blocks)
--list-databases, -l	List all accessible databases and exit
--wait, -w	Wait for user signal before capturing
--timeout, -t <ms>	Page load timeout (default: 30000)
--no-bookmark	Don't include bookmark block at top

Capture Modes

Mode	Behavior	Use When
Auto (default)	Capture on network idle	Public pages, static content
Wait (--wait)	User signals when ready	Login-required, lazy loading, paywalls

Wait mode workflow:

1. Run with --wait → Chrome opens, script outputs "Press Enter when ready"
2. Log in or navigate as needed in the browser
3. Press Enter in terminal to trigger capture

Output Structure

When saving to a database, creates a new page with:

• Name: Page title
• URL: Source URL (if database has URL property)
• Content: Bookmark block + converted content blocks

When appending to a page, adds:

• Bookmark block (link to source)
• Divider
• Converted content blocks

Database Setup

For best results, create a Notion database with these properties:

• Name (Title) - Required, will contain page title
• URL (URL) - Optional, will contain source URL

Examples

Clip a tweet to "Resource" database (by name):

(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && unset http_proxy https_proxy all_proxy && npx -y tsx main.ts "https://x.com/dotey/status/123456" -n "Resource")

List all databases first:

(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && unset http_proxy https_proxy all_proxy && npx -y tsx main.ts --list-databases)

Clip article requiring login:

(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && unset http_proxy https_proxy all_proxy && npx -y tsx main.ts "https://medium.com/article" -n "Reading" --wait)

Append to reading notes page:

(cd "${SKILL_DIR}/scripts" && (test -d node_modules || npm install) && unset http_proxy https_proxy all_proxy && npx -y tsx main.ts "https://blog.example.com/post" -p xyz789)

Quick alias (add to your ~/.bashrc or ~/.zshrc):

alias notion-clip='(cd "${SKILL_DIR}/scripts" && unset http_proxy https_proxy all_proxy && npx -y tsx main.ts)'

# Usage: notion-clip <url> -n "Resources"

How It Works

1. Fetch: Launch Chrome via CDP, navigate to URL
2. Render: Wait for JavaScript to execute, scroll to trigger lazy loading
3. Extract: Run cleanup script to remove ads/nav, extract main content
4. Convert: HTML → Markdown → Notion blocks
5. Save: Call Notion API to create page or append blocks

Dependencies

• Chrome/Chromium browser (installed locally)
• Node.js (script runs with tsx; Bun may route through proxy and return empty body, use Node)
• Notion API key configured

(Other dependencies auto-install on first run.)

Environment Variables

Variable	Description
NOTION_CLIPPER_CHROME_PATH	Custom Chrome executable path
NOTION_CLIPPER_CHROME_PROFILE_DIR	Custom Chrome profile directory
https_proxy / HTTP_PROXY	Proxy for Notion API (e.g. http://127.0.0.1:7890)
http_proxy / HTTPS_PROXY	Same as above
all_proxy	Optional, e.g. socks5://127.0.0.1:7890

Example (proxy on port 7890):

export https_proxy=http://127.0.0.1:7890 http_proxy=http://127.0.0.1:7890 all_proxy=socks5://127.0.0.1:7890

Troubleshooting

Network Issues

Error	Cause	Solution
ECONNREFUSED 208.103.161.1:443	DNS returns blocked IP; proxy conflict	1. Close VPN/proxy software<br>2. Use unset http_proxy https_proxy all_proxy<br>3. Switch network (e.g., mobile hotspot)
Notion API returned empty body (status 200)	Using bun which routes through proxy incorrectly	Run with tsx: npx -y tsx main.ts ... (NOT bun)
fetch failed or ECONNREFUSED	Proxy env vars set but Node.js https doesn't support them	Either:<br>1. Use network without proxy (unset env vars)<br>2. Ensure proxy allows HTTPS traffic
CloudFlare 403	Direct IP access triggers security protection	Use hostname instead of IP; ensure proper Authorization header
Mixed: Sometimes works, sometimes fails	Unstable network or DNS returns different IPs	Script now has 6 retries with exponential backoff (1s, 2s, 4s, 4s...)

Best Practice: For reliable Notion API access, use a stable network (mobile hotspot often works better than corporate VPN).

Content Issues

Error	Cause	Solution
Invalid URL for link	Notion API rejects non-http(s) URLs	Script now removes all markdown links by default to avoid validation errors. Content is preserved, only links are stripped.

Note: The script automatically removes these invalid URL types:

• javascript:, data:, file:, about: protocols
• WeChat internal links (weixin:, wx://)
• Relative paths (/path, ./path)
• Hash-only links (#anchor)
• Empty links

General Issues

• Chrome not found: Set NOTION_CLIPPER_CHROME_PATH environment variable
• Timeout errors: Increase --timeout value or use --wait mode
• Content missing: Try --wait mode for dynamic/lazy-loaded pages
• Notion API error (401/403): Check API key validity and integration permissions
• Notion API error: Ensure integration has access to target database/page

Code Optimizations Applied

The following optimizations have been implemented to handle unstable networks and invalid URLs:

1. Auto-retry mechanism: Up to 6 retries with exponential backoff (1s → 2s → 4s → 4s...)
2. Increased timeout: 30s for Notion API requests (was 25s)
3. URL cleaning: Removes invalid URLs before Notion API submission
4. Using tsx: Node.js runtime that properly handles direct connections (unlike Bun)