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

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 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 (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), 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 — The default language version
• 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 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:

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:

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 and SKILL_en.md based on locale.getdefaultlocale().
• The _install_skill function in 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, the installer checks locale.getdefaultlocale() during the selection phase. If the returned locale starts with en_, the system copies skill/SKILL_en.md; otherwise, it uses the default 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 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.

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