soia-pkm-clip-web

soia-pkm-clip-web

clip family'sgeneral web member: deposit blog / web articles into the vault.

Customer-readable description

What this skill can do

Archive any webpage/blog article to an Obsidian vault with one click. Use content extraction (readability/trafilatura) to extract the title/body/author, and land it according to the unified conventions of the clip family. When the user says "archive and convert to PDF", "archive and export PDF", or "archive and export PDF", after archiving, within the Obsidian vault, prioritize calling Obsidian's built-in PDF...

What the customer wants	What the skill will do	What the customer 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 customer will see Obsidian/vault file changes, terminal logs, generated artifact paths, and the final receipt.
Missing dependencies, permissions, configuration, or key	Stop actions that require external state, and clearly state what is missing	Installation commands, application addresses, configuration paths, or questions that require customer 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 customer uses it

1. State the goal in natural language, and provide the necessary inputs: files, URL, repo, workspace, proposal, vault, or platform account status.
2. The Agent first determines whether this skill is triggered, 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, seek customer confirmation first.
4. After execution, verify the real output; do not substitute "looks successful" for evidence.
5. The final reply must give the customer 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-skills -g -a '*' -s soia-pkm-clip-web -y

Configuration conventions:

~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-clip-web/config.yml
SOIA_PKM_CLIP_WEB_CONFIG_FILE=<custom-config-path>

• If this skill does not require private configuration, you may skip creating config.yml。
• If an API key, cookie, session, provider home, or local path is required, it may only be placed in 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 The subsequent "dependencies / prerequisites / resources / boundaries" description shall prevail; if it is not clearly written, first supplement the description or ask the customer, and do not guess.
• Third-party skills may only declare dependencies and installation methods, and must not directly modify third-party skill files.

Logs and completion receipt

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

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

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

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

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

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

Fetch

• Input: any article URL (blog / Substack / Medium / news / Zhihu, etc.)
• Content extraction:trafilatura or readability-lxml Extract the body (remove ads / navigation), and extract the title, author, and publication time.
• Cannot fetch the body → content_complete: false，never silently truncate。
• Fetching and saving are currently performed manually by the agent according to the process in this section (a dedicated archiving script is yet to be added to this skill's scripts/）。
• On mobile, you can use Obsidian Web Clipper to save to <vault-inbox-dir>/, and then this skill migrates it in.

Mandatory review of fetch quality

A script exit code of 0 does not mean the fetch succeeded—some sites return login walls, navigation shells, or anti-scraping block pages as normal responses, and the script will not report an error.Before writing into the vault, you must read the output yourself, and verify: whether the title matches the original page (not a site-generic title like "Login" or "Access Exception"), whether the body is the complete article (not a pile of navigation bars/sidebars, and not all links), and whether the word count roughly matches the original's length.

Failure signal checklist (hitting any one of these means it is judged a failure and must not be delivered directly):

• Login wall/verification keywords such as "Login", "Please log in first", "verify you are human" appear
• The body is obviously too short (should be a long article but has only a few dozen characters)
• The body is almost entirely links, with no substantive prose

When a failure signal is hit, switch strategies (switch readability-lxml/trafilatura as mutual fallbacks, prompt the user to log in manually and retry, or truthfully mark content_complete: false and remind for manual verification against the original), rather than writing the block page into the vault as the body.

Saving (unified specification for the clip family)

• Path:<vault-articles-dir>/<年>/YYYY-MM-DD-<来源>-<作者>-<标题>.md(sources such as Blog / Substack / Medium)
• frontmatter is the same as the clip family; body ## 摘要 / 原文 / 我的看法 / 关联。
• After archiving, add summary + topics; use organize to file it into place.

Export PDF after archiving

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

Closed-loop position

★clip-web(收) → organize → distill → compose → publish。

---

Receipt after completion

Delivery order: first write the file to disk, then output the receipt below; do not reverse the order; explicitly mark uncertain metadata (such as author or publish time that failed to parse) as "unverified" in the receipt; do not fabricate.

After execution,you mustoutput to the user (do not silently finish):

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