Sync Organization Skills from GitHub（从 GitHub 同步组织级 skills）

背景：Skills 从"平台内手动"到"Git 工程化"

┌──────────────────────────────────────────────────────────────────────┐
│             Organization Skills — 两类形态                              │
├──────────────────────────────────────────────────────────────────────┤
│                                                                        │
│  ┌─────────────────────────┐    ┌──────────────────────────────┐     │
│  │  Hosted skills          │    │  GitHub-backed skills ⭐ v10.14│     │
│  │  ───────────────        │    │  ──────────────────────       │     │
│  │  · Gumloop 内创建        │    │  · 从 GitHub repo 导入         │     │
│  │  · AI / 上传 / 写指令    │    │  · repo 是 source of truth    │     │
│  │  · 完全可编辑            │    │  · Gumloop 内只读             │     │
│  │                         │    │  · 新 commit 自动同步          │     │
│  └─────────────────────────┘    └──────────────────────────────┘     │
│                                                                        │
│  发现规则：每个含 SKILL.md 的 folder = 一个 skill                         │
│  入口：Settings → Organization → Skills                                  │
│  Plan：Pro / Enterprise · 权限：Manage Organization Skills (Admin)        │
└──────────────────────────────────────────────────────────────────────┘

目标

1. 把 skills 纳入 Git 工作流——享受版本控制、PR review、CI 校验、code owner，与代码同生命周期
2. 自动保持最新——新 commit 自动触发同步，全员始终用最新版 skill
3. 复用 SKILL.md 跨平台标准——与 Anthropic Claude Skills 同格式，降低 skill 资产迁移成本
4. 企业级 GitOps 设计——repo 为 source of truth + 单向同步 + 完整状态机 + health 监控

2.1 连接 GitHub repo（4 步向导）

步骤	动作	细节
① Choose a repository	选 GitHub owner + repo	首次选未用过的 repo 自动为组织授权给 Gumloop GitHub App
② Choose where skills live	选 branch + 可选 folder path	folder path 留空 = 扫描整个 repo
③ Set default access	给 team 授权角色 + 设 general access	Restricted（仅所选 team）/ Organization（全公司）。⚠️ Restricted 无 team = 锁死
④ Preview and connect	预览找到多少 SKILL.md folder	确认后连接 source + 首次同步

2.2 发现规则（SKILL.md = skill）

┌──────────────────────────────────────────────────────────────────────┐
│  Skill 发现规则                                                          │
├──────────────────────────────────────────────────────────────────────┤
│  扫描范围：选定 branch + folder path                                      │
│  规则：每个含 SKILL.md 文件的 folder → 一个 organization skill             │
│                                                                        │
│  my-skills-repo/                                                        │
│  ├── skills/                                                            │
│  │   ├── draft-email/                                                   │
│  │   │   └── SKILL.md  ← 成为 "draft-email" skill                        │
│  │   ├── summarize-doc/                                                 │
│  │   │   └── SKILL.md  ← 成为 "summarize-doc" skill                      │
│  │   └── query-snowflake/                                               │
│  │       └── SKILL.md  ← 成为 "query-snowflake" skill                    │
│  └── legacy/                                                            │
│      └── notes.txt    ← 无 SKILL.md，不导入                               │
│                                                                        │
│  ⚠️ 无 SKILL.md 的 folder 不导入                                          │
└──────────────────────────────────────────────────────────────────────┘

2.3 同步机制（三态）+ 状态机

┌──────────────────────────────────────────────────────────────────────┐
│  同步触发 — 3 种                                                          │
├──────────────────────────────────────────────────────────────────────┤
│  Initial sync    连接 source 后自动跑                                     │
│  Automatic       选定 branch 上的 new commits 自动触发                    │
│  Manual          source Settings tab 的 Sync now 按需                     │
│                                                                        │
│  每次 sync：读 repo → 校验发现的 skills → 增/改/删让 Gumloop 匹配 repo      │
│                                                                        │
│  Sync 状态机：queued → scanning → staging → applying → succeeded/failed  │
└──────────────────────────────────────────────────────────────────────┘

2.4 Source health（6 态监控）

状态	含义
Healthy	最近同步成功，更新正常流动
Importing	同步正在运行
Import failed	最近同步失败——查 history 详情
Branch missing	选定 branch 在 repo 中已不存在
App access unavailable	Gumloop GitHub App 无法再访问该 repo
Webhook updates missing	自动 push 更新未收到——用 Sync now 或重连

2.5 管理 source（3 tab）+ 断开连接（Keep / Remove）

三 tab：Overview（状态/数量/最近同步/commit/default access/连接者/30 天用量）、History（同步运行记录，状态/commit/actor/时间）、Settings（Sync now / Open repository / 改 default access / Disconnect）。

Disconnect：Keep skills（转 hosted，停同步保留可用且可编辑）/ Remove skills（从组织移除）。

2.6 访问控制（per skill / bulk + 两角色）

角色	允许
Use only	可 attach 并在 agent 上使用 skill，但不能看 skill 文件
Viewer	也能查看 skill 的文件

per skill（Control Access）或 bulk（多选 Share with teams/org）。访问列标记：锁图标 = restricted（仅 team），建筑图标 = organization-wide。Default access 只对首次导入的 skill 生效（seed 每个新 skill 访问），之后可 per skill 细调。

2.7 agent 使用 + 关键限制

agent 使用：Skills 面板 → Add → Add Existing Skill → Organization section 选取；attached 后自动按需触发。

关键限制：GitHub-backed skills 在 Gumloop 内只读（改在 repo，sync 带入）；一个 source 跟踪一个 branch + 一个 folder path；新 source 不能 overlap 同 repo 已有 source 的 branch+path；无 SKILL.md 的 folder 不导入；需 Admin permission + Pro/Enterprise。

模块 A — 连接 GitHub source（4 步向导）

ID	触发场景	系统行为	优先级
A1	选 owner + repo	列出 GitHub App 可访问 repo；未用过首次自动授权	P0
A2	选 branch + folder path	branch 默认默认分支；path 空则扫全 repo	P0
A3	设 default access	team 角色 + general access（Restricted/Organization）	P0
A4	Restricted 且无 team	警告 skills 锁死，引导补访问	P1
A5	预览并连接	显示 SKILL.md folder 数；确认后连接 + 首次同步	P0

模块 B — Skill 发现与同步

ID	触发场景	系统行为	优先级
B1	扫描 branch + path	每个含 SKILL.md 的 folder → 一个 org skill	P0
B3	连接后	Initial sync 自动跑	P0
B4	branch new commits	Automatic sync 触发	P0
B5	点 Sync now	Manual sync 重导入	P0
B6/B7	每次 sync	读 repo → 校验 → 增/改/删；走状态机	P0

模块 C / D / E / F — health/管理 / 断开 / 访问 / 约束

ID	触发场景	系统行为	优先级
C1	source 状态变化	显示 6 态 health	P0
C2/C4	打开 source / Settings	三 tab；Sync now/Open repo/改 access/Disconnect	P0
D1/D2	Disconnect	Keep（转 hosted）/ Remove（移除）	P0
E1-E5	导入/per skill/bulk/attach/触发	seed 访问；Control Access；Share；Add Existing；按需触发	P0
F1	编辑 GitHub-backed skill	只读，引导改 repo	P0
F3	新 source overlap 已有	拒绝	P1
F4	无 Admin 权限 / 非 Pro/Enterprise	只能用共享的 skill，不能管理	P0