Skills Hub
Skills Hub 是 Mantra「统一配置平面」的第二个支柱（与 MCP Hub 并列）。它将分散在各 AI 工具中的 Skills 集中到一处：一次导入，处处可用。
什么是 Skills Hub？
当你同时使用 Claude Code、Cursor、Codex、Gemini CLI 等多个 AI 工具时，每个工具都有各自的 Skills（技能文件）目录。相同的 Skill 需要手动复制到不同工具中，更新时也要逐个同步。
Skills Hub 解决了这个问题：将所有 Skills 集中存储在一个地方，通过 symlink（符号链接）自动分发到每个 AI 工具的目录。你只需管理一份，所有工具立刻生效。
工作原理
导入的 Skills 集中存储在 {app_data_dir}/skills/，Skills Hub 通过 symlink 将其分发到各 AI 工具的目录：
{app_data_dir}/skills/
├── my-coding-standards/ ← 真实文件存储于此
└── project-rules/
~/.claude/skills/
└── my-coding-standards → symlink ← 指向集中存储
~/.cursor/skills/
└── my-coding-standards → symlink ← 同一份文件所有工具读取到的是同一份文件——修改一处，全局生效。
跨平台支持
- Linux / macOS：使用标准 symlink
- Windows：自动降级为 junction（目录联接），无需管理员权限
扫描与导入
支持的扫描来源
Skills Hub 从三类来源发现 Skills：
四大标准工具目录
| 来源 | 用户级路径 | 项目级路径 |
|---|---|---|
| Claude Code | ~/.claude/skills/ | .claude/skills/ |
| Cursor | ~/.cursor/skills/ | .cursor/skills/ |
| Codex | ~/.codex/skills/ | .codex/skills/ |
| Gemini CLI | ~/.gemini/skills/ | .gemini/skills/ |
自定义源目录
在「设置 → 开发者设置」中维护自定义扫描目录列表，让放在任意位置的 Skills 都能被发现。详见自定义源目录。
GitHub 仓库
直接输入 GitHub 公开仓库地址，批量导入仓库中所有 SKILL.md 文件，并订阅上游更新。详见 GitHub 导入。
四档智能分类
扫描完成后，Skills Hub 将每个检测到的 Skill 分为四档：
| 分类 | 含义 | 操作 |
|---|---|---|
| 自动导入 | 全新 Skill，Hub 中不存在 | 直接导入，无需干预 |
| 自动跳过 | 与 Hub 中已有 Skill 完全相同 | 自动跳过，避免重复 |
| 需决策 | 内容有差异，存在冲突 | 查看差异并选择处理策略 |
| 异常条目 | symlink 断裂或目录不可访问 | 单独分组展示，不进入接管流程 |
多源聚合
当同一个 Skill 被多个工具目录同时引用（例如多个工具的 symlink 都指向同一真实文件），Skills Hub 将其聚合为单张卡片，避免重复信息干扰决策：
- 🔗 N 处引用：右上角徽章显示被几个工具目录引用
- 真实位置（Canonical Source）：显示文件的实际存储路径，而非 symlink 路径
- 被引用于：展开列表查看每个引用路径及其是否为 symlink
无论多少个工具都指向同一文件，导入向导只需你决策一次。
异常条目（Broken 档位）
扫描时遇到断裂 symlink（目标不存在）或目录不可访问时，对应 Skill 归入「异常条目」分组：
- 显示异常原因（断裂 symlink / 目录不可访问 / 混合异常）
- 提供诊断信息帮助你定位源 symlink 手工清理
- 不参与接管流程，不影响正常 Skill 的处理
5 步导入向导
Skills Hub 提供引导式的导入流程：
- 扫描：选择要扫描的来源（AI 工具、自定义目录或 GitHub 仓库），自动发现 Skills
- 预览：查看检测到的 Skills 和四档分类结果；同一 Skill 被多工具引用时以聚合卡片展示
- 冲突决策：对「需决策」类别的 Skills 进行差异对比，选择处理策略
- 执行：确认后执行导入（如涉及外部源清理则需二次确认），建立 symlink 分发
- 关联：将导入的 Skills 关联到相关项目
扫描进度
导入向导按来源显示扫描进度，大量 Skills 时也能清楚了解当前状态。
冲突决策
当导入候选与 Hub 中已有 Skill 内容不同时，进入冲突决策流程。
三方比较视图
当本地版和上游版都与原始版（首次接管时的快照）存在差异时，Skills Hub 打开三方比较视图：
| 栏 | 内容 |
|---|---|
| Base（原始版） | 首次接管时的内容快照 |
| Ours（本地版） | 当前 Skill 的最新内容 |
| Theirs（上游版） | 导入候选或上游更新内容 |
文件级 diff 并排展示，一眼看清每一处差异。
若本地未做修改（Base = Ours）而上游有变更，系统自动建议「覆盖」（Fast-Forward），一次确认即可完成。
三种冲突策略
| 策略 | 行为 |
|---|---|
| 覆盖 | 用上游版覆盖本地，系统自动建立快照记录 |
| 重命名 | 上游版以 {name}-2、-3… 新名称导入，本地版保持不变 |
| 跳过 | 本次不处理，记录 audit log 供事后查阅 |
首次做出选择后，可勾选「应用到本次剩余冲突」，一键批量处理剩余所有冲突项。
统一入口
工具目录扫描、自定义目录、GitHub 导入/检查上游——三个流程的冲突全部经过同一个决策入口，行为完全一致。
GitHub 仓库导入
直接从 GitHub 公开仓库批量导入 Skills，并持续订阅上游更新。
导入步骤
在导入向导中选择「从 GitHub」Tab：
- 输入仓库地址（
https://github.com/owner/repo） - 可选：指定 branch（默认
main）和 subpath（仅扫描子目录） - 点击「扫描」——Shallow clone + 自动扫描所有
SKILL.md（100 个 Skill 量级 < 30 秒） - 预览候选列表，逐项选择或全选
- 执行导入，进入标准四步原子接管流程
支持范围
当前版本仅支持 HTTPS 公开仓库（https://github.com/owner/repo）。私有仓库和 SSH 形式将在后续版本支持。
上游订阅追踪
导入后，Skills Hub 记录每个 Skill 的来源仓库和 commit SHA。在 Skill 详情页：
- metadata 区显示：
上游：{owner}/{repo}@{branch} · sha {short_sha} · 最近检查 {time} - 点击「检查上游」自动拉取最新 commit，比较内容差异：
- 内容相同：Toast 提示「已是最新」
- 内容不同：进入三方比较 + 冲突决策流程
来源识别
从 GitHub 导入时，Skills Hub 解析仓库的 remote origin（.git/config + HEAD），当多个 Skill 共享同一显示名称时，卡片副标题自动显示 host/owner/repo，让来自不同仓库的同名 Skill 一眼可辨。
名称消歧义
导入时遇到同名 Skill 不再报错——系统自动添加序号后缀，零数据丢失：
- 新名称从
{name}-2开始，依次递增直到不冲突 - 来源工具、remote origin 等元数据完整继承
- Skill 详情页展示完整的名称溯源信息
Skills 管理
管理页面
Skills Hub 提供专属的管理界面：
- 概览指标：总 Skills 数量、关联项目数、备份状态
- 标签筛选：点击标签栏快速过滤，工具品牌标签由系统自动生成
- 全文搜索（FTS）：跨 Skill 名称、描述、标签内容同时检索
- 视图切换：列表视图 / 网格视图
- 排序：支持按评分、名称、导入时间排序
- 备份摘要：可折叠的备份状态面板
标签与评分
标签
为 Skill 添加任意标签，实现灵活的分类管理：
- 标签在 Skills Hub 顶部标签栏展示，点击即可筛选
- 标签参与全文搜索，搜索时自动匹配标签内容
- 工具品牌标签（Claude / Cursor / Codex / Gemini）由系统根据来源自动生成
星级评分
为每个 Skill 打 1–5 星，追踪哪些 Skill 对你最有价值：
- 评分可作为排序维度，在列表/网格视图中按评分降序展示
- 评分数据完全本地存储，不上传云端
Skill 详情
点击任意 Skill 可查看：
- 完整的元数据（名称、来源工具、创建时间、上游仓库等）
- Skill 内容预览
- 标签和评分
- 关联的项目列表
- 版本历史（快照时间线）
- 删除影响范围预览
版本历史与快照
Skills Hub 自动追踪每个 Skill 的内容变更历史，支持随时回滚。
自动快照触发
| 触发时机 | 来源标记 | 是否永久保留 |
|---|---|---|
| 首次接管完成 | imported | 是，永不删除 |
| Skill 文件内容变化（500ms 防抖） | fs_change | 否，超出 50 条滚动删除 |
| 上游更新覆盖 | upstream_sync | 否 |
| 手动恢复操作 | restore | 否 |
同 hash 的快照内容自动去重，不重复占用磁盘空间。
快照时间线
在 Skill 详情页切到「版本历史」Tab：
| 列 | 说明 |
|---|---|
| 时间 | 快照创建时间 |
| 来源 | 来源徽章（imported / fs_change / upstream_sync / restore） |
| 大小 | 压缩后体积 |
| Hash | 内容指纹（前 8 位） |
| 操作 | 查看 Diff / 恢复 / 删除 |
回滚与恢复
点击任意快照的「恢复」按钮：
- 弹出确认对话框（"将覆盖当前文件，是否继续"）
- 确认后用该快照内容覆盖当前 Skill 目录
- 自动建一条
restore快照记录本次操作 - symlink 结构保持不变，工具目录无需重新配置
容量管理
- 单 Skill 保留最近 50 条非
imported快照，超出自动删除最旧一条 - 单 Skill 快照总量 > 100 MB 时，详情页顶部显示警告 banner 及「按时间范围批量删除」操作
- 全库累计 > 2 GB 时，Skills Hub 顶部显示全局通知
安全保障
接管备份
在导入前，Skills Hub 自动备份原始 Skill 目录。接管流程采用四步原子化操作 + 双分支回滚，确保任何步骤出现意外都能自动恢复：
- BACKUP：备份原始目录
- COPY：复制内容到集中存储（含并发修改防御）
- CLEANUP：清理旧位置（仅在安全白名单内）
- SYMLINK：建立所有工具目录的 symlink 分发
备份策略：每次接管前自动备份，保留最近 5 个版本，过期备份自动清理，恢复时校验完整性。
外部源安全警示
当 Skill 的真实内容位于工具标准目录之外时，接管操作会涉及清理外部源目录。Skills Hub 通过两级警告条提醒你：
| 警告级别 | 颜色 | 触发条件 | 含义 |
|---|---|---|---|
| 外部源警告 | 琥珀色 | 真实内容在 HOME 下但不在工具目录内 | 接管后该目录将被清理，已备份至 ~/.mantra/backups/ |
| 系统路径警告 | 红色 | 真实内容在系统路径（/etc/、/usr/ 等） | 系统目录不会被清理，Mantra 仅创建副本 |
执行接管前，若存在即将被清理的外部源目录，会弹出二次确认弹窗，要求勾选确认复选框后方可继续。
安全白名单：仅允许清理 $HOME/ 下的目录；系统路径自动拒绝清理操作。
项目关联
关联机制
Skills Hub 支持灵活的多对多项目关联：
- 用户级 Skills：自动关联所有已有项目
- 项目级 Skills：仅关联来源项目
- 可随时手动关联或取消关联任意 Skill 到任意项目
- 变更后，工具目录中的 symlink 自动同步增删
项目详情页集成
Skills 卡片（SkillContextCard）嵌入到项目详情页：
- 紧凑概览卡片：显示关联 Skill 数量、来源工具图标，及可展开的 Skill 列表
- 已关联 Skills 列表 + 快捷操作（关联 / 取消关联 / 查看详情）
- 当项目关联 5 个以上 Skill 时，出现搜索框，按名称或描述快速过滤
- Skill 卡片可跳转到关联项目，项目详情可跳回 Skills Hub（双向导航）
这与 MCP Hub 的项目集成采用对称设计，保持一致的操作体验。
反向流入检测
当你打开一个项目时，Skills Hub 会自动检测是否有 AI 工具直接创建了新的 Skill 文件（绕过了 Mantra 的管理）。如果检测到，卡片内显示橙色横幅，提供一键导入按钮，让你决定是否将其纳入统一管理。
自定义源目录
在「设置 → 开发者设置」中维护自定义扫描目录列表，让放在任意位置的 Skills 都能被 Mantra 发现。
AGENTS.md 标准目录
越来越多用户遵循 AGENTS.md 规范，将工具无关的共享 Skills 放在 ~/.agents/skills/。Mantra 将此目录作为系统级默认来源内置其中：
- 默认启用，随应用首次启动自动注册
- 可禁用（取消扫描），但不可删除
- 即使目录不存在（未安装相应工具），注册条目也会保留，扫描时自动跳过
添加自定义目录
点击「添加目录」，通过系统文件选择器选择任意目录。路径验证规则：
- 目录必须已存在
- 不允许系统敏感路径（
/etc/、/usr/、C:\Windows\等） - 不允许 HOME 内的敏感目录（
.ssh、.aws、.kube等） - 允许 HOME 之外的目录（如
/data/shared-skills/）
目录状态管理
每条记录支持：
- 启用 / 禁用：禁用后下次扫描跳过该目录
- 删除（系统级目录不可删除）
- 状态标识：目录不存在时显示红色警告图标
扫描聚合行为
自定义目录扫描出的 Skills 与标准工具目录的结果按 canonical source（真实文件位置）自动聚合：
- 若
~/.agents/skills/my-skill通过 symlink 被 Codex 引用，则聚合为单一条目（多源展示） - 自定义目录作为只读扫描源，接管后 symlink fanout 仍只写入四大标准工具目录
与 MCP Hub 的关系
Skills Hub 和 MCP Hub 共同构成 Mantra 的统一配置平面：
| 维度 | MCP Hub | Skills Hub |
|---|---|---|
| 管理对象 | MCP 服务（工具能力） | Skills（知识和规范） |
| 工作模式 | 接管 → 集中 → 分发 | 接管 → 集中 → 分发 |
| 存储位置 | SQLite 数据库 | {app_data_dir}/skills/ |
| 分发方式 | 配置文件改写 | Symlink / Junction |
| 项目关联 | 支持 | 支持 |
| 备份恢复 | 支持 | 支持 |
两者采用相同的设计模式：接管 → 集中存储 → 分发，让你在一个地方管理所有 AI 工具的配置。