如何使用skillfs

4.1 检查是否已安装

skillfs --version

如果命令不存在，可以通过系统软件源安装。

4.2 使用 yum 安装

sudo yum install skillfs

4.3 检查 FUSE 环境

fusermount3 --version
ls -l /dev/fuse

如果 /dev/fuse 不存在或当前用户无权限访问，请检查 ECS 镜像中的 FUSE3 软件包和设备权限。

5.1 确认已有 Skill 源目录

使用一个包含多个 Skill 的源目录，例如：

/data/agent-skills/
  weather-query/
    SKILL.md
    scripts/
  ecs-diagnosis/
    SKILL.md
  kernel-tuning/
    SKILL.md
  image-helper/
    SKILL.md

可以根据主要使用场景，将高频 Skill 放入 default view，将低频、实验性或备用 Skill 放入 secondary view。这样 Agent 的主入口保持简洁，无关 Skill 不会影响主要场景使用；必要时仍可通过 skill-discover 发现和使用 secondary view 中的 Skill。

说明：

• 上面的示例是 Flat 布局，每个一级子目录代表一个 Skill。

• 目录名是 SkillFS 的运行时 Skill 标识。

• 每个 Skill 目录应包含可解析的 SKILL.md。

• SKILL.md frontmatter 中的 name 字段用于声明或展示，不作为运行时路径 key。

5.2 Hermes 布局

SkillFS 也支持 Hermes 布局。Skill 可以位于分类目录下，也可以直接位于 source 根目录。

/data/hermes-skills/
  .hub/
  apple/
    apple-notes/
      SKILL.md
  top-level-skill/
    SKILL.md

--skill-layout 默认值是 auto。Source 根目录存在 .bundled_manifest 或 .hub/ 时，SkillFS 自动使用 Hermes 布局，否则使用 Flat 布局。也可以通过 --skill-layout flat 或 --skill-layout hermes 显式指定。

Hermes 布局的挂载方式与 Flat 布局相同，只需将 source 参数替换为 Hermes source。挂载后的访问路径如下。

<mountpoint>/skills/apple/apple-notes/SKILL.md
<mountpoint>/skills/top-level-skill/SKILL.md

下面的挂载示例继续使用 /data/agent-skills 作为 Flat Skill source。

mkdir -p /tmp/skillfs-demo/mount

5.3 普通挂载

skillfs mount \
  /data/agent-skills \
  /tmp/skillfs-demo/mount \
  --foreground

说明：

• --foreground 或缺省参数用于前台运行，适合首次验证、直接查看日志或交由 systemd 托管。未使用 --managed情况下，skillfs mount 会持续运行，不会自动转入后台。

• 普通 mount 会持续运行。按 Ctrl+C 或发送 SIGTERM 时，SkillFS 会卸载并退出。

• 需要让挂载脱离当前终端并由 SkillFS 负责异常恢复时，应使用 5.6 节的 Managed mount。

5.4 验证

Normal mount 下，Agent 通过 <mount>/skills/<skill> 访问 Skill。

ls /tmp/skillfs-demo/mount/skills
cat /tmp/skillfs-demo/mount/skills/weather-query/SKILL.md

如果可以看到 default view 中的 Skill 并读取对应 SKILL.md，说明挂载成功。

5.5 卸载普通挂载

fusermount3 -u /tmp/skillfs-demo/mount

如果 SkillFS 正在当前终端运行，也可以按 Ctrl+C 停止。

5.6 托管挂载

需要让挂载脱离当前终端并在 Agent Gateway 重启后继续运行时，可以使用 --managed。

skillfs mount \
  /data/agent-skills \
  /tmp/skillfs-demo/mount \
  --managed

命令会在挂载就绪后返回。SkillFS supervisor 会在 worker 异常退出时进行有界重试。

使用下面的命令停止 Managed mount。

skillfs stop /tmp/skillfs-demo/mount

skillfs stop 会停止 supervisor 和 worker，并完成卸载。该命令可以重复执行。

6.1 前台挂载

skillfs mount \
  /data/agent-skills \
  /data/agent-skills \
  --foreground \
  --security-mode

In-place mount 下没有额外的 /skills 层。访问路径是：

ls /data/agent-skills
cat /data/agent-skills/weather-query/SKILL.md

适用场景：

• 希望 Agent、安装器和用户都通过同一个路径访问 Skill。

• 希望所有用户态文件访问都经过 SkillFS。

注意事项：

• --security-mode 要求 source 和 mountpoint 是同一目录。

• 不建议把系统主目录、根目录或已有业务工作目录直接作为 In-place mount 目标。

• 挂载期间可以通过 SkillFS 安装、更新和删除 Skill。会替换或重命名整个 mountpoint 的 checkpoint、init 或 rollback 工具，应在挂载前或卸载后运行。

6.2 托管挂载

In-place mount 也可以由 SkillFS supervisor 托管。

skillfs mount \
  /data/agent-skills \
  /data/agent-skills \
  --security-mode \
  --managed

停止时仍使用相同的 mountpoint。

skillfs stop /data/agent-skills

7.1 适用场景

当一个 source 目录中混放了大量 Skill，但只有一部分属于当前高频场景时，可以使用视图分离。例如：

• 高频 Skill 放入 default view，直接出现在运行时目录中。

• 低频或实验性 Skill 放入 secondary view，通过 skill-discover 按需发现。

• 不同 Agent 可以共享同一个 source 目录，但使用不同视图控制主入口可见范围。

7.2 配置 default view 和 secondary view

在 source 根目录创建 skillfs-views.toml：

[[view]]
name = "default"
default = true
description = "高频 Skill，直接出现在运行时目录"
skills = ["weather-query", "ecs-diagnosis"]

[[view]]
name = "secondary"
default = false
description = "低频或备用 Skill，通过 skill-discover 发现"
skills = ["kernel-tuning", "image-helper"]

上述配置表示：

• weather-query 和 ecs-diagnosis 会直接显示在 default view 中。

• kernel-tuning 和 image-helper 不直接显示，但可通过 skill-discover 发现。

说明：

• SkillFS 通过 default = true 判断默认视图。

• name 仅作为视图名称展示，不决定该 view 是否为默认视图。

7.3 挂载后查看 default view

Normal mount 下查看 default view：

ls /tmp/skillfs-demo/mount/skills

如果配置生效，列表中应包含 weather-query 和 ecs-diagnosis，不会直接显示 kernel-tuning 和 image-helper。

7.4 通过 skill-discover 发现 secondary view

skill-discover 是 SkillFS 提供的虚拟 Skill。Agent 可以读取它来了解 secondary view 中还有哪些 Skill 可用。

cat /tmp/skillfs-demo/mount/skills/skill-discover/SKILL.md

In-place mount 下没有额外的 /skills 层，对应路径为：

cat /data/agent-skills/skill-discover/SKILL.md

7.5 管理视图的常用命令

常用命令：

# 校验 Skill 源目录
skillfs validate /data/agent-skills

# 列出 Skill
skillfs list /data/agent-skills

# 生成或查看视图分类
skillfs classify /data/agent-skills

说明：

• 修改 skillfs-views.toml 后，重新挂载可确保视图状态刷新。

• 未配置 skillfs-views.toml 时，SkillFS 使用默认视图规则展示 source 中可识别的 Skill。

8.1 启用 OS Adapter

创建 SkillFS 配置文件，例如 /etc/skillfs/skillfs.toml。

[transforms.os_adapter]
enabled = true
target_os = "auto"

挂载时通过 --config 加载。

skillfs mount \
  /data/agent-skills \
  /tmp/skillfs-demo/mount \
  --foreground \
  --config /etc/skillfs/skillfs.toml

--config 同样适用于 In-place mount 和 Managed mount。

8.2 target_os 说明

auto 会把 ubuntu 和 debian 识别为 Ubuntu 目标，把 alinux 和 anolis 识别为 Alinux 目标。无法识别当前 ECS 镜像时，SkillFS 会拒绝挂载并输出错误，不会静默关闭 OS Adapter。

8.3 转换示例

例如，source 中的 SKILL.md 包含下面的 Ubuntu 命令。

sudo apt-get install -y libssl-dev
sudo systemctl restart cron

在 Alinux 目标下，Agent 读取到的内容如下。

sudo dnf install -y openssl-devel
sudo systemctl restart crond

转换覆盖常见包管理器命令、-dev 和 -devel 包名、service 名称及部分系统路径。转换发生在读取阶段，同一份 Skill source 可以挂载到不同操作系统的 ECS，并分别得到对应内容。

SkillFS 二进制已经内置 Ubuntu 与 Alinux 的转换规则，默认不需要额外规则文件。读时转换不会访问网络、调用模型或启动外部命令。修改配置后需要重新挂载。

8.4 验证 OS Adapter

挂载后读取运行时视图中的 SKILL.md。

cat /tmp/skillfs-demo/mount/skills/weather-query/SKILL.md

如需确认 source 没有被修改，可以同时读取物理文件。

cat /data/agent-skills/weather-query/SKILL.md

Normal mount 下，这两个路径分别表示 Agent 可见内容和原始 source 内容。

9.1 准备 OpenClaw Skill 目录

假设 OpenClaw 的 workspace Skill 目录为：

export OPENCLAW_SKILLS="$HOME/.openclaw/workspace/skills"
mkdir -p "$OPENCLAW_SKILLS"

9.2 使用前台挂载接管该目录

skillfs mount \
  "$OPENCLAW_SKILLS" \
  "$OPENCLAW_SKILLS" \
  --foreground \
  --security-mode

挂载完成后，OpenClaw 仍按原有方式安装和使用 Skill。OpenClaw 写入 $OPENCLAW_SKILLS 的内容会进入物理 source，读取 SKILL.md 时会经过 SkillFS 的视图和读时转换。

9.3 使用 Managed mount

需要让挂载在 OpenClaw Gateway 重启后继续工作时，可以使用 Managed mount。

skillfs mount \
  "$OPENCLAW_SKILLS" \
  "$OPENCLAW_SKILLS" \
  --security-mode \
  --managed

停止挂载。

skillfs stop "$OPENCLAW_SKILLS"

10.1 查看版本

skillfs --version

10.2 校验 Skill 源目录

skillfs validate <source>

10.3 列出 Skill

skillfs list <source>

10.4 挂载 SkillFS

skillfs mount <source> <mountpoint> [OPTIONS]

常用参数：

10.5 停止 Managed mount

skillfs stop <mountpoint>

11.1 挂载失败，提示 FUSE 不可用怎么办？

请检查 FUSE3 是否安装、/dev/fuse 是否存在，以及当前用户是否具备访问 /dev/fuse 的权限。

fusermount3 --version
ls -l /dev/fuse

11.2 Normal mount 下为什么路径里有 /skills？

Normal mount 的 mountpoint 是一个 SkillFS 运行时根目录，Skill 默认展示在 <mount>/skills/<skill> 下。In-place mount 直接使用 source 路径，因此没有额外的 /skills 层。

11.3 新增 Skill 后看不到怎么办？

请确认：

• Skill 目录位于 source 的一级子目录。

• 目录内存在可解析的 SKILL.md。

• 如果使用 skillfs-views.toml，该 Skill 是否在 default view 中。

• 可以运行 skillfs validate <source> 检查解析结果。

11.4 如何停止 SkillFS？

前台挂载可以按 Ctrl+C，也可以使用 fusermount3 -u <mountpoint> 卸载。Managed mount 应使用 skillfs stop <mountpoint>，这样 supervisor 不会再次拉起 worker。

11.5 OS Adapter 没有生效怎么办？

请确认：

• 挂载命令已经传入 --config <PATH>。

• 配置中 [transforms.os_adapter] 的 enabled 为 true。

• target_os 为 auto、ubuntu 或 alinux。

• 读取的是挂载后的 SKILL.md，不是物理 source 文件。

• 修改配置后已经重新挂载。

11.6 为什么 source 中的 SKILL.md 没有变化？

预期行为。OS Adapter 只转换 Agent 通过挂载路径读取到的内容，不会修改物理 source 文件。