Communitygithub.com

soia-pkm-clip-x

Agent-Fertigkeit zum täglichen Wissensmanagement. Archive X-Tweets/Threads/Artikel in Obsidian, inklusive Telegram-Synchronisation. Funktioniert mit Claude Code / Codex / Cursor.

Was ist soia-pkm-clip-x?

Diese Fertigkeit namens "soia-pkm-clip-x" ist ein KI-Agenten-Tool, das Entwickler und Wissensarbeiter dabei unterstützt, wertvolle Inhalte von der Plattform X (ehemals Twitter) direkt in einen Obsidian-Vault zu archivieren. Der Hauptvorteil liegt darin, dass die native X-Oberfläche für die langfristige Wiederverwendung ungeeignet ist – Threads gehen im Timeline-Chaos verloren, X-Artikel haben eine schlechte Formatierung und die Suche ist schwach. Das Skill löst dies, indem es X-Links automatisch in strukturierte Markdown-Notizen umwandelt, vollständige Threads entrollt, Metadaten (Autor, Aufrufe, Likes, Mediendirektlinks) erfasst und diese mit Frontmatter und Tags wie `topics` und `people` für die spätere Suche und MOC-Aggregation (Map of Content) anreichert. Es unterstützt die Sprachen Chinesisch, Englisch, Japanisch und Koreanisch, fügt standardmäßig eine chinesische Zusammenfassung und Übersetzung hinzu (sofern der Inhalt nicht auf Chinesisch ist) und bietet eine nahtlose Integration mit Claude Code, Codex und Cursor. Darüber hinaus ermöglicht das Skill die Synchronisation von Telegram Saved Messages über zwei Wege: per JSON-Export (empfohlen, risikofrei) oder über die MTProto API für fortgeschrittene Benutzer. Die dedizierten Python-Skripte (`archive_x.py`, `sync_telegram_export.py`, `sync_telegram_saved.py`) benötigen nur die Python-Standardbibliothek (optional `telethon` für MTProto) und arbeiten über den kostenlosen fxtwitter Proxy, sodass kein X-API-Key erforderlich ist.

Funktioniert mit✓Claude Code✓Codex CLI✓Cursor
npx skills add soia-team/soia-open-skills

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht soia-pkm-clip-x?

Wertvolle Inhalte von X in deinem Obsidian-Vault sichern und durchsuchbare Wissensbestände aufbauen.

Zielsetzung

Die native X-Oberfläche ist für die langfristige Wiederverwendung ungeeignet: Threads verschwinden im Timeline-Chaos, X-Artikel sind schlecht formatiert, Links verfallen schnell und die Suche ist schwach. Dieses Skill archiviert hochwertige Langinhalte von X mit einem Klick in Obsidian:

  • Threads vollständig entrollt
  • X-Artikel mit vollständigen content.blocks
  • Vollständige Metadaten (Autor, Metriken, Medien-Direktlinks, created_at)
  • Frontmatter mit Themen-[[Links]] für einfache MOC-Aggregation
  • Mehrsprachige Erkennung (zh / en / ja / ko)

Voraussetzungen

  • Obsidian-Vault (beliebige Struktur)

  • Python 3, reine stdlib (keine Drittanbieter-Abhängigkeiten für einzelne Tweets)

  • Optional: pip install telethon (nur für MTProto-Synchronisation)

  • Umgebungsvariablen setzen:

    export OBSIDIAN_VAULT=~/Documents/MyVault
    # Optional: Benutzerdefiniertes Unterverzeichnis für Artikel (Standard: "Articles")
    export OBSIDIAN_ARTICLES="Articles"
    # Optional: Sprache der Abschnittsüberschriften, Standard zh (Chinesisch), auf en für englische Überschriften setzen
    export X_ARCHIVE_LANG=zh
    

Kern-API: fxtwitter

Ersetze x.com in der X-URL durch api.fxtwitter.com und erhalte direkt ein JSON per GET. Kein X-API-Key, kein Login, keine Kosten.

SchlüsselfeldVerwendung
tweet.text / tweet.raw_text.textTweet-Text
tweet.article.titleTitel des X-Artikels
tweet.article.content.blocks[]Langtext-Blöcke des Artikels
tweet.replying_to_statusVorheriger Tweet (Thread-Rückverfolgung)
tweet.quoteZitierter Tweet
tweet.media[]Medien (Bild/Video-Direktlinks)
tweet.created_timestampUNIX-Zeitstempel
tweet.views / likes / bookmarks / retweetsMetriken

Fallback: Falls fxtwitter fehlschlägt → öffentlicher Endpunkt cdn.syndication.twimg.com.

Auslösewörter

Benutzer sagtAufruf
„Archiviere diesen X: URL“ / „archive this: URL“archive_x.py <URL>, für nicht-chinesische Inhalte wird standardmäßig eine Übersetzung hinzugefügt (siehe Schritt 4 des Workflows unten), kein zusätzlicher „Übersetze“-Befehl nötig
„Bereite diesen Thread auf: URL“Gleicher Befehl, erzwingt Thread-Rückverfolgung
„Synchronisiere meine Telegram-Speicher“ + JSON-Pfadsync_telegram_export.py <path> --dry-run zur Vorschau, dann Bestätigung für Ausführung
„Mit API synchronisieren“ (bereits mit Anmeldedaten)sync_telegram_saved.py

Workflow (Standardarchivierung)

  1. URL parsen → handle + status_id
  2. Skript archive_x.py <URL> ausführen
  3. Skript prüft, ob der Vault bereits archiviert (anhand des Frontmatter-Felds url:)
    • Bereits vorhanden → Ausgabe SKIP, Ende
    • Sonst → fxtwitter abrufen, in den Vault schreiben
  4. KI ergänzt anschließend:
    • 1 Satz chinesische Zusammenfassung ## 摘要
    • 1-3 topics-[[Links]] + people-[[Links]]
    • Nicht-chinesischer Inhalt (language ist nicht zh): Standardmäßig den Abschnitt ## 中文译文 mit vollständiger Übersetzung versehen, ohne dass der Benutzer „Übersetze“ sagen muss. Anforderung: sinngemäß übersetzen, nicht wörtlich – der Text soll wie von einem Menschen auf Chinesisch geschrieben klingen, nicht wie maschinelle Übersetzung; Eigennamen, Produktnamen, Code/Befehle/API-Parameter im englischen Original belassen, nur narrative Texte und Erklärungen übersetzen
  5. Der Abschnitt „Meine Meinung“ bleibt immer für den Benutzer leer

Telegram-Synchronisation – Zwei Wege

A. JSON-Export (empfohlen, risikofrei)

Telegram Desktop
  → Einstellungen → Erweitert → Telegram-Daten exportieren
  → „Privatchats“ anhaken + JSON-Format wählen
  → result.json erhalten
python3 sync_telegram_export.py <result.json> --dry-run   # Liste anzeigen
python3 sync_telegram_export.py <result.json>             # Ausführung

Automatische Deduplizierung per URL und Überspringen bereits archivierter Einträge. Einmal monatlicher Export reicht für inkrementelle Synchronisation.

B. MTProto API (fortgeschritten, für China mit Vorsicht zu genießen)

Erforderlich:

  • Auf https://my.telegram.org/auth api_id / api_hash beantragen
  • generate_telegram_session.py ausführen, um session_string zu erhalten
  • Residential IP (Nutzer in China müssen HK/JP Residential IPs verwenden, Rechenzentrum-IPs führen zu ERROR)

⚠️ Nutzer in China priorisieren Weg A. Das Erstellen einer App auf my.telegram.org löst auf dem chinesischen Festland fast immer IP-Risikokontrollen aus, wiederholte Versuche können zu einer 24-72-stündigen Kontosperrung führen.

Dateinamenskonvention

<YYYY-MM-DD>-X-<handle>-<erste 50 Zeichen des Titels>.md

Beispiel:

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

Bei mehreren Einträgen desselben Autors am selben Tag → -<letzte 6 Ziffern der status_id> anhängen.

Ausgabe-Frontmatter

---
tags: [文章摘抄]
source: X
url: https://x.com/<handle>/status/<id>
author: <Anzeigename>
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]]", ...]   # von KI ausgefüllt
people: ["[[xxx]]", ...]   # von KI ausgefüllt
media: [...] / 0
content_complete: true
metrics:
  views: N
  likes: N
  bookmarks: N
---

Grenzfälle und Ausnahmen

SzenarioBehandlung
fxtwitter gibt 404 zurückTweet gelöscht/privat, archive.org empfehlen
fxtwitter 5xx1 Wiederholungsversuch, bei Fehlschlag Fallback auf syndication-Endpunkt
URL ist nicht x.com / twitter.comAblehnen, Web Clipper empfehlen
Tweet-Text leer und kein Artikel und keine MedienWarnung: „Reiner Retweet/Reply, möglicherweise kein eigenständiger Inhalt“
Dateiname am selben Tag/selber Autor doppelt-<letzte 6 Ziffern der status_id> anhängen
Video-MedienDirekter mp4-Link im Frontmatter media[], nicht eingebettet

Befehlszeilenreferenz

# Einzelnen Tweet archivieren
python3 archive_x.py <URL>
python3 archive_x.py <URL> --force                  # Bereits archivierte überschreiben
python3 archive_x.py <URL> --vault /pfad/zum/vault # Umgebungsvariable überschreiben

# Telegram-JSON-Export synchronisieren
python3 sync_telegram_export.py <result.json>
python3 sync_telegram_export.py <result.json> --dry-run
python3 sync_telegram_export.py <result.json> --since 2026-06-01
python3 sync_telegram_export.py <result.json> --limit 30

# MTProto-Synchronisation (muss zuerst eingerichtet werden)
python3 generate_telegram_session.py    # Einmalig
python3 sync_telegram_saved.py --dry-run
python3 sync_telegram_saved.py --days 30
python3 sync_telegram_saved.py --all

Verwandte Skills