How Skill Registration Works for Different AI Agents in Agent Reach

Agent Reach registers itself as a discoverable skill by copying localized SKILL.md descriptors and reference documentation into platform-specific directories—supporting Generic .agents, OpenClaw, and Claude Code environments—via the agent-reach skill --install CLI command.

Agent Reach is an open-source tool that exposes its capabilities as a consumable skill for AI agents. Understanding how skill registration works for different AI agents in Agent Reach is essential for developers integrating the tool into heterogeneous agent environments. The registration system automatically detects your platform, respects locale preferences, and writes the necessary skill descriptors to the appropriate location.

Supported AI Agent Platforms

Agent Reach supports three distinct AI agent environments, each expecting skills in a specific location:

• Generic .agents – Any agent that reads the ~/.agents/skills directory. The expected path is ~/.agents/skills/agent-reach/SKILL.md.
• OpenClaw – Expects skills at ~/.openclaw/skills/agent-reach/SKILL.md. If the OPENCLAW_HOME environment variable is set, Agent Reach uses $OPENCLAW_HOME/.openclaw/skills/ instead.
• Claude Code – Expects skills at ~/.claude/skills/agent-reach/SKILL.md.

During installation, the system checks these locations in a specific priority order, selecting the first existing directory as the installation target.

The Skill Registration Workflow

The core registration logic resides in agent_reach/cli.py and is triggered through the skill sub-command. The process follows a strict sequence: command parsing, platform detection, locale resolution, and file deployment.

CLI Command Registration

The CLI parser registers the skill command with mutually exclusive --install and --uninstall flags. In agent_reach/cli.py (lines 104‑110), the argument parser defines this interface, ensuring users explicitly choose one operation mode.

Platform Detection and Priority

The _install_skill function iterates over a prioritized list of skill roots defined in lines 12‑22 of agent_reach/cli.py:

1. ~/.agents/skills (generic agents)
2. ~/.openclaw/skills (OpenClaw)
3. ~/.claude/skills (Claude Code)

If OPENCLAW_HOME is defined, its path is inserted at the front of this list. The system selects the first existing directory in this sequence. If none exist, it falls back to creating ~/.agents/skills/agent-reach (lines 34‑40).

Locale-Aware File Selection

Before copying files, the system determines which language variant to install. The _install_skill function checks environment variables in the following order (lines 53‑62):

• AGENT_REACH_LANG
• LC_ALL
• LC_MESSAGES
• LANG

If any of these indicate English (e.g., en_US.UTF-8), the installer selects SKILL_en.md. Otherwise, it defaults to SKILL.md.

Copying Skill Assets

The _copy_skill_dir function (lines 71‑99) handles the actual file operations:

1. Removes any previous installation (handling both normal directories and symlinks)
2. Creates the target agent-reach directory
3. Writes the selected SKILL.md file
4. Copies the entire references/ sub-directory containing detailed help documentation (e.g., references/search.md, references/social.md)

The skill package source lives under agent_reach/skill/ in the repository, containing the two language variants (SKILL.md and SKILL_en.md) and the reference materials.

Uninstalling the Skill

To remove the skill, running agent-reach skill --uninstall triggers the _uninstall_skill function (lines 44‑61). Unlike installation, which targets a single platform, uninstallation walks all possible locations in the priority list, deleting the entire agent-reach directory and reporting what was removed. This ensures cleanup across multiple platforms if the user previously installed the skill in different environments.

Skill Package Structure

The skill assets shipped with Agent Reach include:

Path	Purpose
agent_reach/skill/SKILL.md	Default language skill descriptor
agent_reach/skill/SKILL_en.md	English variant of the skill descriptor
agent_reach/skill/references/	Auxiliary markdown documentation referenced by the skill

These files are what AI agents load at runtime to understand Agent Reach's capabilities.

Code Examples

Install the skill for the first detected platform:

agent-reach skill --install

Force the English skill variant when your locale is non-English:

export LANG=en_US.UTF-8
agent-reach skill --install

Install into a custom OpenClaw home directory:

export OPENCLAW_HOME=$HOME/custom-openclaw
agent-reach skill --install

Uninstall from all platforms:

agent-reach skill --uninstall

Programmatic usage from Python:

from agent_reach.cli import _install_skill, _uninstall_skill

# Install the skill

_install_skill()

# Later, remove it from all locations

_uninstall_skill()

Summary

• Agent Reach supports three platforms: Generic .agents, OpenClaw, and Claude Code, each with specific directory expectations.
• The agent-reach skill --install command follows a priority order: generic agents first, then OpenClaw (respecting OPENCLAW_HOME), then Claude Code.
• Locale detection automatically selects SKILL_en.md or SKILL.md based on environment variables (AGENT_REACH_LANG, LC_ALL, LANG).
• The _copy_skill_dir function in agent_reach/cli.py (lines 71‑99) handles atomic replacement of skill files, including the references/ directory.
• Uninstallation cleans up all possible locations simultaneously via _uninstall_skill (lines 44‑61).

Frequently Asked Questions

Where does Agent Reach install its skill files?

Agent Reach installs to the first existing directory in its priority list: ~/.agents/skills/ (generic), ~/.openclaw/skills/ (OpenClaw), or ~/.claude/skills/ (Claude Code). If OPENCLAW_HOME is set, that location takes precedence. If none exist, it creates ~/.agents/skills/agent-reach/ as a fallback.

How does Agent Reach determine which language file to install?

The installer checks environment variables in this order: AGENT_REACH_LANG, LC_ALL, LC_MESSAGES, and LANG. If any indicate English (e.g., en_US.UTF-8), it copies SKILL_en.md; otherwise, it uses the default SKILL.md.

Can I install the skill for multiple platforms simultaneously?

No, a single agent-reach skill --install command targets only the first existing platform directory in the priority list. To install on a secondary platform, create the target directory manually (e.g., mkdir -p ~/.claude/skills) before running the install command, or set OPENCLAW_HOME to prioritize OpenClaw.

How do I completely remove the skill from my system?

Run agent-reach skill --uninstall. This executes _uninstall_skill, which walks all possible platform locations (generic, OpenClaw, and Claude Code) and deletes the agent-reach directory from each, ensuring complete removal regardless of where the skill was originally installed.

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