soia-pkm-clip-wechat-article

clip family'sOfficial Account member: file WeChat Official Account articles into the vault.

Client-readable description

What this skill can do

Archive a single WeChat Official Account article to an Obsidian vault: fetch the static HTML, extract the title, author, body, publish time, and images, and file it according to the clip family conventions; when a PDF is needed, prefer exporting from Obsidian

Client wants	Skill will do	Client can see
Complete the work covered by this skill	Read the user request, necessary context, and this skill's body 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 commands, application addresses, configuration paths, or questions requiring 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

State the goal in natural language and provide the necessary inputs: files, URLs, repos, workspaces, proposals, vaults, or platform account status.
For actions that can be dry-run or previewed, give a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, ask the client for confirmation first.

Dependencies and installation

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

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-pkm-vault@soia

If 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 in two indexes and drift separately, 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-wechat-article -y

The current script's configuration entry point:

OBSIDIAN_VAULT=<vault-path>
OBSIDIAN_ARTICLES=<vault-relative-articles-dir>

CLI --vault / --articles-dir takes precedence over environment variables; if neither is provided, only search upward from the current directory for a real .obsidian/ flag.
If --articles-dir、OBSIDIAN_ARTICLES are both missing, the script still retains the Articles/ fallback for compatibility with existing workflows, but will print a clear warning to stderr; the receipt must include the actual on-disk directory, and when the fallback is used, recommend configuring a formal articles directory and then relocating them.
The current stdlib script does not parse YAML config.yml, nor does it need an API key, cookie, or other credentials; do not create a configuration file that will not take effect.
Third-party skills can only declare dependencies and installation methods; they do not directly modify third-party skill files.

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

Logs and completion receipt

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

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

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

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

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

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

Fetching

Input:https://mp.weixin.qq.com/s/...
WeChat Official Account articles arestatic HTML(easier to fetch than X, no API needed): stdlib urllib.request fetch the page → parse #js_content(body),#activity-name / og:title(title), author meta (byline author),#js_name(official account name),createTime / oriCreateTime(publish time fallback).
Images: extract data-src and keep as remote links; the current script does not download images, offline conversion is handled by a later process.
Script:scripts/archive_wechat.py <url> --vault <path>(pure Python standard library; supports --dry-run、--json, URL deduplication, content quality gate, and atomic write). URL deduplication is normalized:?click_id=/scene=/poc_token= and other tracking parameters do not affect identity; the same article with and without query will be recognized as the same article;s?__biz=&mid=&idx=&sn= form also preserves identity parameters.

python3 scripts/archive_wechat.py <url> \
  --vault <vault-path> \
  --articles-dir <vault-relative-articles-dir> \
  --dry-run --json

First dry-run to verify the title, author, publish time,body_chars, image count, and content_complete, then remove --dry-run and write. If #js_contentcannot be found, the content is abnormally short, or an interception page keyword is hit, writing is denied by default, and the receipt gives block_reason（wechat_captcha / wechat_param_error / wechat_rate_limited / deleted / content_unavailable); when a CAPTCHA/parameter error is hit, prompt "open the original article in a browser and copy the readable /s/ link, or manually paste the content". Only use --allow-incomplete。

when the client explicitly accepts an incomplete archive (unified convention for the clip family)

Path:<vault-articles-dir>/<年>/<月>/YYYY-MM-DD-公众号-<作者>-<标题>.md
frontmatter：tags:[文章摘抄]、source: 公众号、url、author、publisher、published_at、captured_at、topics:[]、content_complete
Content paragraphs:## 摘要(AI supplement),## 原文、## 我的看法(leave blank),## 关联
Single-article archiving continues by default to call soia-pkm-organize-article-moc for minimal organization: supplement summary/topics, confirm the year-month directory, and use rebuild_moc.py --article <path> to incrementally sync affected MOCs, then trigger map/Base gates based on path changes. Do not call --full-rebuildfor single-article archiving. Only when the user explicitly says "archive only/do not organize" should it stop at clip; for batch official account archiving, first list the inventory, then confirm whether to organize in batch.
The archive receipt must separately report captured、organized、moc_synced、map_synced、base_verified; if post-processing fails, it can only say "archived, organization incomplete".
The receipt must include the actual on-disk directory; if --articles-dir or OBSIDIAN_ARTICLES is not configured and the Articles/ fallback is used, a warning must be explicitly marked, and it is recommended to configure the formal articles directory and then relocate.

Verification

python3 -m unittest discover -s tests -p 'test_*.py'
python3 -m py_compile scripts/archive_wechat.py

When the repository maintainer runs from the repo root, replace the paths with skills/soia-pkm-clip-wechat-article/tests and skills/soia-pkm-clip-wechat-article/scripts/archive_wechat.py. These two checks specifically prevent SKILL from again declaring a script that is not delivered with the installation package.

Export PDF after archiving

When the user also requests "convert to PDF / export PDF", first complete the Markdown archiving, summary, topics, 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 can only be used as an explicit fallback.

Closed-loop location

★clip-wechat(收) → organize → distill → compose → publish. Shares the landing convention with clip-x/web/drive, only the source differs.

Receipt after completion

Delivery order: first write the file to disk, then output the receipt below; do not reverse the order; uncertain metadata (such as author or publish time parsing failure) must be explicitly marked "unverified" in the receipt, do not fabricate.

The receipt includes:

What was done — a one-sentence summary of the completed work.
File changes — list newly created / modified / moved files (full paths); if no files were changed, state "no files changed".
Next steps — optional follow-up suggestions (such as the next skill to connect to).