Clipsmith Capture
Use this skill when the user wants to download, save, capture, archive, or OCR a
post, article, or local media item into a Clipsmith bundle.
Recover Before Reporting Failure
A provider script failure does not by itself establish that content is
unavailable. Inspect the actual browser/local state and error, distinguish
readable content from a real login/risk wall, and continue routine recovery
within the user's authorized scope. Correct demonstrated local causes or make
a small reversible repair to the existing provider, verify it, and resume the
original capture and authorized sink. Preserve partial assets and unrelated
edits. Do not ask the user to reconfirm an accessible link before investigating.
Do not blindly retry or bypass platform protection. Escalate when a genuine
login/CAPTCHA/account restriction requires user action, a required change is
outside scope, or evidence-based investigation and repairs cease making progress.
Explain the evidence, attempts, preserved files, and specific remaining blocker.
For X captures, follow clipsmith-x's references/recovery.md.
Flow
Start a job:
clipsmith capture start "<input>" --state-dir "<state_dir>"
Read the returned provider, job_id, and job_path.
Use the matching platform skill:
clipsmith-xhs
clipsmith-x
clipsmith-wechat
clipsmith-web
clipsmith-ocr
The platform skill may first run a copied downloader that produces raw
assets. Before returning, it must convert raw output into a bundle with the
shared normalizer when the provider does not already produce a validated
bundle:
uv run clipsmith normalize raw "<provider>" "<raw_dir>" "<bundle_dir>" \
--source-url "<original_url>" \
--json
The normalizer accepts raw_dir == bundle_dir (in-place finalize) — when the
downloader used --flat true (XHS) or equivalent, pass the same path for
both and add --overwrite. The normalizer reads the source files into memory
before the in-place rmtree, so this is safe.
The final bundle contains:
capture.json — bundle manifest, including content_files[] (post,
summary, ocr) and assets[] (image and video files under assets/)
post.md — extracted post text and metadata
summary.md — generated summary
ocr.md or ocr.txt (when OCR ran) — raw OCR transcript, declared in
capture.json.content_files with kind: "ocr-text". Do not store OCR text
only inside summary.md; the raw OCR file is part of the reviewable source
material.
assets/ — image files (.webp, .jpg, .jpeg, .png, .gif) and
video files (.mp4, .mov, .webm) moved from the raw dir, each declared
in capture.json.assets[] with kind: "image" or kind: "video". The
validator requires image and video assets to live under assets/; do
not place them at the bundle root.
Validate and finalize:
clipsmith validate-bundle "<bundle_dir>" --json
clipsmith capture finalize "<job_id_or_job_path>" "<bundle_dir>" --state-dir "<state_dir>"
Report the bundle path, status, warnings, and validation issues.
Do not write knowledge records. Do not move the bundle into an external inbox
workspace unless the user explicitly requested an inbox sink.
1---2name: clipsmith-capture3description: Capture a URL or local media input into a portable Clipsmith bundle. Routes to platform-specific Clipsmith skills and validates the resulting bundle.4metadata:5 source: https://skillmd.com/skills/octopusgarage/clipsmith-capture6---78# Clipsmith Capture910Use this skill when the user wants to download, save, capture, archive, or OCR a11post, article, or local media item into a Clipsmith bundle.1213## Recover Before Reporting Failure1415A provider script failure does not by itself establish that content is16unavailable. Inspect the actual browser/local state and error, distinguish17readable content from a real login/risk wall, and continue routine recovery18within the user's authorized scope. Correct demonstrated local causes or make19a small reversible repair to the existing provider, verify it, and resume the20original capture and authorized sink. Preserve partial assets and unrelated21edits. Do not ask the user to reconfirm an accessible link before investigating.2223Do not blindly retry or bypass platform protection. Escalate when a genuine24login/CAPTCHA/account restriction requires user action, a required change is25outside scope, or evidence-based investigation and repairs cease making progress.26Explain the evidence, attempts, preserved files, and specific remaining blocker.27For X captures, follow `clipsmith-x`'s `references/recovery.md`.2829## Flow30311. Start a job:3233 ```bash34 clipsmith capture start "<input>" --state-dir "<state_dir>"35 ```36372. Read the returned `provider`, `job_id`, and `job_path`.383. Use the matching platform skill:39 - `clipsmith-xhs`40 - `clipsmith-x`41 - `clipsmith-wechat`42 - `clipsmith-web`43 - `clipsmith-ocr`444. The platform skill may first run a copied downloader that produces raw45 assets. Before returning, it must convert raw output into a bundle with the46 shared normalizer when the provider does not already produce a validated47 bundle:4849 ```bash50 uv run clipsmith normalize raw "<provider>" "<raw_dir>" "<bundle_dir>" \51 --source-url "<original_url>" \52 --json53 ```5455 The normalizer accepts `raw_dir == bundle_dir` (in-place finalize) — when the56 downloader used `--flat true` (XHS) or equivalent, pass the same path for57 both and add `--overwrite`. The normalizer reads the source files into memory58 before the in-place rmtree, so this is safe.5960 The final bundle contains:61 - `capture.json` — bundle manifest, including `content_files[]` (post,62 summary, ocr) and `assets[]` (image and video files under `assets/`)63 - `post.md` — extracted post text and metadata64 - `summary.md` — generated summary65 - `ocr.md` or `ocr.txt` (when OCR ran) — raw OCR transcript, declared in66 `capture.json.content_files` with `kind: "ocr-text"`. Do not store OCR text67 only inside `summary.md`; the raw OCR file is part of the reviewable source68 material.69 - `assets/` — image files (`.webp`, `.jpg`, `.jpeg`, `.png`, `.gif`) and70 video files (`.mp4`, `.mov`, `.webm`) moved from the raw dir, each declared71 in `capture.json.assets[]` with `kind: "image"` or `kind: "video"`. The72 validator requires `image` and `video` assets to live under `assets/`; do73 not place them at the bundle root.745. Validate and finalize:7576 ```bash77 clipsmith validate-bundle "<bundle_dir>" --json78 clipsmith capture finalize "<job_id_or_job_path>" "<bundle_dir>" --state-dir "<state_dir>"79 ```80816. Report the bundle path, status, warnings, and validation issues.8283Do not write knowledge records. Do not move the bundle into an external inbox84workspace unless the user explicitly requested an inbox sink.