SuperAPI AI Directory

soia-pkm-clip-x

General & other

View repository

Updated 10-16 08:44

About this skill

soia-pkm-clip-x

Save valuable content from X into an Obsidian vault and build a searchable knowledge asset.

Client-readable description

What this skill can do

Archive X/Twitter tweets, threads, and Articles into an Obsidian vault. Based on the fxtwitter API, single-item zero configuration; optionally sync Telegram favorites. When PDF is needed, prefer Obsidian export

The client wants The skill will do The client can see
Complete the work covered by this skill Read the user request, necessary context, and this skill's main workflow, and execute the minimal reliable steps The client will see Obsidian/vault file changes, terminal logs, generated artifact paths, and a final receipt.
Missing dependencies, permissions, configuration, or key Stop actions that require external state and clearly state what is missing Install command, application address, configuration path, or questions that need client confirmation
Execution complete Summarize successes, skips, failures, file changes, and verification results A completion receipt that can be copied into a ticket/log

How the client uses it

  1. Describe the goal in natural language and provide the necessary inputs: files, URLs, repo, workspace, proposal, vault, or platform account status.
  2. For actions that can be dry-run or previewed, provide a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, seek client confirmation first.

Dependencies and installation

Installation (recommended: install the entire domain plugin, setting up all skills in this repo at once):

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-pkm-vault@soia

When you only want this one skill, you can use the npx route. Note that the skill will land in the shared source of truth ~/.agents/skills; if the plugin is also installed, the same skill will appear as two indexes and drift independently, so it is recommended to choose one of the two:

npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-clip-x -y

Configuration conventions:

~/.config/soia-skills/soia-pkm-clip-x/config.yml
SOIA_PKM_CLIP_X_CONFIG_FILE=<custom-config-path>
  • If this skill does not need private configuration, you can skip creating config.yml。
  • If an API key, cookie, session, provider home, or local path is needed, it can only go into private config.yml, the process environment, or the provider's own login state, and must not be written into the repo, vault body, or logs.
  • Third-party skills can only declare dependencies and installation methods, and do not directly modify third-party skill files.

WorkBuddy The unit of loading is role-based experts rather than plugins,npx skills add -a '*' cannot cover it, and it needs to be installed separately, see docs/install/workbuddy.md。

Logging and completion receipt

Fetch completion only means captured; a single item by default continues through lifecycle management's organized → MOC/导航 → map → Base five-stage contract, with item-by-item receipt, and stages that do not apply marked as not_applicable。

Every execution must let the client see the process and results. Minimum receipt format:

完成:<一句话说明本次完成了什么>。

日志摘要:
- started: <检查到的输入/配置/依赖,不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>

文件变化:
- <绝对路径或“未改动文件”>

验证:
- <运行过的检查、命令或人工核对点>

问题与下一步:
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令;没有则写“无”>

Positioning

X's native UI is not conducive to long-term review: threads are scattered in the timeline, Articles have messy formatting, links break easily, and search is weak. This skill saves high-quality long content from X into Obsidian with one click:

  • Complete thread unroll
  • X Article retrieves the full content.blocks
  • Complete metadata (author, metrics, direct media links, created_at)
  • Frontmatter topic wikilinks, convenient for MOC aggregation
  • Multilingual recognition (zh / en / ja / ko)

Prerequisites

  • Obsidian vault (any structure)
  • Python 3, pure stdlib (no third-party dependencies, archives a single tweet)
  • Optional:pip install telethon(only used for MTProto sync)
  • vault location priority:
    1. command line --vault <path>
    2. environment variable OBSIDIAN_VAULT
    3. automatically discover the vault going upward from the current working directory (look for AGENTS.md / .obsidian)
  • Articles directory location priority:
    1. command line --articles-dir <subdir>
    2. environment variable OBSIDIAN_ARTICLES
    3. fall back to generic default Articles; the script will print the following warning to stderr, and the exit code remains 0:WARN: 未找到 articles 目录配置(--articles-dir / OBSIDIAN_ARTICLES / config.yml),已落默认 Articles/——该目录不是本 vault 的正式归档位,请确认或配置

Note: tools such as Claude Code / Codex / Gemini CLI / opencode often execute commands in a non-login shell and may not inherit the exportfrom shell startup files. The script will first load the private config.yml, then automatically discover the vault from cwd; if the agent is already in the vault directory, just run it directly.

  • Private config.yml(optional,do not place in the vault or in an open-source skill repository):

    Priority:$SOIA_PKM_CLIP_X_CONFIG_FILE(or compatible alias $SOIA_PKM_CLIP_X_ENV_FILE)> ~/.config/soia-skills/soia-pkm-clip-x/config.yml。

    Supported variable names:OBSIDIAN_VAULT、OBSIDIAN_ARTICLES、X_ARCHIVE_LANG; only MTProto sync requires TELEGRAM_API_ID / TELEGRAM_API_HASH / TELEGRAM_SESSION_STRING. Real values are only written in the private config.yml and are not written into this file.

Core API: fxtwitter

Replace the x.com in the X URL with api.fxtwitter.com, and directly GET back JSON. No X API key, no login, zero cost.

Key field Purpose
tweet.text / tweet.raw_text.text Tweet body
tweet.article.title X Article title
tweet.article.content.blocks[] Article long-form blocks
tweet.raw_text.facets[].replacement Expand the t.co short links in the body into their canonical targets
tweet.article.media_entities[] X Article image/video entities
tweet.replying_to_status Previous tweet (thread backtracking)
tweet.quote Quoted tweet
tweet.media[] Media (direct image/video links)
tweet.created_timestamp UNIX timestamp
tweet.views / likes / bookmarks / retweets metrics

Fallback: fxtwitter fails → cdn.syndication.twimg.com public endpoint.

Trigger words

User says Call
"Archive this X: URL" / "archive this: URL" Run in the vault root directory archive_x.py <URL>; when not inside the vault, add --vault <path>. For non-Chinese content, a translation is automatically added by default (see step 4 of the workflow below); no need to additionally say "translate"
"Archive and convert to PDF: URL" / "Archive and export PDF: URL" First write and complete the Markdown according to the default archiving workflow, then follow references/obsidian-pdf-export.md to use Obsidian's native export; do not prioritize pandoc/wkhtmltopdf
"Organize this thread: URL" Same as above, force thread backtracking
"Sync my Telegram saved messages" + provide JSON path sync_telegram_export.py <path> --dry-run check first, run for real after confirmation
"Sync Telegram with API" (credentials already available) sync_telegram_saved.py

Workflow (default archiving)

  1. Parse URL → handle + status_id
  2. Call script archive_x.py <URL>
  3. The script checks whether the vault has already archived it (by frontmatter url: field)
    • Already exists → output SKIP, exit
    • Otherwise → fetch fxtwitter, write into vault
    • Body URLs preferentially use the replacement; keep the short link only when no expansion target can be found, and indicate in the receipt that it was not expanded
  4. AI then appends:
    • 1 sentence in Chinese ## 摘要
    • 1-3 topics wiki-links + people wiki-links
    • non-Chinese content (language is not zh): by default, fill the ## 中文译文 section with a complete translation, without the user needing to additionally say "translate". Requirementsfree translation, not literal translation— it should read like Chinese written by a human, not machine-translationese; proper nouns, product names, and code/command/API parameters keep their original English, and only narrative text and explanations are translated
  5. the "My take" section is always left blank for the user

if a paper or attachment URL appears in the body,clip-x is only responsible for expanding them and keeping them as canonical links; in-depth discovery, download, hashing, and text extraction of PDFs are left to soia-pkm-clip-drive/scripts/archive_pdf.py --deep, to avoid reimplementing binary handling across different source skills.

export PDF after archiving

when the user also requests "convert to PDF / export PDF", first complete the Markdown archiving, summary, topics/people, and month placement, then read and execute references/obsidian-pdf-export.md. As long as the target file is inside the Obsidian vault, prefer Obsidian's built-in "Export to PDF"; external PDF engines may only serve as an explicit fallback.

Telegram Saved Messages bulk sync

Bulk-archive X links casually forwarded from a phone to Telegram "Saved Messages" into the vault.Recommended JSON export path(zero risk, zero dependencies).

Complete steps, commands, and caveats for both paths (JSON export / MTProto API) → see references/telegram-sync.md。

File naming

<YYYY-MM-DD>-X-<handle>-<title前 50 字>.md

Example:

  • 2026-05-24-X-cyrilXBT-How-to-Organize-Your-Obsidian-Vault.md
  • 2026-05-29-X-ObsidianOtaku-保存版AIエージェントのためのObsidian活用術.md

multiple items from the same author on the same day → append at the end -<status_id 后 6 位>。

Output frontmatter

---
tags: [文章摘抄]
source: X
url: https://x.com/<handle>/status/<id>
author: <显示名>
handle: "@<handle>"
published_at: YYYY-MM-DD HH:mm
captured_at: YYYY-MM-DD HH:mm
language: zh / en / ja / ko
type: tweet / thread / article
topics: ["[[xxx]]", ...]   # AI 填
people: ["[[xxx]]", ...]   # AI 填
media: [...] / 0
content_complete: true
metrics:
  views: N
  likes: N
  bookmarks: N
---

Boundaries and exceptions

Scenario Handling
fxtwitter returns 404 the tweet was deleted/private; suggest checking archive.org
fxtwitter 5xx retry once; on failure, fall back to the syndication endpoint
URL is not x.com / twitter.com reject; suggest using Web Clipper
tweet text is empty and there is no article and no media warning: "pure retweet/pure reply, may have no independent content"
duplicate filename for the same author on the same day append at the end -<status_id 后 6 位>
video media frontmatter media[] record the mp4 direct link, do not embed
Archive directory write by publication time into <articles>/<YYYY>/<MM>/, for example 2026/08/

Offline fixtures and realistic forward tests cover t.co facet expansion, deduplication priority for original/translated text with the same status ID, and media retention; see repository tests/test_archive_x.py。

Command-line reference (archiving)

python3 archive_x.py <URL>
python3 archive_x.py <URL> --force                  # 覆盖已归档
python3 archive_x.py <URL> --vault /path/to/vault   # 覆盖环境变量
python3 archive_x.py <URL> --articles-dir <articles-subdir>

Telegram sync command → see references/telegram-sync.md。


Receipt upon completion

Delivery order: write the file to disk first, then output the receipt below, not the other way around; uncertain metadata (such as author or publication time that fails to parse) must be explicitly marked "unverified" in the receipt, and must not be fabricated.

The receipt includes:

  1. What was done — a one-sentence summary of the completed work.
  2. File changes — List the newly created / modified / moved files (full paths); if no files were changed, state "no files changed".
    • The receipt must include the actual on-disk directory; if the Articles/ fallback was used, it must be explicitly noted that this directory is not the official archive location for this vault, and the user should be advised to configure --articles-dir、OBSIDIAN_ARTICLES or a private config.yml and then relocate it.
  3. Next steps — optional follow-up suggestions (such as the next skill to connect with).