SuperAPI AI Directory

soia-pkm-clip-drive

General & other

View repository

Updated 10-16 08:46

About this skill

soia-pkm-clip-drive

clip family'scloud drive members: imports existing materials (PDF, DOCX, etc.) from network drives / local storage into the vault. Unlike web scraping, it handleslocal / cloud drive files。

Customer-readable description

What this skill can do

Batch-import existing materials (PDF/Word/spreadsheets/presentations/documents) from cloud drives or local storage into an Obsidian vault. Extract text, generate material notes, file them under the materials library or article excerpts, then hand off to organize for tidying. Images cannot be treated as body text based on filename alone; an explicit user request and an OCR backend are required.

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 body workflow, and execute the minimal reliable steps The customer will see Obsidian/vault file changes, terminal logs, generated artifact paths, and a 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 requiring 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. Describe the goal in natural language and provide the necessary inputs: files, URLs, repos, workspaces, proposals, vaults, or platform account status.
  2. For actions that support dry-run or preview, provide a preview first; ask the customer for confirmation before deleting, overwriting, sending, publishing, or writing remote state.

Dependencies and installation

Installation (recommended: install the entire domain plugin, setting up all skills in this repository at once):

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-pkm-vault@soia

When 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 with two indexes that drift independently, so it is recommended to choose one:

npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-clip-drive -y

Configuration conventions:

~/.config/soia-skills/soia-pkm-clip-drive/config.yml
SOIA_PKM_CLIP_DRIVE_CONFIG_FILE=<custom-config-path>
  • If this skill does not need private configuration, you can skip creating config.yml。
  • If an API key, cookie, session, provider home, or local path is needed, it can only go into private config.yml, the process environment, or the provider's own login state; it must not be written into the repository, vault body text, or logs.
  • Third-party skills can only declare dependencies and installation methods; do not directly modify third-party skill files.

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

Logs and completion receipt

Capture is only the captured stage of the five-stage ingestion contract; by default a single file continues to soia-pkm-manage-vault-lifecycle to complete organized → MOC/导航 → map → Base, and the receipt gives item-by-item pass or not_applicable. For the full contract, see the lifecycle skill's references/knowledge-intake-five-stage-contract.md。

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

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

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

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

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

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

Processing

  • Input: file path / directory (PDF, DOC/DOCX, PPT/PPTX, XLS/XLSX, TXT, Markdown; images require explicit OCR)
  • Extraction: for PDF use pypdf/pdfplumber or an equivalent tool, for DOCX use python-docx or an equivalent tool, convert legacy Office formats first; keep the original file until _附件/. Image OCR results must be marked with ocr, tool, and manual verification status.
  • Output to the query skill: keep the extracted draft source、original_path、source_sha256、extraction_method; then use soia-pkm-query-vault to search the extracted draft, without directly parsing the binary body.
  • Large batches: batch-process the directory, each file → one note.
  • Extraction and landing are currently performed manually by the agent according to the process in this section (a dedicated batch import script is to be added to this skill's scripts/)。

landing

  • Reference / reference-type materials → <vault-resources-dir>/<主题>/; article-type → <vault-articles-dir>/(determined by configuration or CLI parameters). When landing in 20_资料库/ , the target semantic directory must have a unique number; do not pile new materials directly in the root directory; if the category is uncertain, stop in Inbox first or hand off to the lifecycle skill to generate a manifest.
  • frontmatter:tags:[资料] or [文章摘抄]、source: 云盘/pdf、original_path、captured_at、topics:[]。
  • After importmust go through organize: cloud drive materials are usually large in volume and messy; rely on organize to categorize / build MOCs / deduplicate. As long as a file in Area 20 is created, you must follow soia-pkm-maintain-vault-health/references/index-sync-contract.md to rebuild OB知识库地图.md, and use vault_index_verify.py to verify the relevant Base; extracting attachment body text does not mean the index has been updated.

Closed-loop location

★clip-drive(收) → organize(云盘资料尤其依赖整理) → distill → …。


Receipt after completion

Delivery order: first write the files to disk, then output the receipt below; do not reverse the order; for uncertain metadata (such as missing source information for the original document), explicitly mark "unverified" in the receipt; do not fabricate.

The receipt includes:

  1. What was done — a one-sentence summary of the completed work.
  2. File changes — list newly created / modified / moved files (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).
  4. Index sync — if writing to Area 20, list the map updated, file/directory statistics, Base root path verification; if there is no Base, explicitly record that it is not configured.