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

soia-pkm-clip-github-repo

Office & productivity

View repository

Updated 10-16 08:28

About this skill

soia-pkm-clip-github-repo

Distill open-source code repository research scattered everywhere into a filterable, clickable "open-source project library" index layer in an Obsidian vault.

Client-readable description

What this skill can do

Archive GitHub open-source project repositories into 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/most recent commit auto-filled; purpose/status/stars/my notes left manual) + create a research note skeleton + bidirectional links; it also supports batch re-runs to refresh the auto fields of all project cards. When the user says "archive this project URL", "archive this repo"...

What the client wants What the skill will do What the client can see
Complete the work covered by this skill Read the user request, necessary context, and this skill's main workflow, and execute the minimum reliable steps The client 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 URLs, 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

  1. State the goal in natural language and provide the necessary inputs: files, URLs, repos, workspace, proposal, vault, or platform account status.
  2. 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 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 have two indexes that 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-github-repo -y

Configuration conventions:

~/.config/soia-skills/soia-pkm-clip-github-repo/config.yml
SOIA_PKM_CLIP_GITHUB_REPO_CONFIG_FILE=<custom-config-path>
# 兼容别名：$SOIA_PKM_CLIP_REPO_CONFIG_FILE（以及原有 $SOIA_PKM_CLIP_REPO_ENV_FILE）
  • 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 private config.yml, the process environment, or the provider's own login state; it must not be written into the repo, vault body, or logs.
  • Third-party skills can only declare dependencies and installation methods; they 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

Writing the project card to disk only proves captured; afterward it must be handed off to lifecycle management to complete organized → MOC/导航 → map → Base. For the contract details, see the lifecycle skill's references/knowledge-intake-five-stage-contract.md; for inapplicable phases, explicitly write not_applicable。

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

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

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

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

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

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

Location

The code itself stays in an upstream directory git clone on the local machine (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, and the vault only holds a clickable, filterable index layer.

Prerequisites

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

  • An upstream directory on this machine for storing git clone repositories (any path; multiple repositories each occupy a 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's SOIA_REPO_UPSTREAM_DIR

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

    Priority:$SOIA_PKM_CLIP_GITHUB_REPO_CONFIG_FILE(compatible alias $SOIA_PKM_CLIP_REPO_CONFIG_FILE, as well as the existing $SOIA_PKM_CLIP_REPO_ENV_FILE）> ~/.config/soia-skills/soia-pkm-clip-github-repo/config.yml。

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

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 the open-source project card" / "batch refresh project cards" / "I cloned a few new 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 go in; if it already exists, skip clone and directly create the card
  3. clone fails (private repository/no permission/network issue) → skip clone, generate a minimal card using only the URL and prompt the user
  4. Call the generator in single-repo mode to create/update a 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 a new one), with frontmatter containing 关联仓库 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 + bidirectional links; in-depth research (filling in the note body completely) is a separate subsequent step, and is not within the automation scope of this skill.

Batch mode (multiple new repos cloned, or wanting to refresh all automatic fields)

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

Scan each subdirectory under upstream, and generate/update a project card repo by 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 introduction / 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 want, rerunning is safe

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

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; only use the URL to generate a minimal card, and prompt the user to handle it manually
Non-git directory (manually copied, project that has never run git clone ) github/最近提交 Leave blank; do not report an error
Repository is not in the hardcoded REPO_CATEGORY_MAP 里 Use README/repo-name keyword heuristics; if none can be determined, categorize as "Other Tools"
Project card already exists Idempotent update: only refresh automatic fields; keep manual fields and "## My Notes" as-is
Projects to research separately outside upstream and not intended to be cloned This skill does not apply; use the in-vault _模板/项目卡模板.md to manually create a card
--vault / --upstream is not specified and private config is also not set --vault/--upstream is not specified and private config 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 persist the project card/research notes to disk, then output the receipt below; do not reverse the order. If automatic field retrieval fails (e.g., cannot get the latest commit in a non-git directory), explicitly mark it as "unverified" in the receipt; do not fabricate.

The receipt includes:

  1. What was done — a one-sentence summary (single-repo archive / 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 in the project card's 用途、状态, "## My Notes".