SuperAPI AI Directory

soia-pkm-clip-github-repo

General & other

View repository

Updated 10-16 08:37

About this skill

soia-pkm-clip-github-repo

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

  1. State the goal in natural language and provide the necessary inputs: files, URLs, repos, workspaces, proposals, vaults, or platform account status.
  2. The Agent first determines whether this skill applies, then checks dependencies, configuration, permissions, and risky actions.
  3. 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.
  4. After execution, verify the real output; do not substitute "looks successful" for evidence.
  5. 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.md The 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_图书馆/项目卡/ and 60_开源项目/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 variable OBSIDIAN_VAULT

  • upstream location priority: command line --upstream > the private config's SOIA_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 private config.yml file, 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>

  1. parse the URL to get owner/repo
  2. there is no such repo under the upstream directory → git clone go in; if it already exists, skip the clone and directly create the card
  3. clone fails (private repository/no permission/network issue) → skip the clone, only use the URL to generate a minimal card and prompt the user
  4. call the generator's 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 it), with frontmatter carrying 关联仓库 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 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 name 10_调研笔记/ 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):

  1. What was done — one-sentence summary (single-repository archival / 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 用途、状态, "## My Notes".