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

> Learn how the agent reach skill install command places SKILL.md files into agent directories. Discover the automated process for skill definition and documentation installation.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-12

---

**The `agent-reach skill --install` command scans standard agent directories (such as `~/.openclaw/skills/`), selects the first location without an existing [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md), and copies the skill definition from [`agent_reach/skill/SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)) performs the copy operation using standard library functions:

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py).

## Practical Usage Examples

Install the skill into the first available agent directory:

```bash
agent-reach skill --install

```

Force an overwrite of existing skill files:

```bash
agent-reach skill --install --force

```

Remove the skill from all discovered directories:

```bash
agent-reach skill --uninstall

```

## Summary

- The `agent-reach skill --install` command automates skill registration by copying [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) from [`agent_reach/skill/SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) file from [`agent_reach/skill/SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) file and `references/` folder from all discovered agent directories, cleaning up the installation without manual intervention.