SuperAPI AI Directory

soia-pkm-clip-x

Coding & development

View repository

Updated 10-16 09:30

About this skill

soia-pkm-clip-x

Preserve 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 to an Obsidian vault. Based on the fxtwitter API, zero configuration for a single item; optionally sync Telegram favorites. When PDF is needed, prefer exporting via Obsidian

What the client wants What the skill will do What 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 the final receipt.
Missing dependencies, permissions, configuration, or keys Stop actions that require external state and clearly state what is missing Install commands, application addresses, configuration paths, 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. State the goal in natural language and provide the necessary inputs: files, URLs, repos, workspaces, proposals, vaults, or platform account status.
  2. The Agent first determines whether this skill applies, then checks dependencies, configuration, permissions, and risky actions.
  3. For actions that can be dry-run or previewed, provide a preview first; when deletion, overwriting, sending, publishing, or writing remote state is involved, ask the client for confirmation first.
  4. After execution, verify the real output; do not substitute "looks successful" for evidence.
  5. The final reply must give the client a visible summary: what was done, log summary, file changes, issues, and next steps.

Dependencies and installation

Install this skill (single skill):

npx skills add soia-team/soia-open-pkm-clip-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 may skip creating config.yml。
  • If an API key, cookie, session, provider home, or local path is needed, it may only go into a private config.yml, the process environment, or the provider's own login state; it must not be written into the repository, vault body, or logs.
  • Strong dependencies, optional dependencies, and third-party skill relationships must be based on this SKILL.md and the subsequent "dependencies / prerequisites / resources / boundaries" description; if it is not clearly written, add the description first or ask the client, do not guess.
  • Third-party skills may only declare dependencies and installation methods; do not directly modify third-party skill files.

Logs and completion receipt

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 across the timeline, Article formatting is messy, links easily expire, and search is weak. This skill preserves high-quality long-form content from X into Obsidian in one click:

  • Complete thread unroll
  • X Article retrieves the full content.blocks
  • Complete metadata (author, metrics, direct media links, created_at)
  • Frontmatter topic double links, 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 for MTProto sync)
  • vault location priority:
    1. command line --vault <path>
    2. environment variable OBSIDIAN_VAULT
    3. auto-discover vault upward from the current working directory (look for AGENTS.md / .obsidian)
  • article directory location priority:
    1. command line --articles-dir <subdir>
    2. environment variable OBSIDIAN_ARTICLES
    3. fall back to generic default Articles; the script prints 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 first loads the private config.yml, then auto-discovers the vault from cwd; if the agent is already in the vault directory, just run it directly.

  • Private config.yml(optional,do not put it in the vault or in the 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 written only in the private config.yml and not in this file.

Core API: fxtwitter

Replace the x.com in the X URL with api.fxtwitter.com, and GET the JSON directly. No X API key needed, no login needed, 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.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 phrase

User says Invoke
"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>. Non-Chinese content automatically gets a translation appended by default (see step 4 of the workflow below); there is 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
"Tidy up this thread: URL" Same as above, force thread backtracking
"Sync my Telegram saved messages" + provide the JSON path sync_telegram_export.py <path> --dry-run check first, run for real after confirmation
"Sync Telegram via 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 the frontmatter url: field)
    • Already exists → output SKIP, exit
    • Otherwise → fetch fxtwitter, write to vault
  4. AI then supplements:
    • 1-sentence Chinese ## 摘要
    • 1-3 topics Dual-link + people dual-link
    • Non-Chinese content (language is not zh): by default fill in ## 中文译文 segments to form a complete translation, without the user needing to additionally say "translate". Requirementfree translation, not literal translation—it should read like Chinese written by a human, not machine-translation-speak; proper nouns, product names, and code/command/API parameters keep their original English, translating only narrative text and explanations
  5. The "My take" section is always left empty for the user

Export to 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 calling Obsidian's built-in "Export PDF"; external PDF engines may only serve as an explicit fallback.

Telegram Saved Messages batch sync

Batch-archive into the vault the X links casually forwarded from a phone to Telegram "Saved Messages".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 by 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 Tweet deleted/private, suggest checking archive.org
fxtwitter 5xx Retry once, fall back to the syndication endpoint on failure
URL is not x.com / twitter.com Reject, suggest using Web Clipper
Tweet text empty and no article and no media Warn: "pure retweet/pure reply, may have no standalone content"
Duplicate filename for same author on same day Append at the end -<status_id 后 6 位>
Video media frontmatter media[] record the mp4 direct link, do not embed

Command-line reference (archive)

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。


Post-completion receipt

Delivery order: first write the file to disk, then output the receipt below; never the reverse; for uncertain metadata (e.g., failed parsing of author or publish time) explicitly mark "unverified" in the receipt; do not fabricate.

After executionmustoutput to the user (do not silently finish):

  1. What was done — summarize the completed work in one sentence.
  2. File changes — list 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 explicitly note that this directory is not the vault's official archive location, and suggest the user configure --articles-dir、OBSIDIAN_ARTICLES or a private config.yml and then relocate.
  3. Next steps — optional follow-up suggestions (e.g., the next skill to connect with).