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

soia-pkm-clip-github-repo

Office & productivity

View repository

Updated 10-16 09:08

About this skill

soia-pkm-clip-github-repo

Turn research on open-source code repositories 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 project cards (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 reruns to refresh the auto fields of all project cards. When the user says "archive this project URL," "archive this repo"...

The customer wants The skill will do The customer can see
Complete the work covered by this skill Read the user request, necessary context, and the main workflow of this skill, and execute the minimum reliable steps The customer will see Obsidian/vault file changes, terminal logs, generated artifact paths, and the final receipt.
Missing dependencies, permissions, configuration, or keys Stop actions that require external state and clearly identify what is missing Install 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 Customers Use It

  1. Describe the goal in natural language and provide the necessary inputs: files, URLs, repos, 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 (single skill):

npx skills add soia-team/soia-open-pkm-clip-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 may 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 repository, vault body, or logs.
  • Hard dependencies, optional dependencies, and third-party skill relationships must be based on the subsequent "dependencies / prerequisites / resources / boundaries" description in this SKILL.md ; 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; do not directly modify third-party skill files.

Logs and Completion Receipt

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

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

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

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

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

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

Location

The code itself remains in an upstream directory on the local machine git clone (not entering the vault); the vault only stores the index — 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 holds only 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 the local machine for storing git clone repositories (any path; each repository occupies 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's SOIA_REPO_UPSTREAM_DIR

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

    Priority:$SOIA_PKM_CLIP_GITHUB_REPO_CONFIG_FILE(compatible alias $SOIA_PKM_CLIP_REPO_CONFIG_FILE, as well as the original $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 written only 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 repository" / "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 repositories, add cards for them" Batch mode:gen_repo_catalog.py --upstream <dir> --vault <path>

Workflow: archive an open-source project <URL>

  1. Parse the URL to get owner/repo
  2. If there is no such repository under the upstream directory → git clone go in; if it already exists, skip the clone and create the card directly
  3. clone fails (private repository / no permission / network issue) → skip the clone, generate only a minimal card from the URL, and prompt the user
  4. Call the generator in single-repo mode to create/update the project card for this one repository (60_开源项目/00_图书馆/项目卡/<仓名>.md）
  5. In 60_开源项目/10_调研笔记/ start a YYYY-MM-DD-调研-<仓名>.md skeleton note (if this repository already has a research note, skip creating a new one); the frontmatter carries 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 in the note body completely) is a separate follow-up step, and is not within the automation scope of this skill.

Batch mode (multiple new repositories cloned, or you want to refresh all automatic fields)

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

Scan every subdirectory under upstream, and generate/update the project card for each repository one by one. Idempotent: only refresh automatic fields, and 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 repository name 10_调研笔记/ filename (or its frontmatter 关联仓库) automatically backfills the wikilink
  • Manual fields（用途 / 状态 / stars / body "## My Notes"): the generatordoes not overwrite, write whatever you like, 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 can't 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, generate a minimal card using only the URL, and prompt the user to handle it manually
Non-git directory (manually copied, a project where git clone has never been run) github/最近提交 leave blank, do not error
Repository not in the hardcoded REPO_CATEGORY_MAP list Use README/repository name keyword heuristics; if neither can be determined, categorize as "Other tools"
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 unset Error out and indicate the environment variable name; do not silently use someone's hardcoded default path

Receipt after completion

Delivery order: first write the project card/research notes to disk, then output the receipt below; this order must not be reversed; if automatic field retrieval fails (e.g., a non-git directory cannot get the latest commit), explicitly mark "unverified" in the receipt; do not fabricate.

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

  1. What was done — one-sentence summary (single-repository archive / batch refresh, how many repositories 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 research, backfill the project card's 用途、状态, and "## My Notes".