如何使用skillfs

4.1 检查是否已安装

skillfs --version

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

4.2 使用 yum 安装

sudo yum install skillfs

4.3 检查 FUSE 环境

fusermount3 --version
ls -l /dev/fuse

如果 /dev/fuse 不存在或当前用户无权限访问，请联系系统管理员检查 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。

说明：

• SkillFS 默认使用平铺目录结构，每个子目录代表一个 Skill。

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

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

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

下面示例假设使用 /data/agent-skills 作为 Skill source。

mkdir -p /tmp/skillfs-demo/mount

5.2 挂载

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

说明：

• --foreground 表示前台运行，便于调试和查看日志。

• 生产或后台运行时可根据业务进程管理方式去掉该参数。

5.3 验证

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.4 卸载

fusermount3 -u /tmp/skillfs-demo/mount

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 准备 OpenClaw Skill 目录

假设 OpenClaw 的 workspace skill 目录为：

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

8.2 使用 SkillFS 接管该目录

如果只需要让所有用户态访问经过 SkillFS，可以使用 in-place mount：

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

如果需要结合 Skill Ledger 或 agent-sec-core 做安全增强，可以在挂载时启用安全参数：

export AGENT_SEC_DAEMON_SOCKET="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/agent-sec-core/daemon.sock"

skillfs mount \
  "$OPENCLAW_SKILLS" \
  "$OPENCLAW_SKILLS" \
  --foreground \
  --security-mode \
  --security \
  --activation-mode file \
  --notify-socket "$AGENT_SEC_DAEMON_SOCKET" \
  --activation-reload-mode poll \
  --activation-events-log /tmp/skillfs-openclaw-activation-events.jsonl

8.3 安装和使用 Skill

挂载完成后，用户仍按 OpenClaw 原有方式安装和使用 Skill。OpenClaw 写入

$OPENCLAW_SKILLS 的内容会进入 SkillFS 管理的 source/current workspace。

• 未启用安全增强时，OpenClaw 可以直接从该目录读取当前 Skill。

• 启用安全增强时，SkillFS 会通知外部安全组件扫描 Skill。

• 扫描通过后，SkillFS 暴露可信版本，OpenClaw 可以正常读取和使用。

• 扫描未通过时，SkillFS 可以回退到上一个可信 snapshot；没有可信版本时，

  该 Skill 会对 OpenClaw 隐藏。

8.4 用户可感知的安全行为

在安全增强场景中，用户可能看到以下行为：

• 新安装 Skill 后短时间不可见：等待外部安全组件扫描并写入 activation。

• 良性更新后自动切换到新版本：外部安全组件确认新版本可信。

• 风险更新后仍使用旧版本：SkillFS 回退到上一个可信 snapshot。

• 用户或策略阻断后 Skill 不可见：该 Skill 不再出现在 Agent 可访问视图中。

9.1 查看版本

skillfs --version

9.2 校验 Skill 源目录

skillfs validate <source>

9.3 列出 Skill

skillfs list <source>

9.4 挂载 SkillFS

skillfs mount <source> <mountpoint> [OPTIONS]

常用参数：

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

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

fusermount3 --version
ls -l /dev/fuse

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

Normal mount 的 mountpoint 是一个 SkillFS 运行时根目录，Skill 默认展示在 <mount>/skills/<skill> 下。

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

请确认：

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

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

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

• 如果启用了外部安全集成，Skill 可能需要等待安全组件写入可见状态。

10.4 如何停止 SkillFS？

使用 fusermount3 -u <mountpoint> 卸载。如果使用前台运行，也可以先
通过 Ctrl+C 停止进程，再确认挂载点已卸载。