Consolidate research on open source code repositories scattered everywhere into a filterable, clickable, jumpable "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 filled in automatically; purpose/status/stars/my notes left manual) + create a research note skeleton + bidirectional links; 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 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
- State the goal in natural language and provide the necessary inputs: files, URLs, repos, workspaces, proposals, vaults, or platform account status.
- The Agent first determines whether this skill applies, then checks dependencies, configuration, permissions, and risky actions.
- For actions that can be dry-run or previewed, provide a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, ask the customer for confirmation first.
- After execution, verify the real output; do not substitute "looks successful" for evidence.
- The final reply must give the customer a visible summary: what was done, a log summary, file changes, issues, and next steps.
Dependencies and installation
Install this skill (single skill):
npx skills add soia-team/soia-open-skills -g -a '*' -s soia-pkm-clip-github-repo -y
Configuration conventions:
~/.config/soia-skills/soia-open-skills/soia-pkm/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 API keys, cookies, sessions, provider homes, or local paths are needed, they may only be placed in private
config.yml, the process environment, or the provider's own login state; they must not be written into repositories, vault body text, or logs. - Strong dependencies, optional dependencies, and third-party skill relationships must be based on this
SKILL.mdThe subsequent "dependencies / prerequisites / resources / boundaries" description shall prevail; 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
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 git clone upstream directory (not into 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 only holds a clickable, filterable index layer.
Prerequisites
-
Obsidian vault, containing (or to be created) two subdirectories:
60_开源项目/00_图书馆/项目卡/and60_开源项目/10_调研笔记/ -
A local upstream directory 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 variableOBSIDIAN_VAULT -
upstream location priority: command line
--upstream> the private config'sSOIA_REPO_UPSTREAM_DIR -
private
config.yml(optional,do not put it 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-open-skills/soia-pkm/soia-pkm-clip-github-repo/config.yml。supported variable names:
OBSIDIAN_VAULT、SOIA_REPO_UPSTREAM_DIR. The real path is only written in the privateconfig.ymlfile, not in 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 cards" / "batch refresh the project cards" / "I cloned a few new repositories, add their cards" | batch mode:gen_repo_catalog.py --upstream <dir> --vault <path> |
Workflow: archive an open source project <URL>
- parse the URL to get
owner/repo - there is no such repo under the upstream directory →
git clonego in; if it already exists, skip the clone and directly create the card - clone fails (private repository/no permission/network issue) → skip the clone, only use the URL to generate a minimal card and prompt the user
- call the generator's single-repo mode to create/update the project card for this one repo (
60_开源项目/00_图书馆/项目卡/<仓名>.md) - in
60_开源项目/10_调研笔记/start aYYYY-MM-DD-调研-<仓名>.mdskeleton note (if the repo already has a research note, skip creating it), with frontmatter carrying关联仓库a double link back to the project card; body skeleton:## 是什么/## 架构与代码/## 对我的价值/## 运行验证/## 我的结论 - Bidirectional links: the card's "## Related Research" automatically lists this note; the note's
关联仓库field points to this card
"Archive" is just quick card creation + note skeleton + double links; deep research (completing the note body) is a separate subsequent step, not within the automation scope of this skill.
Batch mode (multiple new repositories 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 the 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 name10_调研笔记/file name (or its frontmatter关联仓库) automatically backfills the wikilink - Manual fields(
用途/状态/stars/ body "## My Notes"): the generatordoes not overwrite, write whatever you want, reruns are safe
The main text introduction takes the first narrative sentence in the README (skipping title/badge/HTML decorative lines/pure command lines/navigation bar), and leaves it blank when it cannot be captured. (待补描述)。
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 only a minimal card from the URL, and prompt the user to handle it manually |
Non-git directory (manual copy, a project where git clone has never been run) |
github/最近提交 leave blank, do not report an error |
The repository is not in the hardcoded REPO_CATEGORY_MAP is missing |
Use README/repository-name keyword heuristics; if none can be identified, classify as "Other Tools" |
| The project card already exists | Idempotent update: refresh only automatic fields; manual fields and "## My Notes" are preserved as-is |
| Projects to be researched separately outside upstream and not intended for clone | Not applicable to this skill; use the vault's _模板/项目卡模板.md to create a card manually |
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 someone's hardcoded default path |
Receipt after completion
Delivery order: first persist the project cards/research notes to disk, then output the receipt below; the order must not be reversed. If automatic field capture fails (for example, a non-git directory cannot obtain the latest commit), explicitly mark "unverified" in the receipt; do not fabricate.
After executionmustoutput to the user (do not finish silently):
- What was done — one-sentence summary (single-repository archival / batch refresh, how many repositories involved).
- File changes — list newly created / updated project cards and newly created research notes (full paths).
- Next steps — remind the user: after reading the code/finishing research, backfill the project card's
用途、状态, "## My Notes".