An agent skill (Codex, Claude Code, and other SKILL.md-compatible agents) that organizes the GitHub repositories you starred into stable, clear, long-term-maintainable lists.
- Inventory refresh — fetch the full starred-repo inventory and compute a delta (
newStars/removedStars) against the previous snapshot. - README corpus — download every repo's README into a local semantic review corpus with per-repo metadata stubs.
- Classification — an agent reads the READMEs (not just descriptions) and assigns repos to a reusable taxonomy; scripted recording with list-name validation.
- General-purpose taxonomy — a bundled 23-bucket taxonomy (personal software, AI/agent tooling, self-hosted services, developer infrastructure, and a fallback), extendable per workspace. A 500-repo probe and a 300-repo random sample both confirm ~90%+ reasonable placement of classifiable repos.
- Bucket overload review — when a bucket exceeds ~10% of the total star count (floor 30), the agent analyzes its contents, proposes concrete splits, and asks before creating new lists (recorded in the workspace taxonomy only).
- Cloud drift audit — read live GitHub list memberships before any writeback; deliberate live edits win, accidental ones are corrected to the ledger's intent at apply.
- Safe writeback — offline plan → online plan (review
planHash) → apply with an approved plan; unmanaged lists are preserved by default, and deleting any list requires explicit user approval.
Clone this repository into your agent's skills directory:
# Codex (Windows)
git clone https://github.com/Leexunhuan743/github-stars-curator.git "$env:USERPROFILE\.codex\skills\github-stars-curator"
# Claude Code
git clone https://github.com/Leexunhuan743/github-stars-curator.git "$env:USERPROFILE\.claude\skills\github-stars-curator"
# macOS / Linux (any SKILL.md-compatible agent)
git clone https://github.com/Leexunhuan743/github-stars-curator.git ~/.claude/skills/github-stars-curatorThe skill's nine scripts are plain Python + gh and run anywhere; SKILL.md follows the shared skill format, so agents that load SKILL.md skills (Claude Code, Cursor, Windsurf, and similar) can use it. agents/openai.yaml is Codex-specific interface metadata and is ignored by other agents.
Restart or reload your agent so the github-stars-curator skill is discovered.
- Python 3
- GitHub CLI (
gh) - authenticated
ghsession with a token scope that includesuser - PyYAML
Install PyYAML if needed:
python -m pip install pyyaml# 1. refresh the inventory and delta
python scripts/fetch_star_inventory.py --out-dir "<workspace>"
# 2. fetch READMEs (incremental: --only-new-from "<workspace>/github-stars-delta.json")
python scripts/fetch_readmes.py --inventory "<workspace>/github-stars.json" --out-dir "<workspace>/star-readmes"
# 3. (agent) read READMEs, classify, record with:
python scripts/write_classification.py --classifications records.json --inventory "<workspace>/github-stars.json" --out-dir "<workspace>" --ledger-name incremental-20260802-ledger
# 4. validate locally, then review the online plan (narrow ledger from step 3)
python scripts/apply_user_lists.py --mapping "<workspace>/star-readmes/incremental-20260802-ledger.json" --inventory "<workspace>/github-stars.json" --out-dir "<workspace>" --offline-plan
python scripts/apply_user_lists.py --mapping "<workspace>/star-readmes/incremental-20260802-ledger.json" --inventory "<workspace>/github-stars.json" --out-dir "<workspace>"
# 5. apply the reviewed plan
python scripts/apply_user_lists.py --mapping "<workspace>/star-readmes/incremental-20260802-ledger.json" --inventory "<workspace>/github-stars.json" --out-dir "<workspace>" --apply --approved-plan "<workspace>/github-stars-sync-plan.json"
# 6. merge the narrow ledger back into the full record (snapshots first)
python scripts/write_classification.py --classifications records.json --inventory "<workspace>/github-stars.json" --out-dir "<workspace>" --ledger-name incremental-20260802-ledger --merge-into-full "<workspace>/star-readmes/complete-ledger.json"fetch_star_inventory.py— fetch stars and compute the delta (github-stars.json,github-stars-delta.json,github-stars-summary.json).fetch_readmes.py— download READMEs intostar-readmes/raw/and merge per-repo metadata stubs.split_manifest.py— split the inventory into balanced batches for parallel subagent classification.merge_classifications.py— validate and merge per-batch classification results (JSON-integrity, 1:1 coverage, list-name whitelist, cross-batch duplicates).write_classification.py— record agent classifications into meta files and emit a ledger; validates list names against the taxonomy;--merge-into-fullmerges a narrow ledger back into the full record with a snapshot, and--prune-removeddrops unstarred repos from it.reclassify_bucket.py— apply an adopted bucket split from a{repo: [new lists]}mapping through the same validation and snapshot-and-merge path aswrite_classification.py --merge-into-full.init_taxonomy.py— copy the bundled taxonomy template to<workspace>/taxonomy.yaml(refuses to overwrite an existing workspace copy).audit_cloud_drift.py— read-only live-vs-ledger drift audit before writeback; exit code 0 = no drift or only expected pre-synclocalNotLivedrift, non-zero =liveNotLocalreconcile signal.apply_user_lists.py— offline plan / online plan / apply (creates missing lists in taxonomy order, updates descriptions and memberships, writes an audit journal);--retry Nretries transient network errors per mutation.
The bundled references/taxonomy-template.yaml defines 23 buckets: downloaders, cloud-drive-transfer-sync, clipboard-tools, media-players, agent-tools, ai-agents, dev-tools, terminal, windows-tools, desktop-apps, reading-notes, pdf-document-tools, references-guides, self-hosted, cloudflare-network-proxy, frameworks-libraries, data-ml-tools, game-3d-creative, design-assets, business-apps, web-scraping-data-collection, security-pentest-tools, everything-else.
A workspace can extend it by copying the template to <workspace>/taxonomy.yaml and adding lists there (e.g. video-downloaders, agent-skills were added this way after a bucket overload review). The 32-list GitHub cap is enforced at plan time.
- Plan, review, then mutate. Every writeback goes through offline plan → online plan (review
planHash) → apply with--approved-plan; a tampered or stale plan is refused. - Deliberate live edits win; accidents don't. Cloud drift is checked proactively before writeback; deliberate manual cloud edits are preserved (local ledgers never silently overwrite them), while unintentional cloud discrepancies are corrected back to the ledger's intent at apply.
- Unmanaged lists are preserved by default. Lists outside the loaded taxonomy are left alone; when they are discovered, the user is asked whether to delete them, and deletion happens only with explicit approval.
- Unexpected removals stop the flow. Any
listsToRemoveoutside the current request is a pause-and-review signal. - Human checkpoints. Bucket overload, taxonomy drift, single-repo new lists, and auth gaps all pause for review.
cd scripts
python -m pytest tests/ -q49 tests cover meta merging, incremental corpus preservation, ledger validation, plan-hash integrity, drift audit semantics, classification recording, batch split/merge, network retry, bucket reclassification, taxonomy initialization, cache archiving, delta backup on redundant runs, and propagation chain consistency — all offline (GitHub calls are mocked).
See SKILL.md for the agent-facing operating instructions.
这是一个 Agent 技能(兼容 Codex、Claude Code 等),用来把你 star/收藏 的 GitHub 仓库整理成稳定、清晰、可长期维护的列表。
- 清单刷新:拉取全部 star,计算与上次快照的增量(新增/移除);
- README 语料:下载所有 repo 的 README 到本地,形成语义审阅语料;
- 分类:agent 读 README(不是只看描述)把 repo 归入可复用 taxonomy,脚本化记录并校验列表名;
- 通用 taxonomy:内置 23 桶(个人软件、AI/agent 工具、自托管服务、开发者基础设施、兜底桶),可按工作区扩展;500 个样本压力测试 + 300 个随机样本实测可判定仓库归位率 ~90%+;
- 桶超载审查:某桶超过总 star 数约 10%(下限 30)时,agent 分析内容、提出拆分方案、询问后再建新列表(只记入工作区 taxonomy);
- 云漂移审计:写回前读取云端 live 成员关系,与本地 ledger 不一致时以 live 为准;
- 安全写回:离线计划 → 在线计划(审阅 planHash)→ 凭批准计划 apply;unmanaged 列表默认保留,删除任何列表必须经用户明确同意。
把仓库 clone 到你所用 agent 的 skills 目录:
# Codex (Windows)
git clone https://github.com/Leexunhuan743/github-stars-curator.git "$env:USERPROFILE\.codex\skills\github-stars-curator"
# Claude Code
git clone https://github.com/Leexunhuan743/github-stars-curator.git "$env:USERPROFILE\.claude\skills\github-stars-curator"
# macOS / Linux(任何兼容 SKILL.md 的 agent)
git clone https://github.com/Leexunhuan743/github-stars-curator.git ~/.claude/skills/github-stars-curator9 个脚本是纯 Python + gh,与平台无关;SKILL.md 采用通用 skill 格式,因此 Claude Code、Cursor、Windsurf 等加载 SKILL.md 的 agent 都能使用。agents/openai.yaml 是 Codex 特有的接口元数据,其他 agent 会忽略它。
重启或重新加载 agent,让 github-stars-curator 被发现。
- Python 3
- GitHub CLI:
gh(已登录,token scope 含user) - PyYAML
python -m pip install pyyaml# 1. 刷新清单与增量
python scripts/fetch_star_inventory.py --out-dir "<workspace>"
# 2. 抓 README(增量用 --only-new-from "<workspace>/github-stars-delta.json")
python scripts/fetch_readmes.py --inventory "<workspace>/github-stars.json" --out-dir "<workspace>/star-readmes"
# 3. (agent)读 README 分类后用脚本记录
python scripts/write_classification.py --classifications records.json --inventory "<workspace>/github-stars.json" --out-dir "<workspace>" --ledger-name incremental-20260802-ledger
# 4. 离线计划 → 在线计划(审阅 planHash;mapping 用第 3 步的窄 ledger)
python scripts/apply_user_lists.py --mapping "<workspace>/star-readmes/incremental-20260802-ledger.json" --inventory "<workspace>/github-stars.json" --out-dir "<workspace>" --offline-plan
python scripts/apply_user_lists.py --mapping "<workspace>/star-readmes/incremental-20260802-ledger.json" --inventory "<workspace>/github-stars.json" --out-dir "<workspace>"
# 5. 凭批准计划写回
python scripts/apply_user_lists.py --mapping "<workspace>/star-readmes/incremental-20260802-ledger.json" --inventory "<workspace>/github-stars.json" --out-dir "<workspace>" --apply --approved-plan "<workspace>/github-stars-sync-plan.json"
# 6. 把窄 ledger 合并回完整记录(先快照)
python scripts/write_classification.py --classifications records.json --inventory "<workspace>/github-stars.json" --out-dir "<workspace>" --ledger-name incremental-20260802-ledger --merge-into-full "<workspace>/star-readmes/complete-ledger.json"fetch_star_inventory.py:拉取清单并算增量(github-stars.json / delta / summary);fetch_readmes.py:下载 README 语料并合并 meta 元数据;split_manifest.py:把清单切成均衡批次,供并行子代理分类;merge_classifications.py:校验并合并各批分类结果(JSON 完整性、1:1 覆盖、列表名白名单、跨批重复);write_classification.py:记录分类到 meta 并生成 ledger,校验列表名;--merge-into-full把窄增量合并回完整 ledger(先快照),--prune-removed从中剔除已取消 star 的仓库;reclassify_bucket.py:按{repo: [新列表]}映射应用桶拆分,走与write_classification.py --merge-into-full相同的校验与快照合并路径;init_taxonomy.py:把内置模板复制到<workspace>/taxonomy.yaml(已存在时不覆盖);audit_cloud_drift.py:写回前只读漂移审计(exit 0 = 无漂移或仅预期的 pre-synclocalNotLive漂移,非零 =liveNotLocal需协调信号);apply_user_lists.py:离线/在线计划与 apply(按 taxonomy 顺序创建缺失列表、更新描述与成员、写审计 journal);--retry N每次变更自动重试瞬时网络错误。
内置 references/taxonomy-template.yaml 23 桶:downloaders、cloud-drive-transfer-sync、clipboard-tools、media-players、agent-tools、ai-agents、dev-tools、terminal、windows-tools、desktop-apps、reading-notes、pdf-document-tools、references-guides、self-hosted、cloudflare-network-proxy、frameworks-libraries、data-ml-tools、game-3d-creative、design-assets、business-apps、web-scraping-data-collection、security-pentest-tools、everything-else。
需要自定义时用 python scripts/init_taxonomy.py --out-dir "<workspace>" 把模板复制到 <workspace>/taxonomy.yaml 再编辑(例如 video-downloaders、agent-skills 就是经桶超载审查后这样加的)。32 列表上限在计划阶段强制校验。
- 先计划、再审阅、后写回:离线计划 → 在线计划(审阅 planHash)→ 凭
--approved-planapply;篡改或过期的计划会被拒绝; - 有意的 live 修改优先,误操作不优先:写回前主动查云漂移;用户有意的云端手动修改被保留(本地 ledger 绝不静默覆盖),而无意的云端差异在 apply 时按 ledger 意图纠正;
- unmanaged 列表默认保留:taxonomy 之外的云端列表不碰;发现时询问用户是否删除,删除仅凭明确同意;
- 意外移除即暂停:请求之外的任何
listsToRemove都是停止复查信号; - 人工检查点:桶超载、taxonomy 漂移、单 repo 新列表、鉴权不足都会暂停。
cd scripts
python -m pytest tests/ -q49 个测试覆盖 meta 合并、增量语料保留、ledger 校验、planHash 完整性、漂移审计语义、分类记录、批次切分/合并、网络重试、桶重分类、taxonomy 初始化、缓存归档、重复运行增量备份与传播链一致性——全部离线(GitHub 调用被 mock)。
详细的 agent 操作规程见 SKILL.md。