Agent Reach AI Agent Skill Installation Mechanism: A Deep Dive into the CLI Implementation

Agent Reach installs its AI agent skill by detecting framework-specific directories, selecting locale-appropriate markdown files, and copying them into ~/.agents/skills, ~/.openclaw/skills, or ~/.claude/skills using the _install_skill function in agent_reach/cli.py.

The Agent Reach repository (Panniantong/Agent-Reach) provides a plug-in skill system that allows AI agents to understand how to interact with the tool. The installation mechanism is framework-agnostic, supporting multiple popular AI agent ecosystems through a single CLI command. This article examines the internal workings of the Agent Reach AI agent skill installation mechanism, from directory detection to locale-aware file selection.

How the Skill Installation Works

The core installation logic resides in agent_reach/cli.py and is invoked via the agent-reach skill --install command. The process follows a deterministic sequence of steps to ensure compatibility across different agent frameworks.

Framework Detection and Target Directories

The _install_skill function (lines 27-33) builds a priority list of potential skill directories. By default, it searches for:

• ~/.agents/skills
• ~/.openclaw/skills
• ~/.claude/skills

If the environment variable OPENCLAW_HOME is set, its skills subdirectory is inserted at the front of the list. When none of these directories exist, the function creates ~/.agents/skills/agent-reach as a fallback (lines 52-61).

Locale-Aware Skill Selection

Before copying files, the system determines which markdown variant to install. The _skill_resource_name function (lines 65-74) checks environment variables in this order:

1. AGENT_REACH_LANG
2. LC_ALL
3. LC_MESSAGES
4. LANG

If any of these indicate an English locale (e.g., en_US, en_GB), the function selects SKILL_en.md. Otherwise, it falls back to the generic SKILL.md.

Package Resource Resolution

To locate the skill files within the installed package, _read_skill_markdown (lines 76-81) uses importlib.resources.files("agent_reach").joinpath("skill"). This approach works with standard pip installations. For editable installs (pip install -e .), the code includes a fallback to Path(__file__).parent / "skill" to ensure the files remain accessible during development.

File Copying and Idempotency

The _copy_skill_dir function (lines 84-122) handles the actual installation:

• Creates or overwrites the agent-reach/ subdirectory in each target location
• Writes the selected SKILL.md file
• Copies any files from the references/ subdirectory
• Respects the force parameter (default True) to skip overwriting existing files when set to False

After installation, the CLI reports the platform (Agent, OpenClaw, or Claude Code) and whether files were newly installed or preserved (lines 44-50).

Uninstalling the Skill

The companion _uninstall_skill function (lines 66-99) walks the same set of directories discovered during installation. It removes the entire agent-reach/ folder from each location, or unlinks symbolic links if present. The function reports success or failure for each target directory, ensuring users know exactly which installations were affected.

Usage Examples

CLI Installation

Install the skill into the first available directory:

agent-reach skill --install

Force a fresh install, overwriting any existing skill files:

agent-reach skill --install --force

Uninstall from all known agent directories:

agent-reach skill --uninstall

Programmatic Invocation

Embed the installation step in Python scripts:

from agent_reach.cli import _install_skill, _uninstall_skill

# Install with default force=True

_install_skill()

# Uninstall from all locations

_uninstall_skill()

Controlling Locale

Force the English skill variant by setting an environment variable:

export AGENT_REACH_LANG=en_US
agent-reach skill --install

Alternatively, standard locale variables like LC_ALL or LANG also work.

Summary

• Multi-framework support: The mechanism automatically detects OpenClaw, Claude Code, and generic Agent directories, with OPENCLAW_HOME taking precedence.
• Locale sensitivity: English-speaking users receive SKILL_en.md automatically based on environment variables, while others get the default SKILL.md.
• Editable-install safe: Uses importlib.resources with a filesystem fallback to support both production and development installations.
• Idempotent operation: The force flag prevents accidental overwrites of user-customized skill files when set to False.
• Clean removal: The uninstall function mirrors the installation logic, ensuring complete removal across all detected frameworks.

Frequently Asked Questions

What AI agent frameworks does Agent Reach support?

Agent Reach supports OpenClaw, Claude Code, and the generic ~/.agents layout. The installation mechanism searches for framework-specific directories in ~/.openclaw/skills, ~/.claude/skills, and ~/.agents/skills, automatically installing to whichever locations exist on the system.

How do I force a fresh install of the skill?

By default, the CLI calls _install_skill(force=True), which overwrites existing files. If calling programmatically with force=False, the installation preserves any existing SKILL.md files, skipping the copy operation to prevent accidental loss of customizations.

Can I customize the skill files after installation?

Yes, but be aware that running agent-reach skill --install with the default force flag will overwrite your changes. To preserve customizations, either set force=False when calling programmatically or backup your modified SKILL.md and references/ files before reinstalling.

How does Agent Reach handle editable installs?

When installed in editable mode (pip install -e .), the importlib.resources approach may fail to locate files. The code detects this and falls back to Path(__file__).parent / "skill" to read the markdown files directly from the source tree, ensuring developers can test changes without reinstalling the package.

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