# How Skill Installation Works for Different Agents in Agent Reach: A Complete Technical Guide

> Discover how skill installation works for OpenClaw, Claude Code, and .agents in Agent Reach. Learn about the automatic, priority-ordered detection system for efficient skill management.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: deep-dive
- Published: 2026-08-04

---

**Agent Reach automatically installs reusable skill packages into platform-specific directories for OpenClaw, Claude Code, and generic `.agents` environments using a priority-ordered detection system.**

The **Agent Reach** repository provides a cross-platform skill installation mechanism that bridges three major AI agent ecosystems. Understanding this system helps developers integrate external capabilities consistently across different runtime environments.

## What Are Skills in Agent Reach?

A **skill** in Agent Reach consists of a [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) file plus optional supporting resources in a `references/` subdirectory. These assets define reusable behaviors that Agent Reach exposes to downstream AI agents. The CLI handles copying these files into each agent's designated skill directory so the capabilities become available at runtime.

According to the source code 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), the installation logic supports three target platforms with distinct directory conventions.

## Supported Agent Platforms and Directory Priorities

| Platform | Skill Directory | Priority |
|----------|-----------------|----------|
| Generic agents | `~/.agents/skills` | 1st |
| OpenClaw | `~/.openclaw/skills` | 2nd |
| Claude Code | `~/.claude/skills` | 3rd |

When detecting installation locations, the `_install_skill` function builds this candidate list and operates on every directory that exists on the local system.

## The Skill Installation Pipeline

The installation process follows five sequential steps implemented in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py):

### 1. Locate Packaged Skill Resources

The system first attempts to load skill files via `importlib.resources.files("agent_reach").joinpath("skill")`. If this fails—common during editable installs or development environments—it falls back to the local `skill/` directory adjacent to the source file (lines 399–404).

### 2. Select Appropriate Markdown Variant

The `_read_skill_markdown` helper checks for locale-specific [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) files before defaulting to the generic version (lines 376–383). This enables internationalized skill documentation without code changes.

### 3. Determine Active Installation Paths

The function constructs the three candidate directories listed above, filtering to only those that exist or can be created (lines 428–435).

### 4. Copy Assets with Cleanup

For each valid target, the installer:
- Creates or replaces a subdirectory named `agent-reach`
- Clears existing installations to prevent stale file accumulation (lines 389–397)
- Copies [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) and the full `references/` subtree (lines 383–424)
- Creates symbolic links when appropriate for development workflows

### 5. Ensure Fallback Availability

If none of the platform-specific directories exist, the system creates `~/.agents/skills/agent-reach` as a guaranteed install location (lines 453–456).

## Skill Removal (Uninstallation)

The `_uninstall_skill` function (lines 466–499) mirrors installation logic:
- Iterates the same three candidate directories
- Removes `agent-reach` subdirectories and symlinks
- Reports success or failure per location

```bash

# Install skills across all detected agent platforms

$ python -m agent_reach.cli skill --install
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

```

```bash

# Remove skills from all known locations

$ python -m agent_reach.cli skill --uninstall
Removed OpenClaw skill: /home/user/.openclaw/skills/agent-reach
Removed Claude Code skill: /home/user/.claude/skills/agent-reach
Removed Agent skill: /home/user/.agents/skills/agent-reach

```

## Automatic Installation Triggers

Skill installation is not limited to manual CLI invocation. The codebase automatically triggers skill deployment during:

- **Full installation runs**: `agent-reach install` (line 1492)
- **Doctor/diagnostic checks**: Ensures skill presence unless explicitly disabled by the user (line 1493)

This guarantees that normal setup procedures leave the skill system in a functional state without requiring separate configuration steps.

## Manual Implementation Pattern

The underlying copy operation uses standard library utilities for cross-platform compatibility:

```python
import shutil
from pathlib import Path

def manually_install_skill(source: Path, target_base: Path) -> None:
    """Replicate the CLI's core copy behavior."""
    target = target_base / "agent-reach"
    
    # Mirror CLI's cleanup-then-copy approach

    if target.exists():
        shutil.rmtree(target)
    
    shutil.copytree(
        source,
        target,
        dirs_exist_ok=True  # Python 3.8+

    )

```

## Key Source Files

| File | Purpose |
|------|---------|
| [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) | Core implementation (`_install_skill`, `_uninstall_skill`, `_read_skill_markdown`) |
| `agent_reach/skill/` | Packaged [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) and `references/` assets |
| [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) | Path resolution and user configuration overrides |

## Summary

- **Agent Reach skill installation** targets three agent 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) implements priority-ordered directory detection and atomic replacement
- Skills auto-deploy during `install` and `doctor` commands for seamless setup
- The `references/` subdirectory and locale-aware [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) selection support complex, documented capabilities
- Uninstallation uses identical path logic with reciprocal cleanup operations

## Frequently Asked Questions

### What happens if multiple agent platforms are installed?

Agent Reach installs skills into **all detected directories simultaneously**. The tool does not require selecting a single target; it populates every existing location from the priority list.

### Can I customize where skills are installed?

The system respects platform conventions by default. For non-standard paths, modify [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) to override directory resolution before the skill command executes.

### Why does installation clear existing files first?

The `shutil.rmtree` call (lines 389–397) prevents **stale resource accumulation** when [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) or `references/` content changes between versions. This ensures agents always receive current capability definitions.

### Is the skill installation reversible?

Yes. The `skill --uninstall` command removes the `agent-reach` subdirectory from every location where it was deployed, handling both real directories and symbolic links safely.