# How Agent-Reach Manages Skill Installation for Different AI Agents

> Agent-Reach simplifies skill installation for AI agents, copying assets to platform-specific directories for OpenClaw Claude Code and more. Learn how it works.

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

---

**Agent-Reach installs reusable skills across OpenClaw, Claude Code, and generic agent environments by copying packaged assets from `agent_reach/skill/` into platform-specific directories under `~/.agents/skills`, `~/.openclaw/skills`, and `~/.claude/skills`.**

Agent-Reach provides a unified mechanism for distributing capabilities to AI agents through a portable skill package. The system enables seamless integration with multiple agent platforms by abstracting the installation logic into a single CLI command. This article examines how the **`_install_skill`** and **`_uninstall_skill`** functions in [[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) handle cross-platform skill deployment.

## Supported Agent Platforms

Agent-Reach targets three distinct agent ecosystems with prioritized installation paths:

- **Generic agents (`.agents`)**: `~/.agents/skills`
- **OpenClaw**: `~/.openclaw/skills`
- **Claude Code**: `~/.claude/skills`

The installation routine checks these directories in priority order, ensuring the skill is available wherever the user has existing agent configurations.

## How Skill Installation Works

The `_install_skill` function orchestrates the deployment process through four distinct phases:

### Locating Skill Resources

The installer first attempts to load bundled resources using `importlib.resources.files("agent_reach").joinpath("skill")`. If this fails—typically during editable installs or development environments—it falls back to the local `skill` directory adjacent to the source file【`line 399‑404`】.

### Reading Skill Metadata

The helper function `_read_skill_markdown` selects the appropriate documentation, preferring a locale-specific variant (e.g., [`SKILL.zh.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.zh.md)) over the default [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md)【`line 376‑383`】. This markdown file serves as the primary interface definition for the agent consuming the skill.

### Resolving Target Directories

The system builds a candidate list of installation paths, prioritizing the generic `.agents` location, followed by OpenClaw and Claude Code directories【`line 428‑435`】. For each existing directory, the installer creates (or symlinks) a subdirectory named `agent-reach`.

### Copying and Cleaning Assets

Before writing new files, the installer clears existing `agent-reach` directories to prevent stale artifacts【`line 389‑397`】. It then copies the markdown documentation and any contents from the `references/` subdirectory into the target location【`line 383‑424`】. If none of the standard directories exist, the system creates `~/.agents/skills/agent-reach` as a fallback to ensure the skill remains available【`line 453‑456`】.

## Automatic Installation Triggers

Skill installation is not limited to explicit CLI commands. The system automatically invokes `_install_skill` during:

1. Full installation runs (`agent-reach install`)
2. Diagnostic checks (`agent-reach doctor`)

This ensures the skill remains synchronized with the core package unless explicitly disabled by the user【`line 1492‑1493`】.

## Uninstalling Skills

The `_uninstall_skill` function mirrors the installation logic by iterating through the same three platform directories. It removes the `agent-reach` subdirectory from each location, handling both physical directories and symbolic links, and reports the status of each removal operation【`line 466‑499`】.

```bash

# Remove the skill from all supported agents

python -m agent_reach.cli skill --uninstall

```

## Practical Usage Examples

Install the skill across all detected agent environments:

```bash
python -m agent_reach.cli skill --install

```

Expected output:

```text
Installing skill for OpenClaw → ~/.openclaw/skills/agent-reach
Installing skill for Claude Code → ~/.claude/skills/agent-reach
Installing skill for generic agents → ~/.agents/skills/agent-reach

```

Programmatically copy the skill directory (replicating the CLI behavior):

```python
import shutil
import os
from pathlib import Path

src = Path(__file__).parent / "skill"
dst = os.path.expanduser("~/.agents/skills/agent-reach")

if src.exists():
    shutil.copytree(src, dst, dirs_exist_ok=True)

```

## Summary

- **Agent-Reach** deploys skills to three platforms: generic `.agents`, OpenClaw, and Claude Code.
- The **`_install_skill`** function in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) uses `importlib.resources` to locate packaged assets, then copies them to platform-specific directories under the user's home directory.
- Installation clears existing directories first to prevent stale files, with automatic fallback creation if no agent directories exist.
- The **`_uninstall_skill`** function removes the `agent-reach` directory from all known locations, handling both regular directories and symlinks.
- Skills auto-install during `agent-reach install` and `doctor` commands, ensuring continuous synchronization.

## Frequently Asked Questions

### Where does Agent-Reach install skill files by default?

Agent-Reach prioritizes `~/.agents/skills` for generic agents, followed by `~/.openclaw/skills` for OpenClaw and `~/.claude/skills` for Claude Code. If none exist, it creates `~/.agents/skills/agent-reach` to ensure the skill is always available.

### How does Agent-Reach handle existing skill installations?

Before copying new assets, the `_install_skill` function clears any existing `agent-reach` directory in the target location【`line 389‑397`】. This prevents stale documentation or reference files from interfering with the current version.

### Can the skill be installed manually without using the CLI?

Yes. The skill assets reside in the `agent_reach/skill/` directory within the package. You can manually copy this directory (including [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) and the `references/` folder) to any supported agent's skills directory, typically located at `~/.agents/skills/agent-reach`.

### What triggers automatic skill installation in Agent-Reach?

Beyond the explicit `skill --install` command, Agent-Reach automatically installs skills when running `agent-reach install` or `agent-reach doctor`【`line 1492‑1493`】. This ensures the skill package remains synchronized with the core tool unless explicitly disabled.