XSkill's 用户指南

一个用于发现、安装和管理可复用 agent 技能包的技能管理工具，支持多种 AI 编程平台。

特性

• 多源支持：从 Git 仓库、GitHub、GitLab 及任何 Git 兼容主机安装技能
• 平台管理：一条命令将技能安装到多个 AI 编程平台（Claude、Codex 等）
• 锁文件追踪：通过 .xskill-lock.json 追踪已安装技能，确保可复现安装
• 全局配置：单一全局配置文件 ~/.xskill/settings.json，支持 XSKILL_CONFIG 环境变量覆盖
• 递归搜索：自动发现仓库中嵌套目录结构下的技能。优先扫描 skills/ 子目录，若不存在则回退到项目根目录扫描。以 . 开头的目录（如 .git、.agents）会被排除。
• 批量操作：使用 --all 标志或 * 通配符安装或移除所有技能
• 缓存支持：可选的本地缓存，实现无网络访问的快速技能查询
• 交互式 TUI：通过 find 命令模糊搜索并交互式安装技能
• 跨平台：支持 Windows、macOS 和 Linux

安装

快速安装

Linux / macOS：

curl -fsSL https://xskill.gcli.cn/install.sh | bash

脚本自动检测操作系统和架构，从 GitHub Releases 下载对应的预编译二进制文件，安装到 ~/.local/bin（root 用户安装到 /usr/local/bin）。支持中国网络 CDN 加速。

Windows（PowerShell）：

irm https://xskill.gcli.cn/install.ps1 | iex

自动检测架构，从 GitHub Releases 下载，安装到 %USERPROFILE%\.local\bin（管理员安装到 %ProgramFiles%\xskill\bin）。若安装路径不在 PATH 中，脚本会提示你添加。

从 npm 安装

npm install -g @jetsung/xskill

从 crates.io 安装

cargo install xskill

从 Git 安装

cargo install --git https://github.com/jetsung/xskill.git xskill

或从 AtomGit 安装（国内用户）：

cargo install --git https://atomgit.com/jetsung/xskill.git xskill

从源码安装

git clone https://github.com/jetsung/xskill.git
cd xskill
cargo install --path .

环境要求

• Rust 1.70+
• Git（需在 PATH 中可用）

预编译二进制

GitHub Releases 页面提供 Linux、macOS 和 Windows 的预编译二进制文件。

快速开始

1. 配置源

添加技能仓库作为源：

xskill sources add -n my-skills -u https://github.com/example/skills

或让名称从 URL 自动提取：

xskill sources add -u https://github.com/user/repo.git
# 名称自动设为 "user/repo"

2. 查询可用技能

列出源中的技能：

xskill query -f my-skills

查询特定技能：

xskill query -f my-skills -s vue

3. 安装技能

安装到项目级 .agents/ 目录：

xskill add -f my-skills -s vue

安装到全局 ~/.agents/ 目录：

xskill add -f my-skills -s vue -g

4. 列出已安装技能

xskill list

5. 移除技能

xskill remove -s vue

全局选项

以下选项可在任何子命令之前使用：

示例：

# 调试模式 — 查看 git clone 详情
xskill -v add -f my-skills -s vue

# 调试模式 + 全局安装
xskill -v add -f my-skills -s vue -g

命令

sources — 管理配置源

列出、添加、移除或重命名配置中的技能源。

sources list

列出所有已配置的源：

xskill sources
# 或显式调用：
xskill sources list

输出格式：

#  NAME   TYPE URL
1  antfu  git  https://github.com/antfu/skills

sources add

添加新源：

xskill sources add -n <name> -u <url> [-t git|api]

选项：

• -n, --name — 源名称（可选，仅允许字母数字、-、_ 和 /，支持 user/repo 格式；未指定时自动从 URL 提取路径作为默认名称，如 https://github.com/user/repo.git → user/repo）
• -u, --url — 源地址（必填，须以 http:// 或 https:// 开头）
• -t, --type — 源类型：git 或 api（默认：git）

示例：

# 显式指定名称
xskill sources add -n my-skills -u https://github.com/example/skills

# 名称自动提取为 "user/repo"
xskill sources add -u https://github.com/user/repo.git

# 斜杠分隔的名称
xskill sources add -n org/team/repo -u https://gitlab.com/org/team/repo

sources remove

按名称、URL 或索引移除源：

xskill sources remove -n <name>
xskill sources remove -u <url>
xskill sources remove -n <name> -u <url>
xskill sources remove -i <index>

选项：

• -n, --name — 要移除的源名称（可选）
• -u, --url — 要移除的源地址（可选）
• -i, --index — 源索引，来自 sources list 的 # 列（可选，从 1 开始）

优先级：--name/--url > --index。至少需指定 --name、--url 或 --index 之一。同时指定 --name 和 --url 时两者都匹配才删除。

sources rename

重命名已有源（仅允许修改名称，url 和 type 不可变更）：

xskill sources rename -n <name> -N <new-name>
xskill sources rename -i <index> -N <new-name>

选项：

• -n, --name — 当前源名称（或使用 -u 按 URL 匹配）
• -u, --url — 当前源地址（替代标识符）
• -i, --index — 源索引，来自 sources list 的 # 列（可选，从 1 开始）
• -N, --new-name — 新名称（必填，传空字符串清空名称）

优先级：--name/--url > --index。至少需指定 --name、--url 或 --index 之一。

platforms — 管理配置平台

列出或重置所有已配置的 AI 编程平台。

platforms list

列出已配置的平台。默认只显示启用（enabled: true）的渠道,按显示名称排序;NAME 列为渠道显示名称（缺失时回退到配置 key）:

xskill platforms list

裸命令 xskill platforms 等同于 xskill platforms list。

默认输出格式（NAME、PATH、COMPAT 三列）:

NAME         PATH      COMPAT
Claude Code  .claude   ✗
Codex        .codex    ✓

✓ 绿色表示兼容（agents_compat: true），✗ 红色表示不兼容，便于肉眼区分。

显示详细平台信息,包含禁用渠道及其 ENABLED 状态（NAME、PATH、SKILLS、AGENTS、SOURCE、COMPAT、ENABLED 七列）:

xskill platforms list -a

输出格式:

NAME         PATH     SKILLS  AGENTS      SOURCE     COMPAT  ENABLED
Claude Code  .claude  skills  CLAUDE.md   AGENTS.md  ✗       ✓
Codex        .codex   skills  AGENTS.md   AGENTS.md  ✓       ✓
Cline        .cline   skills  CLAUDE.md   AGENTS.md  ✓       ✗

只显示已启用渠道的详细信息(隐藏禁用渠道):

xskill platforms list -e

选项：

• -a, --all — 显示详细信息（路径、技能目录、代理文件、源文件、agents 兼容性和启用状态），包含全部渠道（含禁用）
• -e, --enabled — 详细视图仅显示已启用（enabled: true）的渠道；与 -a 同时指定时按启用过滤优先

兼容平台（agents_compat: true）会在 add、link 等命令的交互式目标平台选择器中自动预选。

platforms reset

将 platforms 重置为内置默认平台列表，执行前弹出 skim 单选 TUI（↑/↓ 选择，Enter 确认，Esc 取消，回车默认选中第一项）：

• 完全恢复（第一项，默认）— 所有平台恢复内置默认配置，移除自定义平台
• 谨慎合并 — 只更新内置平台，自定义平台保留
• 取消 — 不修改任何配置

若存在自定义平台，会先打印提示。其他配置字段（sources、cache、proxy 等）不受影响。

示例：

$ xskill platforms reset
Custom platforms: my-custom
# skim TUI: 完全恢复(默认) / 谨慎合并 / 取消
Platforms reset: 18 platforms, replaced with defaults (custom dropped)

边界情况：

• 未配置任何平台时输出 “No platforms configured”。
• 空字段显示 -。

add — 安装技能

从源安装技能到目标目录。

xskill add [OPTIONS] --from <SOURCE> --skill <SKILL>

选项：

• -f, --from <SOURCE> — 源名称、ORG/REPO 或 Git URL
• -s, --skill <SKILL> — 技能名称（使用 '*' 表示所有技能）
• -g, --global — 安装到全局 ~/.agents/ 目录
• -a, --agent <AGENT> — 目标平台（使用 '*' 表示所有平台）
• -A, --all — --skill '*' --agent '*' 的简写（需配合 --from）

安装目标

源信息显示

安装前会输出源信息：Source: <source-name> (<source-url>)（标签 cyan bold）。

多源同名技能选择

当未指定 -f 且多个源（含注册中心）包含同名技能时：

• 交互终端：弹出 skim 单选 TUI，三列对齐显示：[registry] / -（第一列，注册中心条目显示 [registry]，本地源显示 -）、source_name、url。注册中心 source_name 为空或与本地源冲突时显示 -。
• 非交互终端：报错并列出所有匹配源（含 URL），提示使用 xskill add -f <source> -s <skill>。

输出样式

标签（Name、Description、Version、Path）使用 cyan bold 显示。Name 值使用黄色显示。Description 或 Version 为空时不显示该行。

• Path（cyan bold）：技能在仓库中的完整路径（如 skills/vue/SKILL.md）。
• Installed（green）：规范目录路径。
• Symlinked（green）：平台目录路径（不显示箭头和目标，因 Installed 行已展示规范目录）。
• Source（cyan bold）：Source: <name> (<url>)。

示例

# 安装到项目
xskill add -f antfu -s vue

# 安装到全局
xskill add -f antfu -s vue -g

# 安装到特定平台
xskill add -f antfu -s vue -a claude

# 安装到所有平台
xskill add -f antfu -s vue -a '*'

# 安装源中所有技能
xskill add -f antfu -s '*'

# 安装到所有位置
xskill add -f antfu -A

link — 软链接已有技能到平台

将规范目录中已存在的 skill 软链接到指定平台目录。与 add 不同，link 不会从远程源下载或安装任何 skill，仅操作本地已有的 skill。

xskill link [OPTIONS] --skill <SKILL> --agent <AGENT>

选项：

• -s, --skill <SKILL> — 技能名称（使用 '*' 表示所有技能）
• -a, --agent <AGENT> — 目标平台（使用 '*' 表示所有平台）
• -g, --global — 操作全局 ~/.agents/skills/ 目录
• -A, --all — --skill '*' --agent '*' 的简写

链接行为

关键规则

• link 不需要 -f 参数（不涉及远程源）。
• 不更新锁文件：skill 已由 add 命令安装并写入锁文件，link 仅创建 symlink。
• 规范目录中的 skill 必须已存在（包含 SKILL.md），否则报错。
• -s '*' 时扫描规范目录中所有包含 SKILL.md 的子目录。
• 软链接使用相对路径，规则与 add 命令一致。
• symlink 创建失败时回退为文件复制。

agents_compat 兼容

agents_compat: true 的平台会被跳过（直接读取规范目录）。单平台指定时输出 Skipped: <name> (agents_compat)（暗灰色）；-a '*' 时静默跳过并汇总输出。

示例

# 将单个 skill 链接到特定平台
xskill link -s vue -a claude

# 将所有已有 skill 链接到某个平台
xskill link -s '*' -a claude

# 将 skill 链接到所有平台
xskill link -s vue -a '*'

# 链接所有 skill 到所有平台
xskill link -A

# 全局模式
xskill link -s vue -a claude -g

remove — 移除技能

移除已安装的技能并更新锁文件。

xskill remove [OPTIONS] --skill <SKILL>

选项：

• -s, --skill <SKILL> — 技能名称（使用 '*' 表示所有技能）
• -g, --global — 从全局目录移除
• -a, --agent <AGENT> — 目标平台（使用 '*' 表示所有平台）
• -A, --all — --skill '*' --agent '*' 的简写

update — 更新已安装技能

根据锁文件记录重新安装技能，保留原始 installed_at 时间戳。

xskill update [OPTIONS]

选项：

• -g, --global — 仅更新全局技能
• -s, --skill <SKILL> — 技能名称（使用 '*' 表示所有技能）

输出样式：标签（Source、Updating、Name、Description、Version、Updated）使用 cyan 显示，Name 值使用黄色。

restore — 从锁文件恢复技能

读取当前目录下的 .xskill-lock.json，安装所有已记录的技能。适用于新环境搭建或克隆项目后快速恢复技能。恢复时按 source_url 分组，同一仓库仅克隆一次，避免重复 git 操作。

xskill restore [OPTIONS]

选项：

• -g, --global — 安装到全局 ~/.agents/skills/ 目录（默认：项目级 .agents/skills/）
• -a, --agent <AGENT> — 目标平台（使用 '*' 表示所有平台）
• -D, --dry-run — 预览模式：列出将要恢复的技能，不执行安装

安装目标

示例

# 恢复所有技能到项目
xskill restore

# 恢复到全局目录
xskill restore --global

# 恢复到特定平台
xskill restore --agent claude

# 预览将要恢复的内容
xskill restore --dry-run

输出格式：

Restoring: vue
  Source: https://github.com/antfu/skills.git
  Target: .agents/skills/vue
  Name: Vue
  Description: Vue.js 技能包

Restore complete: 3 succeeded, 0 failed

Dry-run 输出（按技能名称分组，避免重复）：

Skills to restore:

NAME   SOURCE                                      TARGET
vue    https://github.com/antfu/skills.git         .claude/skills/vue
                                                    .codex/skills/vue
react  https://github.com/antfu/skills.git         .claude/skills/react
                                                    .codex/skills/react

颜色规则：多目标（-a '*' 或多个平台）时表头蓝色、续行 TARGET 黑灰色。单目标（-a <name>）时无颜色。

list — 列出已安装技能

以对齐列格式显示已安装的技能。

xskill list [OPTIONS]

选项：

• -g, --global — 列出全局技能
• -a, --agent <AGENT> — 只列出指定平台实际可用的技能；agents_compat 平台合并列出规范目录与其自身 skills 目录下的技能；不支持 *

输出格式（不带 -a）：

Project Skills

vue     ~/.agents/skills/vue     Agents: codebuddy, gemini
react   ~/.agents/skills/react   Agents: codebuddy

指定 -a <agent> 时（例如 -a claude，仅列出该平台实际可用的技能，无 Agents: 列）：

Project Skills

vue     ~/.claude/skills/vue
react   ~/.claude/skills/react

• 技能名称显示为黄色，路径显示为暗灰色（使用 ~/ 前缀替代 home 目录）。
• Agents: 前缀为黑灰色，平台名为默认白色（仅不带 -a 时显示）。
• agents_compat 平台（如 atomcode）合并列出规范目录（.agents/skills）与其自身 skills 目录下的技能，同名技能仅显示一次（规范目录优先）。
• -a '*' 不受支持：不加 -a 即为列出全部技能。
• 按路径字母顺序排序。

query — 查询源中的技能

从已配置或远程源查询或列出技能。

xskill query [OPTIONS]

选项：

• -f, --from <SOURCE> — 源名称、ORG/REPO 或 Git URL
• -s, --skill <SKILL> — 特定技能名称（必填，不支持通配符 *）

当 cache.enabled 为 true 时，查询从本地缓存读取，而非从远程源获取。当 registry.enabled 为 true 且未指定 --from 时，还会额外查询注册中心。

输出样式：标签（Source、Registry、Name、Description、Version、Path）使用 cyan bold 显示，Name 值使用黄色。Source 为空时显示 -。Description 或 Version 为空时不显示该行。各技能之间以空行分隔。

当未找到技能但已配置源且 cache.enabled 为 true 时，显示提示：Hint: run 'xskill cache update' to refresh skills cache（cyan）。

find — 交互式查找并安装技能

启动多步交互式 TUI，支持多选批量安装技能。同源技能仅 clone 一次仓库，避免重复拉取。

xskill find [OPTIONS]

选项：

• -f, --from <SOURCE> — 按源名称或 URL 过滤技能
• -s, --skill <QUERY> — 预填充过滤查询
• -g, --global — 安装到全局 ~/.agents/ 目录（默认：项目级 .agents/）

工作流程

1. 选择技能 — 多选子串搜索（exact 模式）。显示格式：name [source]（注册中心条目显示 name [registry] [source]）。非选中行技能名称使用默认色，选中行使用蓝色。source 标签始终暗灰色；[registry] 标签选中时变为绿色。搜索框在底部，列表向上排列。快捷键提示：TAB: multi-select | enter confirm | esc cancel。按 TAB 多选技能，Enter 确认。未 TAB 选中时直接 Enter，使用光标所在项。
2. 选择目标平台 — TUI 多选。首项为 Default（不可选中，表示不创建平台符号链接）。agents_compat 平台不在可选列表中，以 SELECTED: <platform1>, <platform2>, ... 形式显示在 header 中。后续为非兼容的配置平台。按 TAB 选择/取消选择，Enter 确认。选中行使用蓝色文字和深色背景高亮。
3. 安装 — 按 source URL 分组，每组仅 clone 一次仓库。从 CachedSkill.path 提取正确安装路径（支持嵌套路径，如 skills/engineering/grill/SKILL.md，或根目录级别的 my-skill/SKILL.md）。安装到规范目录（.agents/skills/<name> 或 -g 时 ~/.agents/skills/<name>），然后为每个选中的平台创建相对符号链接。输出 Installed:、Symlinked: 和失败的平台（如有）。各技能输出之间以空行分隔。注册中心的技能直接使用 URL 克隆，不依赖本地 sources 配置。

任意步骤按 Esc 或 Ctrl-C 取消。

已知问题：skim 库的列表行号从 0 开始（skim 5.2.0 行为），非本项目可控。

示例

# 打开交互式查找器
xskill find

# 预过滤匹配 "git" 的技能
xskill find --skill git

# 从指定源查找
xskill find --from antfu

# 从 URL 查找（自动缓存 10 分钟）
xskill find --from https://github.com/example/skills

注意： 需要已填充的缓存。如尚未更新缓存，请先运行 xskill cache update。使用 URL 方式的 --from 时，技能列表会自动拉取并缓存。

rec — 管理推荐技能

管理推荐技能源，支持列表、添加和移除操作。

xskill rec <COMMAND>

rec list

列出所有推荐源：

xskill rec list

输出格式：

SOURCE  NAME   URL                                  SKILLS
true    antfu  https://github.com/antfu/skills       vue, react
false   foo    invalid                              bar

• SOURCE 列：true 表示该推荐源的名称存在于 sources 配置中且 URL 一致，false 表示不匹配。
• URL 在名称存在于 sources 但 URL 不匹配时显示 invalid（红色）。

rec add

向推荐源添加技能。若条目已存在，新技能将被追加（自动去重）。

xskill rec add [-n <name>] [-u <url>] -s <skills>

选项：

• -n, --name — 源名称（若未提供 --url，则必须存在于 sources 中）
• -u, --url — 源地址（当 name 存在于 sources 中且 url 匹配时，仅保存 name）
• -s, --skills — 逗号分隔的技能名称列表（必填）

参数组合逻辑：

• 仅 -n 和 -s：验证 -n 存在于 sources 中，保存 name + skills
• -n、-u 和 -s：
  • 若 -n 存在于 sources 中且 url 与 -u 匹配：仅保存 name + skills（无需 url）
  • 若 -n 存在于 sources 中但 url 与 -u 不匹配：报错
  • 若 -n 不存在于 sources 中：使用 url + skills 保存（name 为 url 值）
• 仅 -u 和 -s：使用 url + skills 保存

追加行为：若条目 “antfu” 已有技能 vue，执行 rec add -n antfu -s react,angular 后结果为 vue,react,angular。

rec remove

移除推荐源或特定技能：

xskill rec remove [-n <name>] [-u <url>] [-s <skills>]

选项：

• -n, --name — 源名称（用于标识条目，或与 -u/-s 配合使用）
• -u, --url — 源地址（当同时指定 -n 和 -u 时，优先以 -u 为准）
• -s, --skills — 逗号分隔的技能名称列表（移除特定技能而非整个条目）

优先级逻辑：

• 同时指定 -n 和 -u：优先按 -u 查找，若未找到则回退到 -n
• 仅指定 -n：删除对应名称的整条数据
• 指定 -n 和 -s：删除该名称下对应的技能
• 指定 -u 和 -s：删除该 URL 下对应的技能

cache — 管理技能缓存

管理本地技能缓存，支持离线查询。

xskill cache <COMMAND>

cache update

从远程源获取技能列表并保存到缓存：

xskill cache update [-f <source>]

选项：

• -f, --from <source> — 仅更新特定源（名称或 URL）

每个源的输出：<源名称>: <数量> skills。汇总：Cache updated: N sources, M skills total。

cache clear

清除缓存的技能数据：

xskill cache clear [-f <source>]

选项：

• -f, --from <source> — 仅清除特定源（名称或 URL）

config — 管理配置

查看或修改全局配置文件。

xskill config [OPTIONS]

选项：

• -i, --init — 初始化配置文件，生成含默认值的完整配置（默认平台、缓存、注册中心）
• -e, --edit — 在 $EDITOR 中打开配置（默认 vi）
• -g, --get <key> — 通过点号路径获取配置值（如 cache.enabled）
• -s, --set <key=value> — 通过点号路径设置配置值（如 cache.enabled=true）
• -w, --show — 以美化后的 JSON 打印当前加载的完整配置（合并默认值，如补全缺失的平台）。输出无颜色，便于管道处理
• -V, --validate — 校验配置文件。先做 JSON 语法与强类型结构校验，再对照 JSON Schema 做完整 Schema 校验。优先查找本地 Schema（$XSKILL_SCHEMA、<config_dir>/schemas/xskill.schema.json、从可执行文件目录向上查找、<exe_dir>/../share/xskill/xskill.schema.json）；本地均无则从 https://xskill.gcli.cn/xskill.schema.json 拉取（遵循代理配置）。成功输出 Valid <path> (schema: <source>)，失败打印每条错误（含 JSON 路径）并以 1 退出

示例 — 读取/设置代理：

xskill config --get proxy
xskill config --set proxy=socks5h://127.0.0.1:40027
xskill config --validate

示例

# 初始化配置文件
xskill config --init

# 在编辑器中打开配置
xskill config --edit

# 读取值
xskill config --get cache.enabled

# 设置值
xskill config --set cache.enabled=true

new — 创建技能项目

使用模板创建新的技能项目。

xskill new --name <name> [--description <desc>] [--template <template>]

选项：

• -n, --name <name> — 技能名称（必填，用作目录名）
• -d, --description <desc> — 技能描述
• -t, --template <template> — 模板类型

配置

配置文件位置

没有项目级配置，仅使用一个全局配置文件。

配置结构

{
  "$schema": "https://xskill.gcli.cn/xskill.schema.json",
  "platforms": { ... },
  "sources": [ ... ],
  "recommended": [ ... ],
  "cache": { ... },
  "registry": { ... }
}

完整示例

{
  "$schema": "https://xskill.gcli.cn/xskill.schema.json",
  "platforms": {
    "claude": {
      "path": ".claude",
      "skills": "skills",
      "agents": "CLAUDE.md",
      "agents_compat": false
    },
    "codex": {
      "path": ".codex",
      "skills": "skills",
      "agents": "AGENTS.md",
      "agents_compat": true
    },
    "pi": {
      "path": ".pi/agent",
      "skills": "skills",
      "agents": "AGENTS.md",
      "agents_compat": true
    }
  },
  "sources": [
    {
      "name": "antfu",
      "type": "git",
      "url": "https://github.com/antfu/skills"
    },
    {
      "name": "mattpocock",
      "url": "https://github.com/mattpocock/skills"
    }
  ],
  "recommended": [
    {
      "name": "antfu",
      "skills": ["vue", "react"]
    }
  ],
  "cache": {
    "enabled": true,
    "ttl": 600
  },
  "registry": {
    "enabled": false,
    "url": "https://xskill.gcli.cn/skills.json"
  },
  "proxy": ""
}

平台

每个平台条目配置特定 AI 编程工具的技能安装方式。

平台字段

符号链接行为

agents 文件通过符号链接指向 .agents/ 下的源文件：

<path>/<agents>  →  .agents/<source>

例如，agents: "AGENTS.md" 且 source: "AGENTS.md"（默认）：

.codex/AGENTS.md  →  .agents/AGENTS.md

agents: "AGENTS.md" 且 source: "CLAUDE.md"：

.codex/AGENTS.md  →  .agents/CLAUDE.md

源

源定义技能的获取位置。

推荐

推荐技能由 rec 命令管理，方便安装。

缓存

启用后，xskill cache update 从所有源获取技能元数据并存储在本地。后续 query 和 find 命令根据 cache.ttl 检查缓存是否过期：未过期直接读取缓存；过期或缓存为空但有配置源时，自动重新克隆并回写 skills.json。

注册中心

注册中心是一个可选的 JSON API，提供精选的技能索引。启用后，query 和 find 命令会在查询配置源的同时额外查询注册中心。

URL 解析规则：

• 裸域名或以 / 结尾 → 自动补全 /skills.json
• 路径末尾含文件扩展名（如 .json）→ 原样使用
• 空值或无效协议 → 回退内置默认地址

去重规则（URL 归一化后比较，本地优先）：

• 注册中心源的 URL 与已配置源的 URL 相同 → 跳过（以本地配置为准）。
• 注册中心源与已配置源同名但 URL 不同 → 视为两个不同仓库，注册中心条目正常合并。query 中注册中心条目的源名称置空（显示为 -），find 中显示为该源的 URL。
• 无冲突 → 正常显示。
• Skill 级去重：仅在 URL 相同时跳过整个源。URL 不同时，即使 skill 名称相同也保留两条。

示例：

# 启用注册中心
xskill config --set registry.enabled=true

# 使用自定义注册中心地址（裸域名）
xskill config --set registry.url=https://example.com

# 使用自定义注册中心地址（带路径）
xskill config --set registry.url=https://example.com/api/v1/

--from 参数解析

-f / --from 参数按以下顺序解析：

1. Git URL：若值以 http:// 或 https:// 开头，直接使用
2. 配置名称：匹配已配置的源名称
3. GitHub 简写：若值包含 /（如 ORG/REPO），展开为 https://github.com/ORG/REPO.git
4. 错误：若以上均不匹配，报告“源未找到“

--skill 参数

-s / --skill 参数接受：

• 特定技能名称（如 vue）— 精确匹配，不支持模糊或子串匹配
• 通配符 * 匹配所有技能

--agent 验证规则

当 -a / --agent 指定具体平台名称（非 *）时，该平台必须存在于配置的 platforms 中。否则显示以下错误：

Invalid agents: <输入值>                    （黄色）
Valid agents: platform1, platform2, ...     （黑灰色）

URL 归一化

所有 URL 相关操作在比较或缓存前会去除 .git 后缀。适用于 cache update --from、query --from、find --from 及 URL 缓存文件名生成（source_<md5>.json）。例如，https://github.com/org/repo.git 和 https://github.com/org/repo 视为同一 URL。

安装模型：规范目录 + 软链接

技能文件存放在规范目录（.agents/skills/），各平台目录通过相对路径软链接指向规范目录。

.agents/skills/my-skill/          ← 文件实际存放位置（规范目录）
.codebuddy/skills/my-skill/       → symlink → ../../.agents/skills/my-skill/
.gemini/skills/my-skill/          → symlink → ../../.agents/skills/my-skill/

全局 vs 本地路径

软链接规则

• 相对路径：使用 relative(platform_skills_dir, canonical_skill_dir) 生成相对路径，便于目录移动。
• 幂等：已存在且指向同一目标 → 跳过。
• 更新：已存在但指向不同目标 → 删除重建。
• 自动创建父目录：mkdir -p 确保平台 skills 子目录存在。
• 跨平台：Windows 使用 junction，Unix 使用 symlink。

回退机制

优先：symlink（默认）
  ↓ 失败
回退：copy（文件复制）

symlink 创建失败时，清理目标目录后回退为 copy_dir_recursive 文件复制。

平台目录不存在时的行为

锁文件

锁文件追踪已安装技能，确保可复现性。

位置

格式

{
  "version": 1,
  "skills": {
    "vue": {
      "source": "antfu",
      "source_type": "git",
      "source_url": "https://github.com/antfu/skills.git",
      "skill_path": "skills/vue/SKILL.md",
      "skill_folder_hash": "abc123...",
      "installed_at": "2026-07-15T18:16:42.852Z",
      "updated_at": "2026-07-15T18:16:42.852Z"
    },
    "my-skill": {
      "source": "custom",
      "source_type": "git",
      "source_url": "https://github.com/user/my-skill.git",
      "skill_path": "my-skill/SKILL.md",
      "skill_folder_hash": "def456...",
      "installed_at": "2026-07-25T10:00:00.000Z",
      "updated_at": "2026-07-25T10:00:00.000Z"
    }
  },
  "updated_at": "2026-07-15T18:16:42.852Z"
}

条目字段

顶层字段

update 命令使用锁文件记录重新获取技能，同时保留原始 installed_at 时间戳。

restore 命令从项目锁文件读取，并写回同级锁文件（默认项目级，-g 时全局级），更新 skill_folder_hash 和两个 updated_at 字段，保留原始 installed_at。

JSON Schema

schemas/ 目录提供两个 JSON Schema，同时托管在 xskill.gcli.cn。

xskill.schema.json — 工具配置

用于 ~/.xskill/settings.json，定义完整配置结构。

顶层字段：

Platform（platforms.*）：

Source（sources[]）：

RecommendedSource（recommended[]）：

CacheConfig（cache）：

RegistryConfig（registry）：

registry.schema.json — 注册中心索引

用于注册中心 API 响应（skills.json），定义技能索引数据结构。

顶层字段：

SourceEntry（sources[]）：

SkillEntry（sources[].skills[]）：

编辑器集成

xskill config --init 会自动在 settings.json 中添加 $schema 字段：

{
  "$schema": "https://xskill.gcli.cn/xskill.schema.json",
  ...
}

大多数 JSON 编辑器（VSCode、Neovim + jsonls 等）会自动从该 URL 加载 schema，提供校验和自动补全。

开发

构建

cargo build

测试

cargo test

项目结构

xskill/
├── Cargo.toml
├── README.md
├── schemas/                # JSON Schema 定义
│   ├── xskill.schema.json    # settings.json schema
│   └── registry.schema.json  # 注册中心索引 schema
├── docs/                   # 文档源（mdbook 输入）
│   ├── SPEC.md             # 需求规范
├── book/                   # mdbook 输出（生成）
│   ├── en/
│   └── zh/
├── crates/
│   └── generate-book/      # mdbook 内容生成器
├── src/
│   ├── main.rs             # CLI 入口（clap derive）
│   ├── config.rs           # 配置处理
│   ├── git.rs              # Git 操作（克隆、稀疏检出）
│   ├── lock.rs             # 锁文件管理
│   ├── skill_meta.rs       # SKILL.md frontmatter 解析
│   ├── cache.rs            # 缓存数据结构
│   ├── utils.rs            # 工具函数
│   └── commands/
│       ├── add.rs          # 安装技能
│       ├── link.rs         # 软链接已有技能到平台
│       ├── remove.rs       # 移除技能
│       ├── update.rs       # 从锁文件更新
│       ├── restore.rs      # 从锁文件恢复
│       ├── list.rs         # 列出已安装技能
│       ├── find.rs         # 交互式 TUI 技能查找器
│       ├── query.rs        # 查询远程/缓存技能
│       ├── sources.rs      # 管理源（CRUD）
│       ├── platforms.rs    # 列出平台
│       ├── rec.rs          # 管理推荐技能（list/add/remove）
│       ├── cache.rs        # 缓存管理
│       ├── config.rs       # 配置管理
│       └── new.rs          # 创建技能项目

许可证

Apache License 2.0