How Skill Registration Works for OpenClaw and Claude Code in Agent-Reach

Agent Reach registers its AI agent capabilities by copying localized SKILL.md documentation into ~/.openclaw/skills, ~/.claude/skills, and ~/.agents/skills via the agent-reach skill --install command, enabling automatic discovery by OpenClaw and Claude Code without manual configuration.

The Panniantong/Agent-Reach repository implements a deterministic skill registration system that bridges the gap between the agent-reach CLI and AI agent environments. When you invoke the installation command, the system detects your locale, selects the appropriate skill documentation, and deploys files to agent-specific configuration directories. This guide examines the internal mechanics of this process as implemented in agent_reach/cli.py.

Locale-Aware Skill Selection

Before copying any files, the _install_skill() helper determines which markdown documentation to deploy based on environment variables. It inspects AGENT_REACH_LANG, LC_ALL, LC_MESSAGES, and LANG in sequence. If any indicate an English locale, the installation uses SKILL_en.md; otherwise, it falls back to the default SKILL.md (Chinese). This logic ensures that agents receive instructions in the user's preferred language without manual file selection.

Target Directory Resolution

The registration system searches for existing agent configuration directories in a specific priority order:

• ~/.agents/skills (generic agents, highest priority)
• ~/.openclaw/skills (OpenClaw)
• ~/.claude/skills (Claude Code)

If the OPENCLAW_HOME environment variable is set, its corresponding .openclaw/skills path is inserted at the front of the search list. This resolution strategy allows the same installation command to service multiple agent types simultaneously, ensuring that OpenClaw and Claude Code can both locate the skill files without conflicting configurations.

The Installation Process

When you run agent-reach skill --install, the _install_skill() function executes a six-step workflow:

1. Load source files – Reads the selected SKILL.md from package resources using importlib.resources.files("agent_reach"), with an editable-install fallback that resolves relative to agent_reach/cli.py.

2. Discover agent directories – Walks the candidate paths listed above to identify which agent environments exist on the system.

3. Copy skill documentation – For each valid directory, _copy_skill_dir() creates (or overwrites) an agent-reach subdirectory. It writes the locale-specific SKILL.md and recursively copies all .md files from skill/references/ into a matching references/ subfolder.

4. Report status – Emits confirmation messages such as "Skill installed for OpenClaw" or "Skill already installed for Claude Code, preserving existing files".

5. Fallback creation – If none of the standard agent directories exist, the system creates ~/.agents/skills/agent-reach as a default installation location.

6. Reference integrity – Ensures auxiliary documentation in the references/ folder is available alongside the main skill definition.

# Install for all detected agents (OpenClaw, Claude Code, generic)

agent-reach skill --install

# Force Chinese documentation regardless of system locale

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

Removing Registered Skills

The uninstall counterpart _uninstall_skill() performs a reverse lookup using the same directory list. It removes the agent-reach subdirectory from each valid agent path, cleaning up both the main SKILL.md and any reference documentation without affecting other installed skills.

# Remove from all agent configurations

agent-reach skill --uninstall

Programmatic API Access

You can trigger registration directly from Python without shelling out to the CLI. This is useful for build scripts or automated development environment setup:

from agent_reach.cli import _install_skill, _uninstall_skill

# Register with all detected agent directories

_install_skill()

# Later cleanup

_uninstall_skill()

Key Implementation Files

The skill registration logic resides entirely within agent_reach/cli.py, which implements the _install_skill(), _copy_skill_dir(), and _uninstall_skill() helpers. The skill content itself ships as two localized variants—agent_reach/skill/SKILL_en.md and agent_reach/skill/SKILL.md—augmented by optional reference documents in agent_reach/skill/references/.

Summary

• Command-driven registration: Use agent-reach skill --install to deploy documentation to ~/.openclaw/skills, ~/.claude/skills, and ~/.agents/skills.
• Automatic locale detection: The system selects SKILL_en.md for English locales (via LANG, LC_ALL, etc.) or defaults to SKILL.md.
• Environment override: Set OPENCLAW_HOME to prepend a custom OpenClaw skills directory to the search path.
• Idempotent installation: Running install multiple times updates existing files or preserves them if unchanged, with a fallback to ~/.agents/skills when no agent directories exist.
• Clean removal: The --uninstall flag removes the agent-reach subdirectory from all detected locations.

Frequently Asked Questions

What happens if OpenClaw and Claude Code are not installed?

If neither ~/.openclaw/skills nor ~/.claude/skills exists, the _install_skill() function falls back to creating ~/.agents/skills/agent-reach as a default location. This ensures the skill is preserved for future agent installation or manual configuration.

Can I install the skill to a custom directory?

While the CLI does not accept arbitrary paths, you can influence OpenClaw's target by setting the OPENCLAW_HOME environment variable, which prepends $OPENCLAW_HOME/.openclaw/skills to the search list. For other locations, use the Python API and manually copy the files loaded via importlib.resources.files("agent_reach").

How does the locale detection prioritize language settings?

The _install_skill() function checks variables in the order: AGENT_REACH_LANG, LC_ALL, LC_MESSAGES, then LANG. If any of these contain the substring en (case-insensitive), the installation selects SKILL_en.md. This allows explicit override via AGENT_REACH_LANG even when system locale differs.

Is it safe to run the install command multiple times?

Yes. The _copy_skill_dir() helper overwrites existing files in the agent-reach subdirectory, ensuring the latest documentation is present while preserving the directory structure. The CLI reports "already installed" when files match, preventing unnecessary writes while maintaining idempotency.

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