# How Agent-Reach Skill Installation Works Across OpenClaw, Claude Code, and .agents Directories

> Discover how Agent-Reach installs AI skills across OpenClaw, Claude Code, and .agents directories. Learn about detecting agent directories and copying skill bundles.

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

---

**Agent-Reach installs its AI skill by detecting supported agent directories, selecting the appropriate localized markdown file, and copying the skill bundle into the first available location, defaulting to `~/.agents/skills` when no specific platform is detected.**

The **Agent-Reach** library (from the `Panniantong/Agent-Reach` repository) ships with a compact skill package—comprising a [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) file and optional `references/` assets—that enables seamless integration with any AI-agent platform following the OpenClaw/Claude Code skill contract. Understanding how this **skill installation** mechanism works across different agent ecosystems ensures developers can deploy and maintain their agent capabilities correctly.

## The Three Target Directories for Skill Installation

The installation routine in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (specifically within the `_install_skill` function) builds a prioritized list of directories where the skill can be registered. The system checks these locations in order, installing into the first existing directory it encounters.

### ~/.agents/skills (Platform-Agnostic)

The **`~/.agents/skills`** directory represents the generic, platform-agnostic location and receives highest priority in the detection sequence. This directory serves as the universal fallback for agent skills that are not specific to OpenClaw or Claude Code.

### ~/.openclaw/skills (OpenClaw)

For **OpenClaw** installations, the system targets `~/.openclaw/skills`. If the `OPENCLAW_HOME` environment variable is set, the installer dynamically inserts that custom path at the front of the priority list (see lines 427-440 of [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)), allowing users to override default locations with custom OpenClaw home directories.

### ~/.claude/skills (Claude Code)

When **Claude Code** is present on the system, the installer looks for `~/.claude/skills`. This directory follows the same structure as the OpenClaw equivalent, maintaining consistency across different agent platforms.

## Locale-Aware Skill Selection

Before copying files, the installer determines which localized version of the skill documentation to deploy. Agent-Reach bundles two markdown files in the `agent_reach/skill/` directory:

- **[`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md)** — The default language version
- **[`SKILL_en.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL_en.md)** — The English locale version

The code calls `locale.getdefaultlocale()` to detect the system locale (lines 365-382). If the locale string starts with `en_`, the English file is selected; otherwise, the default markdown file is used. This ensures that agent instructions match the user's preferred language when supported.

## The Installation Process in agent_reach/cli.py

The `_install_skill` function (lines 355-464) executes the installation in three distinct stages:

1. **Directory Detection**: Builds the prioritized list of candidate directories, checking for existence and respecting the `OPENCLAW_HOME` override.

2. **Target Preparation**: For the first existing directory found:
   - Creates a subfolder named `agent-reach`
   - Clears existing contents if the folder already exists (to prevent stale files)
   - Uses the locale-selected markdown file as the primary skill definition

3. **Asset Copying**: 
   - Writes the chosen [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) into the `agent-reach` folder
   - Recursively copies the `references/` subdirectory if it exists in the package
   - Handles errors gracefully, continuing to the next candidate directory if copying fails

If none of the known directories exist, the installer creates `~/.agents/skills/agent-reach` as a fallback (lines 453-456).

### Force Reinstall Behavior

When `force=True` is passed to `_install_skill()`, the installer clears existing skill directories before writing new files, ensuring a clean installation without legacy artifacts.

## Uninstalling the Skill

The `_uninstall_skill` function (lines 466-472) provides symmetric cleanup functionality. It iterates over the same three directory locations (`~/.agents/skills`, `~/.openclaw/skills`, and `~/.claude/skills`) and removes the entire `agent-reach` folder from each location if present.

## Code Examples

Install the Agent-Reach skill programmatically:

```python
from agent_reach.cli import _install_skill

# Standard installation

_install_skill()

# Force reinstall (clears existing files first)

_install_skill(force=True)

```

Remove the skill from all known agent directories:

```python
from agent_reach.cli import _uninstall_skill

# Uninstall from all detected locations

_uninstall_skill()

```

## Summary

- **Agent-Reach** supports three installation targets: `~/.agents/skills` (highest priority), `~/.openclaw/skills`, and `~/.claude/skills`.
- The **`OPENCLAW_HOME`** environment variable overrides default OpenClaw paths, inserting custom locations at the front of the priority list.
- **Locale detection** automatically selects between [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) and [`SKILL_en.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL_en.md) based on `locale.getdefaultlocale()`.
- The **`_install_skill`** function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) handles directory creation, file copying, and reference asset deployment.
- The **`_uninstall_skill`** function cleans up all installed instances across the three supported directories.

## Frequently Asked Questions

### What happens if multiple agent directories exist on my system?

Agent-Reach installs the skill into the **first existing directory** from its prioritized list. The order is: `~/.agents/skills` (highest priority), then `~/.openclaw/skills`, then `~/.claude/skills`, with `OPENCLAW_HOME` overrides taking precedence if set. The installer stops after successfully writing to the first available location.

### How does Agent-Reach handle different system locales?

According to the source code in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), the installer checks `locale.getdefaultlocale()` during the selection phase. If the returned locale starts with `en_`, the system copies [`skill/SKILL_en.md`](https://github.com/Panniantong/Agent-Reach/blob/main/skill/SKILL_en.md); otherwise, it uses the default [`skill/SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/skill/SKILL.md). This ensures the skill documentation matches the user's language preferences when English localization is available.

### Where is the skill installation logic implemented?

The core installation logic resides in **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** within the `_install_skill` function (lines 355-464). This function handles directory detection, locale selection, file copying, and error handling. The uninstall counterpart, `_uninstall_skill`, occupies lines 466-472 of the same file.

### How do I force a reinstall of the Agent-Reach skill?

Pass `force=True` to the `_install_skill()` function. This triggers the clearing of existing `agent-reach` directories before writing new files, ensuring no stale references or outdated assets remain from previous installations. This is particularly useful during development when skill files change frequently.