Skill: ewingyangs/notion-clipper-skill (version 1.0.0)

--- name: notion-clipper-skill description: 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". --- # 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**: ```bash 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): ```bash (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:** ```bash # 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 ```bash # 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):** ```bash (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:** ```bash (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:** ```bash (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:** ```bash (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):** ```bash 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 | | [REDACTED_SECRET] | 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):** ```bash 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)


Security scan verdicts — ClawScan: clean | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)