SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssoia-pkm-clip-repo

soia-pkm-clip-repo

General & other

View repository

Updated 10-16 08:10

About this skill

soia-pkm-clip-repo

Distill open-source code repository research scattered everywhere into a filterable, clickable "Open-Source Project Library" index layer in an Obsidian vault.

Customer-Readable Description

What This Skill Can Do

Archive GitHub open-source project repositories to the "Open-Source Project Library" in an Obsidian vault with one click — clone the upstream code (not into the vault) + generate/update a project card (category/language/access link/latest commit filled in automatically; purpose/status/stars/my notes left for manual entry) + create a research note skeleton + bidirectional links; it also supports batch reruns to refresh the automatic fields of all project cards. When the user says "archive this project URL" "archive this repository"...

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, URLs, 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, ask the customer for confirmation first.
  4. After execution, verify the actual 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 (a single skill):

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

Configuration conventions:

~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-clip-repo/config.yml
SOIA_PKM_CLIP_REPO_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 be placed in a private config.yml, the process environment, or the provider's own login state, and must not be written into the repository, vault body, or logs.
  • Strong dependencies, optional dependencies, and third-party skill relationships must be based on the "dependencies / prerequisites / resources / boundaries" description following this SKILL.md ; if it is not clearly written, add the description first or ask the customer, and do not guess.
  • Third-party skills can only declare dependencies and installation methods; do 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 / 缺依赖 / 需要客户确认 / 建议下一条命令；没有则写“无”>

Location

The code itself stays on the local machine in an upstream directory git clone (not into the vault); the vault only stores indexes— one project card per repo + one research note skeleton. The structure and design philosophy are the same as the cloud drive collection / personal library: external resources stay in place, the vault only holds a clickable, filterable index layer.

Prerequisites

  • Obsidian vault containing (or to be created with) two subdirectories:60_开源项目/00_图书馆/项目卡/ and 60_开源项目/10_调研笔记/

  • A local upstream directory for storing git clone repositories (any path, with each repository in its own subdirectory)

  • Python 3, pure stdlib, no third-party dependencies

  • Vault location priority: command line --vault > environment variable OBSIDIAN_VAULT

  • Upstream location priority: command line --upstream > private config SOIA_REPO_UPSTREAM_DIR

  • Private config.yml(optional,do not put in the vault or the open-source skill repository）：

    Priority:$SOIA_PKM_CLIP_REPO_CONFIG_FILE(or compatible alias $SOIA_PKM_CLIP_REPO_ENV_FILE）> ~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-clip-repo/config.yml。

    Supported variable names:OBSIDIAN_VAULT、SOIA_REPO_UPSTREAM_DIR. The actual path is written only in the private config.yml file, not in this file or the script source (the script itself does not hard-code any personal absolute paths).

Trigger Words

The user says invoke
"archive this project <url>" / "archive this repo" / "clip this repo" Single-repo archive mode:gen_repo_catalog.py --add <url>
"regenerate open-source project cards" / "batch refresh project cards" / "I just cloned a few repos, add cards for them" Batch mode:gen_repo_catalog.py --upstream <dir> --vault <path>

Workflow: archive open-source project <URL>

  1. Parse the URL to get owner/repo
  2. If the repo does not exist under the upstream directory -> git clone and enter it; if it already exists, skip clone and create the card directly
  3. clone fails (private repo / no permission / network issue) -> skip clone, use only the URL to generate a minimal card and prompt the user
  4. Call the generator in single-repo mode to create/update the project card for this one repo (60_开源项目/00_图书馆/项目卡/<仓名>.md）
  5. In 60_开源项目/10_调研笔记/ start a YYYY-MM-DD-调研-<仓名>.md skeleton note (if the repo already has a research note, skip creating one), with frontmatter containing 关联仓库 as a double link back to the project card; body skeleton: ## 是什么 / ## 架构与代码 / ## 对我的价值 / ## 运行验证 / ## 我的结论
  6. Bidirectional links: the card's "## Related Research" automatically lists this note; the note's 关联仓库 field points to this card

"Archive" is just quickly creating a card + note skeleton + double links; in-depth research (filling out the note body completely) is a separate follow-up step, outside the automation scope of this skill.

Batch mode (after cloning multiple repos, or to refresh all automatic fields)

python3 scripts/gen_repo_catalog.py --upstream <upstream目录> --vault <vault路径>

Scan every subdirectory under upstream and generate/update a project card for each repo. Idempotent: only refresh automatic fields, do not overwrite manual fields.

Project card frontmatter

---
tags: [开源项目]
仓名: "<仓名>"
github: owner/repo             # 自动：git remote get-url origin 转 owner/repo
分类: <11 类之一>                # 自动：仓名→分类映射表 REPO_CATEGORY_MAP；未列出的按
                                # README/名字启发式归类，兜底「工具其他」
语言: Rust / Go / JS/TS / Python / Java / Swift / 未知   # 自动：启发式扫构建文件
用途: ""                        # 人工：这个仓库对你的具体用途
状态: 研究中                     # 人工：研究中 / 已借鉴 / 已弃 等
本地路径: "<upstream 下绝对路径>"  # 自动
访问链接: "https://github.com/<owner>/<repo>"  # 自动：github 字段拼出的完整 URL
最近提交: "YYYY-MM-DD"           # 自动：git log -1 --format=%cs，非 git 目录留空
stars:                          # 人工
---

Automatic fields vs manual fields—this is the core convention of this skill:

  • Automatic fields（github / 分类 / 语言 / 本地路径 / 访问链接 / 最近提交 / body summary / body "## Related Research"): refreshed on every rerun, do not maintain manually; "## Related Research" matches by repo name 10_调研笔记/ filename (or its frontmatter 关联仓库) to automatically backfill the wikilink
  • Manual fields（用途 / 状态 / stars / body "## My Notes"): the generatordoes not overwrite, write whatever you like, safe to rerun

For the body summary, take the first narrative sentence in the README (skip headings/badges/HTML decorative lines/pure command lines/navigation bars); if it cannot be captured, leave it blank (待补描述)。

Command reference

# 单仓归档（clone + 建卡 + 起调研笔记骨架 + 双链）
python3 scripts/gen_repo_catalog.py --add https://github.com/<owner>/<repo> \
  --upstream <upstream目录> --vault <vault路径>

# 批量重跑（刷新全部仓库的自动字段）
python3 scripts/gen_repo_catalog.py --upstream <upstream目录> --vault <vault路径>

# 覆盖调研笔记目录（默认 60_开源项目/10_调研笔记）
python3 scripts/gen_repo_catalog.py --upstream <dir> --vault <path> --notes-dir <相对路径>

Boundaries and exceptions

Scenario Handling
clone fails (private repository/no permission/network issue) Skip clone, generate a minimal card using only the URL, and prompt the user to handle it manually
Non-git directory (manually copied, project where git clone was never run) github/最近提交 leave blank, do not report an error
Repository is not in the hardcoded REPO_CATEGORY_MAP li Use README/repository-name keyword heuristics; if none can be determined, classify as "Tools Other"
Project card already exists Idempotent update: refresh only automatic fields; manual fields and "## My Notes" are preserved as-is
Projects researched separately outside upstream and not intended to be cloned This skill does not apply; use the vault's _模板/项目卡模板.md to manually create a card
Not specified --vault/--upstream and the private configuration is also not set Report an error and indicate the environment variable name; do not silently use some hardcoded default path

Completion receipt

Delivery order: first write the project card/research notes to disk, then output the receipt below; do not reverse the order. If automatic field capture fails (for example, a non-git directory cannot get the latest commit), explicitly mark it as "unverified" in the receipt; do not fabricate.

After executionmustoutput to the user (do not silently finish):

  1. What was done — a one-sentence summary (single-repository archiving / batch refresh, how many repositories were involved).
  2. File changes — list newly created / updated project cards and newly created research notes (full paths).
  3. Next steps — remind the user: after reading the code/finishing the research, fill back the project card's 用途、状态, "## My Notes".