Obsidian Clipper

Universal clipper — saves URLs from any platform to your Obsidian Vault with local media, tags, and wikilinks.

Configuration

On first run, read config.yml from the same directory as this SKILL.md file. If missing, tell the user to copy config.yml.example to config.yml and fill in vault.base_path.

Key paths derived from config:

CODEBLOCK0

URL Router

Match the URL and dispatch to the correct handler:

Shared Rules

These apply to ALL handlers:

File naming

• - Use the content title as filename
• Strip /\:*?"<>| and all emoji / special Unicode
• Truncate if >60 characters
• If a file with the same name exists, ask the user before overwriting

Tags

• - Every clipping MUST have the clipping tag
• No . or spaces in tags (llms.txt → llms-txt, Claude Code → Claude-Code)
• Add 2-4 content-based tags automatically

Media download

• - Download all images and videos to INLINECODE19
• Image naming: {title-slug}-{n}.{ext} (slug ≤20 chars, no emoji)
• Video naming: {title-slug}.mp4 or INLINECODE22
• Replace remote URLs with Obsidian wikilinks: INLINECODE23

"Why clipped" field

• - Infer from conversation context if possible
• If context is insufficient, ask the user

Cross-platform linking

• - If the content contains a github.com/{owner}/{repo} link, auto-trigger the GitHub Handler to create a GitHub note, then add bidirectional wikilinks

X Handler

Saves X (Twitter) posts and articles.

Step 1: Fetch post data

CODEBLOCK1

Extract from URL: x.com/{handle}/status/{id} → handle, tweet_id.

Fields:

• - tweet.author.name → author name
• INLINECODE27 → @handle
• INLINECODE28 → post body (short posts)
• INLINECODE29 → long-form article (if present)
• INLINECODE30 → article title
• INLINECODE31 → structured content (Draft.js format)
• INLINECODE32 → publish date
• INLINECODE33 / tweet.retweets / tweet.views → engagement
• INLINECODE36 → short post images
• INLINECODE37 → article inline images

Step 2: Determine content type

Short post (tweet.article is null): use tweet.text, images from tweet.media.photos.

Article (tweet.article exists): parse tweet.article.content.blocks (Draft.js):

Inline styles: Bold → **text**, Italic → *text*.

For atomic blocks: entityMap → value.data.mediaItems[].mediaId → match media_entities → media_info.original_img_url.

Step 3: Download images

Download all images to ATTACHMENTS/.

Step 4: Generate file

Write to X_DIR/{title}.md:

Short post:
CODEBLOCK2

Article:
CODEBLOCK3

Notes

• - fxtwitter API needs no auth but may rate-limit; try vxtwitter.com as fallback
• Title: articles use article.title; short posts use INLINECODE71

WeChat Handler

Saves WeChat Official Account (公众号) articles.

Step 1: Fetch article data

CODEBLOCK4

Extract: title, nick_name, create_time, content_noencode, link.

If API returns 204 or fails, fall back to defuddle or WebFetch.

Step 2: Fetch HTML (if rich content needed)

If content has images or complex formatting:

CODEBLOCK5

Extract image URLs and formatted content from HTML.

Step 3: Download images

• - Download each image to INLINECODE79
• WeChat image URLs: mmbiz.qpic.cn/mmbiz_png/... → .png, mmbiz_jpg/... → INLINECODE83
• Replace with INLINECODE84

Step 4: Generate file

Write to WECHAT_DIR/{title}.md:

CODEBLOCK6

Xiaohongshu Handler

Saves 小红书 notes (images + video).

Step 1: Resolve short link

If URL is xhslink.com, follow redirects to get the real URL with full query parameters (especially xsec_token):

CODEBLOCK7

Important: The full query string is required. Bare URLs return empty noteDetailMap.

Step 2: Fetch SSR data

Xiaohongshu is an SPA, but SSR embeds data in window.__INITIAL_STATE__:

CODEBLOCK8

Step 3: Download media

• - Images: curl -L -o each image to INLINECODE91
• Video (if present): curl -L -o to INLINECODE93

Step 4: Generate file

Write to XHS_DIR/{title}.md:

CODEBLOCK9

Notes

• - If curl can't reach Xiaohongshu, add INLINECODE95
• INLINECODE96 often contains [话题]#tag[话题]# markers — strip them for clean text

Douyin Handler

Saves 抖音 videos. Requires douyin-downloader tool — check config.douyin.enabled first. If disabled, tell the user to install douyin-downloader and enable it in config.

Step 1: Extract and resolve link

From share text like 7.94 复制打开抖音...https://v.douyin.com/xxxxx/ DUL:/..., extract the v.douyin.com short link.

Resolve to full video ID:

CODEBLOCK10

Construct: INLINECODE101

Step 2: Download with douyin-downloader

1. 1. Edit {config.douyin.tool_path}/config.yml: set link to the full URL
2. Run:

   cd {config.douyin.tool_path} && {config.douyin.python} run.py
   

1. 3. Find files in Downloaded/ — .mp4, _cover.jpg, INLINECODE107

Step 3: Extract metadata

From _data.json:

• - desc → description (title + hashtags)
• INLINECODE110 → author
• INLINECODE111 → likes
• INLINECODE112 → comments
• INLINECODE113 → shares
• INLINECODE114 → Unix timestamp → convert to YYYY-MM-DD

Step 4: Copy media to vault

Copy video and cover to ATTACHMENTS/.

Step 5: Generate file

Write to DOUYIN_DIR/{title}.md:

CODEBLOCK12

Notes

• - Short links MUST be resolved first — douyin-downloader cannot handle them
• If download fails (0% success), cookies may be expired — tell user to re-run cookie fetcher:

  cd {config.douyin.tool_path} && {config.douyin.python} -m tools.cookie_fetcher --config config.yml
  

• - create_time is Unix timestamp: INLINECODE118

GitHub Handler

Saves GitHub repositories.

Step 1: Fetch repo metadata

CODEBLOCK14

Extract: name, full_name, description, stargazers_count, language, license.spdx_id, topics, created_at, html_url, homepage.

Step 2: Fetch README

CODEBLOCK15

Decode base64 content to get README markdown.

Step 3: Summarize README

Do NOT copy the full README. Extract:

1. 1. Core features: 3-5 bullet points, one sentence each
2. Quick start: only the most essential command or API snippet
3. Notes: limitations, dependencies, special requirements

Step 4: Generate file

Write to GITHUB_DIR/{repo-name}.md:

CODEBLOCK16

Notes

• - Star count as raw number (no 1.2k formatting — for Dataview sorting)
• Use name not full_name for filename
• If API returns 403 (rate limit), tell user to wait
• Strip emoji from filenames

Web Handler

Saves generic web pages. Fallback for URLs that don't match any platform handler.

Step 1: Extract content with defuddle

CODEBLOCK17

Extract: title, author, content (HTML), description, published, domain.

If defuddle is not installed, run npm install -g defuddle-cli first.

Step 2: Handle empty content (SPA fallback)

If content is empty or just <body></body> (client-rendered SPA), try fallback paths in order:

Path A: CDP browser (if config.web.cdp_enabled):

1. 1. Open page: curl -s "{config.web.cdp_url}/new?url=<URL>" → get INLINECODE145
2. Scroll: INLINECODE146
3. Extract title: INLINECODE147
4. Extract body: INLINECODE148
5. Extract images: INLINECODE149
6. Extract videos: INLINECODE150
7. Close tab: INLINECODE151

Path B: WebFetch — use the WebFetch tool as fallback.

Path C: Bookmark mode — if URL is a web app/tool/dashboard or all paths fail, create a bookmark note from meta info only.

Step 3: Download media

Download images and videos to ATTACHMENTS/, replace with ![[filename]].

Step 4: Generate file

Write to WEB_DIR/{title}.md:

Content page:
CODEBLOCK18

Bookmark page (tool/app/SPA):
CODEBLOCK19

Notes

• - defuddle does not work on SPAs (React/Vue client-rendered) — use CDP path
• Always close CDP tabs after use