How the Skill Registration Process Installs SKILL.md Files into Agent Directories

The agent-reach skill --install command scans standard agent directories (such as ~/.openclaw/skills/), selects the first location without an existing SKILL.md, and copies the skill definition from agent_reach/skill/SKILL.md along with the references/ documentation folder.

The Agent-Reach repository provides a CLI-based skill registration system that enables AI agents to discover available commands dynamically without hard-coding tool integrations. When you run the skill installation command, the system places a standardized SKILL.md file and supporting documentation into agent-specific directories, allowing the agent to parse routing tables and execute appropriate commands for user requests.

How the Installation Works

The installation process implemented in agent_reach/cli.py follows a deterministic sequence to ensure safe, conflict-free registration across multiple agent environments.

Locating Agent Skill Directories

The CLI begins by scanning well-known locations where agents store their skill files. According to the source code, the installer checks paths such as ~/.openclaw/skills/ along with any user-defined custom directories. The scanning logic walks each directory tree looking for folders named after the skill package (e.g., agent-reach).

Selecting the Target Directory

To prevent duplicate installations, the system selects the first directory that does not already contain a SKILL.md file. This validation mechanism ensures that existing agent configurations remain untouched unless explicitly overridden by the user.

Copying SKILL.md and Reference Assets

Once a target directory is identified, the installer copies two critical components from the package's agent_reach/skill/ directory:

1. The SKILL.md file – Contains the routing table and command shortcuts
2. The references/ subdirectory – Holds detailed documentation for platform categories including search, social, career, dev, web, video, and finance tools

The implementation (lines 374-406 in agent_reach/cli.py) performs the copy operation using standard library functions:

# Copy SKILL.md using the selected locale file

with open(os.path.join(target, "SKILL.md"), "w", encoding="utf-8") as f:
    f.write(skill_pkg.joinpath("SKILL.md").read_text(encoding="utf-8"))

# Copy the reference markdown files

shutil.copytree(
    os.path.join(skill_pkg, "references"),
    os.path.join(target, "references"),
    dirs_exist_ok=True,
)

Overwrite Protection

By default, the installer aborts with a warning if SKILL.md already exists in the chosen directory. Users must pass the --force flag to override existing files, preventing accidental overwrites of customized agent configurations.

Uninstalling the Skill

The complementary command agent-reach skill --uninstall reverses the installation process. It walks the same directory paths identified during installation and removes the SKILL.md file along with the accompanying references/ folder. This cleanup logic is implemented in the *_cmd_skill* handler starting at line 467 in agent_reach/cli.py.

Practical Usage Examples

Install the skill into the first available agent directory:

agent-reach skill --install

Force an overwrite of existing skill files:

agent-reach skill --install --force

Remove the skill from all discovered directories:

agent-reach skill --uninstall

Summary

• The agent-reach skill --install command automates skill registration by copying SKILL.md into agent directories.
• The installer scans ~/.openclaw/skills/ and custom paths, selecting the first directory without an existing skill file.
• It copies both the main SKILL.md from agent_reach/skill/SKILL.md and the entire references/ subdirectory containing platform-specific documentation.
• The --force flag is required to overwrite existing installations.
• Uninstallation removes both the skill definition and reference materials from all discovered directories.

Frequently Asked Questions

Where does the skill installer look for agent directories?

The installer scans well-known locations such as ~/.openclaw/skills/ and any custom paths defined by the user. It walks each directory tree to identify folders named after the skill package, ensuring compatibility with standard agent workspace layouts.

What files are copied during skill registration?

The process copies the locale-specific SKILL.md file from agent_reach/skill/SKILL.md and the entire references/ subdirectory containing detailed command documentation for categories like search, social, and development tools.

How does the installer prevent duplicate skill files?

The system selects the first discovered directory that does not already contain a SKILL.md file. If the file exists and the --force flag is not provided, the installation aborts to prevent overwriting existing configurations.

Can I uninstall the skill without manually deleting files?

Yes. Running agent-reach skill --uninstall automatically removes the SKILL.md file and references/ folder from all discovered agent directories, cleaning up the installation without manual intervention.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}