How Agent Reach Registers Its Skill with Different AI Agents: A Complete Technical Guide

Agent Reach registers its skill with OpenClaw, Claude Code, and the generic .agents framework by copying skill definition files into each agent's designated skills directory via the agent-reach skill --install CLI command.

The open-source Agent‑Reach project (available at Panniantong/Agent-Reach) provides a cross-platform skill that AI agents can consume to extend their capabilities. Understanding how the Agent Reach skill installation system works helps developers customize deployments and troubleshoot integration issues across different AI ecosystems.

The CLI Entry Point for Skill Registration

The registration flow begins in agent_reach/cli.py, where the skill sub-command is defined. Lines 119–124 register the command with the argument parser, and when --install is supplied, execution routes through _cmd_skill to the private function _install_skill at line 198.

# From agent_reach/cli.py, lines 119-124 (simplified structure)

parser.add_argument("skill", help="Manage Agent Reach skill")
parser.add_argument("--install", action="store_true", help="Install skill to agents")
parser.add_argument("--uninstall", action="store_true", help="Remove skill from agents")

# Routes to _cmd_skill → _install_skill (line 198)

How _install_skill Targets Multiple AI Agents

The core installation logic in _install_skill (lines 13–34) follows a priority-based directory strategy to ensure broad compatibility without requiring explicit agent selection.

Step 1: Locale-Aware Skill File Selection

Before copying, the function selects the appropriate skill definition based on system locale (lines 19–33):

• English locale detected → Uses SKILL_en.md
• All other locales → Falls back to SKILL.md

Both files reside in agent_reach/skill/ and contain the structured commands, configuration schema, and reference documentation that AI agents parse.

Step 2: Priority-Ordered Target Directories

The function builds a prioritized list of candidate directories at lines 85–90:

Priority	Directory	Target AI Agent
1	~/.agents/skills	Generic ".agents" framework
2	~/.openclaw/skills	OpenClaw
3	~/.claude/skills	Claude Code

If the OPENCLAW_HOME environment variable is set, its custom path is prepended to this list (lines 92–96), allowing non-standard OpenClaw installations.

Step 3: Directory Copying with _copy_skill_dir

For each existing directory in the priority list, _copy_skill_dir (lines 41–80) performs:

1. Creates a subfolder named agent-reach/
2. Copies the selected SKILL.md file
3. Recursively copies the entire references/ directory tree

Existing installations are preserved by default. Pass force=True to overwrite (lines 44–46).

Step 4: Fallback Directory Creation

If none of the known directories exist, _install_skill creates ~/.agents/skills/agent-reach as a default location and installs there (lines 110–118). This ensures the skill is always installed somewhere, even on fresh systems.

Skill Content Structure

The actual capability definitions consumed by AI agents live in:

• agent_reach/skill/SKILL.md — Default skill definition
• agent_reach/skill/SKILL_en.md — English-localized variant
• agent_reach/skill/references/ — Supplemental markdown documentation

These files use standard AI-agent skill formats that describe available commands, required parameters, and contextual help that agents surface to users.

Uninstalling the Skill

The counterpart command agent-reach skill --uninstall invokes _uninstall_skill (lines 24–38), which removes the agent-reach folder from every known skill directory. This ensures clean removal across all previously targeted agents.

Practical Usage Examples

Install for All Supported Agents

agent-reach skill --install

Custom OpenClaw Installation Path

export OPENCLAW_HOME=/opt/custom/openclaw
agent-reach skill --install

# The script prepends $OPENCLAW_HOME/skills to the priority list

Force Overwrite Existing Installation

from agent_reach.cli import _install_skill

# Overwrite any existing skill files

_install_skill(force=True)

Programmatic Uninstall

from agent_reach.cli import _uninstall_skill

# Remove from all detected agent directories

_uninstall_skill()

Key Implementation Files

File	Purpose
agent_reach/cli.py	CLI definition, _install_skill(), _uninstall_skill()
agent_reach/skill/SKILL.md	Default skill definition
agent_reach/skill/SKILL_en.md	English-localized skill definition
agent_reach/skill/references/	Reference documentation bundle

Summary

Agent Reach achieves cross-agent compatibility through a simple, file-system-based registration approach:

• Single command: agent-reach skill --install handles all supported agents
• Priority targeting: Checks .agents/, openclaw/, and claude/ directories in order
• Locale awareness: Automatically selects translated skill definitions when available
• Non-destructive by default: Preserves existing installations unless force=True
• Environment customization: OPENCLAW_HOME overrides standard OpenClaw paths

Frequently Asked Questions

What AI agents are officially supported by Agent Reach?

Agent Reach supports OpenClaw, Claude Code, and any AI agent implementing the generic ".agents" framework specification. The registration system targets the standard skill directories for each: ~/.openclaw/skills, ~/.claude/skills, and ~/.agents/skills respectively.

Can I install the skill to only one specific agent?

Not directly through CLI flags—the _install_skill function iterates through all existing directories. However, you can achieve agent-specific installation by ensuring only that agent's directory exists before running the command, or by setting OPENCLAW_HOME to isolate OpenClaw targeting.

Where does Agent Reach install the skill if no agent directories exist?

The fallback logic in lines 110–118 of agent_reach/cli.py creates ~/.agents/skills/agent-reach as the default location. This ensures the skill is installed even on systems without any pre-configured AI agents.

Is the skill installation persistent across Agent Reach updates?

Yes, but with caveats. The skill files are copied at installation time and are not automatically updated when Agent Reach itself upgrades. Re-run agent-reach skill --install with force=True (or the --force CLI equivalent) to refresh with the latest skill definitions.

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