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

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 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), 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:

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 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 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

# 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

# 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:

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	Core implementation (_install_skill, _uninstall_skill, _read_skill_markdown)
agent_reach/skill/	Packaged SKILL.md and references/ assets
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 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 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 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 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.

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