Repository navigation
Description
User need and evidence
Enterprise users syncing public GitHub skill repositories into SkillHub face a silent version-drift problem when a suite is upgraded member-by-member. When a GitHub repository containing multiple skills is synced, the skills are designed as a suite with lockstep versioning semantics (bound to the same fixed commit). However, because the current review and installation workflows operate on individual skills, a user can inadvertently install or upgrade only a subset of a suite's members, leading to broken workflows.
Evidence (project feedback):
- Issue: [Feature] 开源技能(@github)支持按仓库成套查看与整套安装 #1094 (updated 2026-11-19)
- The reporter explicitly states: "版本错位:仓库升级后逐个升级容易漏装、出现成员版本不一致,而套件语义本就要求成员版本锁步。" (Version drift: after a repository upgrades, upgrading one-by-one easily leads to missing members and inconsistent member versions, while suite semantics inherently require members to be version-locked.)
- Issue: [Feature] 审核中心支持批量审批与套件整体审批(可选:仅对 GitHub 同步来源的收窄免审) #1096 (updated 2026-11-19) reinforces the suite-level governance gap. The same 79-skill batch from 4 repos produces 79 individual review tasks, and the reporter frames this as a suite-level governance problem: "按仓库决策 4 次就够了,逐条审 79 次并没有增加任何治理信息。" (Deciding per-repo 4 times is enough; reviewing 79 items individually adds no governance value.)
- Issue: feat(github-sync): generate suite records for synced repositories to enable grouped browsing and one-command installation #1103 (updated 2026-11-19) proposes generating suite records for synced repositories, which would establish the data model. However, it does not address the runtime UX guard that prevents users from creating version drift when installing or upgrading suite members individually.
Proposed feature and tradeoffs
Proposal: Add a suite-level version consistency guard that detects and warns about version drift when a user installs, upgrades, or reviews individual members of a suite. This builds on the proposed suite records (#1103) by adding a client- and server-side validation layer that enforces lockstep semantics at the point of action.
Minimum viable scope:
- Drift detection on install/upgrade: When a user attempts to install or upgrade a single skill that belongs to a suite, check if the target version's commit hash matches the versions of already-installed suite members. If a mismatch is detected, surface a non-blocking warning:
Version drift detected: this skill is part of suite @github/owner--repo (commit abc123), but installed members are on commit def456. Consider upgrading the entire suite. - Bulk upgrade guard: On the suite detail page, if any installed member is on a different commit than the latest synced commit, show a prominent "Upgrade Suite" button with a diff summary (e.g., "3 of 5 members are on an older commit"). Clicking it upgrades all members to the pinned commit in one transaction.
- Review queue grouping (read-only): In the review center, group pending review items by their parent suite and commit. This does not change the per-item review logic (each member still gets an independent review record per [Feature] 审核中心支持批量审批与套件整体审批(可选:仅对 GitHub 同步来源的收窄免审) #1096), but it gives the reviewer visual context that these items are lockstep products.
Tradeoffs:
- Non-blocking by default: The drift warning is non-blocking to preserve the existing individual-install path. Enterprises that want strict enforcement can configure a namespace-level policy to block individual installs of suite members.
- Dependency on suite records: This feature depends on feat(github-sync): generate suite records for synced repositories to enable grouped browsing and one-command installation #1103 being merged first to establish the suite record data model. This issue only covers the drift detection and UX guard layer.
- Performance: The drift check requires comparing commit hashes across installed suite members. This is a lightweight O(n) check where n is the number of suite members (typically < 100), acceptable for a synchronous API response.
Harness and evaluation plan
Harness setup:
- Deploy a local SkillHub instance with the GitHub sync feature enabled.
- Sync a public repository with multiple skills (e.g.,
obra/superpowersormattpocock/skills) to generate a suite record. - Simulate the version-drift scenario: install 2 of 5 suite members at commit A, then sync the repository again to advance HEAD to commit B, then attempt to install a 3rd member at commit B.
Evaluation scenarios:
- Drift warning on individual install: Install suite member A at commit A, then attempt to install member B at commit B. Verify a warning is surfaced with the correct commit mismatch details.
- Bulk upgrade: With 2 of 5 members on commit A and the suite on commit B, click "Upgrade Suite" and verify all 5 members are upgraded to commit B in a single transaction.
- Review grouping: Sync a repo producing 10 pending review items. Verify they are visually grouped by suite in the review center.
- No false positives: Install all members of a suite at the same commit. Verify no drift warning is shown.
Note: This is an evaluation plan. No harness execution has been performed yet; the feature depends on #1103 being merged first.
Acceptance criteria
- Installing a single suite member whose commit differs from already-installed members surfaces a clear, non-blocking drift warning with commit hashes.
- The suite detail page shows a "Upgrade Suite" button when any installed member is on an older commit, and clicking it upgrades all members atomically.
- The review center visually groups pending items by parent suite and commit hash.
- No drift warning is shown when all installed suite members are on the same commit.
- Namespace administrators can optionally enforce a strict mode that blocks individual installs of suite members.
References
- Issue [Feature] 开源技能(@github)支持按仓库成套查看与整套安装 #1094: [Feature] 开源技能(@github)支持按仓库成套查看与整套安装 ([Feature] 开源技能(@github)支持按仓库成套查看与整套安装 #1094)
- Issue [Feature] 审核中心支持批量审批与套件整体审批(可选:仅对 GitHub 同步来源的收窄免审) #1096: [Feature] 审核中心支持批量审批与套件整体审批 ([Feature] 审核中心支持批量审批与套件整体审批(可选:仅对 GitHub 同步来源的收窄免审) #1096)
- Issue feat(github-sync): generate suite records for synced repositories to enable grouped browsing and one-command installation #1103: feat(github-sync): generate suite records for synced repositories (feat(github-sync): generate suite records for synced repositories to enable grouped browsing and one-command installation #1103)
Activity
github-actions commentedon Nov 20, 2026
Issue Triage
triage/deferredpriority/p2(2.9/5)effort/s(2/5)3/5lowrules-onlyWhy
Next Action
问题分流结果
triage/deferredpriority/p2(2.9/5)effort/s(2/5)3/5低rules-only原因
下一步