How to use SkillFS

4.1 Check if it is installed

skillfs --version

If the command does not exist, it can be installed from the system software source.

4.2 Install using yum

sudo yum install skillfs

4.3 Check FUSE environment

fusermount3 --version
ls -l /dev/fuse

if /dev/fuse Does not exist or the current user does not have permission to access, please check the FUSE3 package and device permissions in the ECS image.

5.1 Confirm that there is an existing Skill source directory

Use a source directory that contains multiple Skills, for example:

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

You can put high-frequency skills into default view and low-frequency, experimental or backup skills into secondary view according to the main usage scenarios. In this way, the main entrance of the Agent is kept simple, and irrelevant Skills will not affect the use of the main scene; you can still use it when necessary. skill-discover Discover and use skills in secondary view.

illustrate:

• The above example is a Flat layout, and each first-level subdirectory represents a Skill.

• The directory name is the runtime skill identifier for SkillFS.

• Each Skill directory should contain parsable SKILL.md.

• SKILL.md in frontmatter name Fields are used for declaration or display, not as runtime path keys.

5.2 Hermes layout

SkillFS also supports Hermes layout. Skills can be located in the category directory or directly in the source root directory.

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

--skill-layout The default value is auto. Source root directory exists .bundled_manifest or .hub/ When, SkillFS automatically uses the Hermes layout, otherwise it uses the Flat layout. You can also pass --skill-layout flat or --skill-layout hermes Explicitly specified.

The Hermes layout is mounted in the same way as the Flat layout, just replace the source parameter with Hermes source. The access path after mounting is as follows.

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

The following mount example continues to use /data/agent-skills As a Flat Skill source.

mkdir -p /tmp/skillfs-demo/mount

5.3 Normal mount

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

illustrate:

• --foreground Or default parameters are used for foreground running, suitable for first-time verification, viewing logs directly, or hosting by systemd. Not used --managedcase,skillfs mount It will continue to run and will not automatically go to the background.

• Normal mount will continue to run. according to Ctrl+C or send SIGTERM , SkillFS will uninstall and exit.

• When the mount needs to be separated from the current terminal and SkillFS is responsible for exception recovery, the managed mount in Section 5.6 should be used.

5.4 Verification

Under Normal mount, Agent passes <mount>/skills/<skill> Visit Skills.

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

If you can see the Skill in the default view and read the corresponding SKILL.md, indicating that the mounting is successful.

5.5 Uninstall normal mounts

fusermount3 -u /tmp/skillfs-demo/mount

If SkillFS is running in the current terminal, you can also press Ctrl+C stop.

5.6 Managed mounts

When you need to disconnect the mount from the current terminal and continue running after Agent Gateway restarts, you can use --managed.

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

The command will return when the mount is ready. SkillFS supervisor will perform bounded retry when the worker exits abnormally.

Use the following command to stop the managed mount.

skillfs stop /tmp/skillfs-demo/mount

skillfs stop The supervisor and worker will be stopped and the uninstallation will be completed. This command can be executed repeatedly.

6.1 Frontend mount

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

There are no additional /skills layer. The access path is:

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

Applicable scenarios:

• It is hoped that the Agent, installer and user will all access the Skill through the same path.

• It is hoped that all user-mode file access will go through SkillFS.

Things to note:

• --security-mode Source and mountpoint are required to be in the same directory.

• It is not recommended to directly use the system home directory, root directory or existing business working directory as the In-place mount target.

• Skills can be installed, updated, and removed via SkillFS during the mount. A checkpoint, init, or rollback tool that replaces or renames the entire mountpoint should be run before mounting or after unmounting.

6.2 Managed mount

In-place mounts can also be hosted by SkillFS supervisors.

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

The same mountpoint is still used when stopped.

skillfs stop /data/agent-skills

7.1 Applicable scenarios

View separation can be used when a large number of Skills are mixed in a source directory, but only some of them belong to the current high-frequency scene. For example:

• High-frequency skills are placed in default view and appear directly in the runtime directory.

• Low-frequency or experimental Skills are placed in secondary view and passed skill-discover Discover on demand.

• Different Agents can share the same source directory, but use different views to control the visible range of the main entrance.

7.2 Configure default view and secondary view

Created in the source root directory skillfs-views.toml:

[[view]]
name = "default"
default = true
description = "High-frequency skills appear directly in the runtime directory"
skills = ["weather-query", "ecs-diagnosis"]

[[view]]
name = "secondary"
default = false
description = "Low-frequency or backup skills, discovered through skill-discover"
skills = ["kernel-tuning", "image-helper"]

The above configuration means:

• weather-query and ecs-diagnosis Will be displayed directly in the default view.

• kernel-tuning and image-helper Not displayed directly, but available via skill-discover Discover.

illustrate:

• SkillFS passed default = true Determine the default view.

• name It is only displayed as the view name and does not determine whether the view is the default view.

7.3 View the default view after mounting

View default view under Normal mount:

ls /tmp/skillfs-demo/mount/skills

If the configuration is in effect, the list should contain weather-query and ecs-diagnosis, will not be displayed directly kernel-tuning and image-helper.

7.4 Discover secondary views through skill-discover

skill-discover It is a virtual skill provided by SkillFS. The agent can read this to learn what skills are available in the secondary view.

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

There are no additional /skills layer, the corresponding path is:

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

7.5 Common commands for managing views

Commonly used commands:

# Verify Skill source directory
skillfs validate /data/agent-skills

# List Skills
skillfs list /data/agent-skills

# Generate or view view classifications
skillfs classify /data/agent-skills

illustrate:

• Revise skillfs-views.toml Afterwards, remounting ensures that the view state is refreshed.

• Not configured skillfs-views.toml SkillFS uses default view rules to display Skills recognized in the source.

8.1 Enable OS Adapter

Create a SkillFS configuration file, e.g. /etc/skillfs/skillfs.toml.

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

passed when mounting --config load.

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

--config The same applies to in-place mounts and managed mounts.

8.2 target_os description

auto will ubuntu and debian Identified as an Ubuntu target, put alinux and anolis Identified as an Alinux target. When the current ECS image cannot be recognized, SkillFS will refuse to mount and output an error, and will not shut down the OS Adapter silently.

8.3 Conversion example

For example, in source SKILL.md Contains the following Ubuntu commands.

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

Under the Alinux target, the content read by the Agent is as follows.

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

Transformations cover common package manager commands,-dev and -devel Package name, service name and part of the system path. The conversion occurs in the reading phase. The same Skill source can be mounted to ECS of different operating systems and the corresponding content can be obtained respectively.

The SkillFS binary has built-in conversion rules for Ubuntu and Alinux, and no additional rule files are required by default. Read-on-read transformations do not access the network, call models, or initiate external commands. You need to remount after modifying the configuration.

8.4 Verify OS Adapter

Read the runtime view after mounting SKILL.md.

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

To confirm that the source has not been modified, you can read the physical file at the same time.

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

Under Normal mount, these two paths represent the Agent visible content and the original source content respectively.

9.1 Preparing the OpenClaw Skill Directory

Assume that the workspace Skill directory of OpenClaw is:

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

9.2 Use foreground mounting to take over the directory

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

After the mounting is complete, OpenClaw still installs and uses the skill in the original way. OpenClaw write $OPENCLAW_SKILLS The content will enter the physical source and read SKILL.md It will go through SkillFS's view and read-time conversion.

9.3 Using managed mount

Managed mount can be used when you need the mount to continue working after OpenClaw Gateway restarts.

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

Stop mounting.

skillfs stop "$OPENCLAW_SKILLS"

10.1 View version

skillfs --version

10.2 Verify Skill source directory

skillfs validate <source>

10.3 List Skills

skillfs list <source>

10.4 Mount SkillFS

skillfs mount <source> <mountpoint> [OPTIONS]

Commonly used parameters:

10.5 Stop managed mount

skillfs stop <mountpoint>

11.1 What should I do if the mount fails and prompts that FUSE is unavailable?

Please check whether FUSE3 is installed,/dev/fuse exists, and whether the current user has access /dev/fuse permissions.

fusermount3 --version
ls -l /dev/fuse

11.2 Why is there in the path under Normal mount /skills?

The mountpoint of Normal mount is a SkillFS runtime root directory. Skill is displayed by default in <mount>/skills/<skill> Down. In-place mount uses the source path directly, so there are no additional /skills layer.

11.3 What should I do if I can’t see the new Skill?

Please confirm:

• The Skill directory is located in the first-level subdirectory of source.

• The directory contains resolvable SKILL.md.

• If using skillfs-views.toml, whether the Skill is in the default view.

• Can run skillfs validate <source> Check the parsing results.

11.4 How to stop SkillFS?

Foreground mounting can be done by pressing Ctrl+C, you can also use fusermount3 -u <mountpoint> uninstall. Managed mount should be used skillfs stop <mountpoint>, so that the supervisor will not pull up the worker again.

11.5 What should I do if the OS Adapter does not take effect?

Please confirm:

• The mount command has been passed in --config <PATH>.

• Configuring [transforms.os_adapter] of enabled for true.

• target_os for auto, ubuntu or alinux.

• What is read is after mounting SKILL.md, not a physical source file.

• It has been remounted after modifying the configuration.

11.6 Why is there no change in SKILL.md in source?

expected behavior. The OS Adapter only converts the content read by the Agent through the mount path and does not modify the physical source file.