How Agent-Reach Manages Skill Installation for Different AI Agents

Agent-Reach installs reusable skills across OpenClaw, Claude Code, and generic agent environments by copying packaged assets from agent_reach/skill/ into platform-specific directories under ~/.agents/skills, ~/.openclaw/skills, and ~/.claude/skills.

Agent-Reach provides a unified mechanism for distributing capabilities to AI agents through a portable skill package. The system enables seamless integration with multiple agent platforms by abstracting the installation logic into a single CLI command. This article examines how the _install_skill and _uninstall_skill functions in [agent_reach/cli.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) handle cross-platform skill deployment.

Supported Agent Platforms

Agent-Reach targets three distinct agent ecosystems with prioritized installation paths:

• Generic agents (.agents): ~/.agents/skills
• OpenClaw: ~/.openclaw/skills
• Claude Code: ~/.claude/skills

The installation routine checks these directories in priority order, ensuring the skill is available wherever the user has existing agent configurations.

How Skill Installation Works

The _install_skill function orchestrates the deployment process through four distinct phases:

Locating Skill Resources

The installer first attempts to load bundled resources using importlib.resources.files("agent_reach").joinpath("skill"). If this fails—typically during editable installs or development environments—it falls back to the local skill directory adjacent to the source file【line 399‑404】.

Reading Skill Metadata

The helper function _read_skill_markdown selects the appropriate documentation, preferring a locale-specific variant (e.g., SKILL.zh.md) over the default SKILL.md【line 376‑383】. This markdown file serves as the primary interface definition for the agent consuming the skill.

Resolving Target Directories

The system builds a candidate list of installation paths, prioritizing the generic .agents location, followed by OpenClaw and Claude Code directories【line 428‑435】. For each existing directory, the installer creates (or symlinks) a subdirectory named agent-reach.

Copying and Cleaning Assets

Before writing new files, the installer clears existing agent-reach directories to prevent stale artifacts【line 389‑397】. It then copies the markdown documentation and any contents from the references/ subdirectory into the target location【line 383‑424】. If none of the standard directories exist, the system creates ~/.agents/skills/agent-reach as a fallback to ensure the skill remains available【line 453‑456】.

Automatic Installation Triggers

Skill installation is not limited to explicit CLI commands. The system automatically invokes _install_skill during:

1. Full installation runs (agent-reach install)
2. Diagnostic checks (agent-reach doctor)

This ensures the skill remains synchronized with the core package unless explicitly disabled by the user【line 1492‑1493】.

Uninstalling Skills

The _uninstall_skill function mirrors the installation logic by iterating through the same three platform directories. It removes the agent-reach subdirectory from each location, handling both physical directories and symbolic links, and reports the status of each removal operation【line 466‑499】.

# Remove the skill from all supported agents

python -m agent_reach.cli skill --uninstall

Practical Usage Examples

Install the skill across all detected agent environments:

python -m agent_reach.cli skill --install

Expected output:

Installing skill for OpenClaw → ~/.openclaw/skills/agent-reach
Installing skill for Claude Code → ~/.claude/skills/agent-reach
Installing skill for generic agents → ~/.agents/skills/agent-reach

Programmatically copy the skill directory (replicating the CLI behavior):

import shutil
import os
from pathlib import Path

src = Path(__file__).parent / "skill"
dst = os.path.expanduser("~/.agents/skills/agent-reach")

if src.exists():
    shutil.copytree(src, dst, dirs_exist_ok=True)

Summary

• Agent-Reach deploys skills to three platforms: generic .agents, OpenClaw, and Claude Code.
• The _install_skill function in agent_reach/cli.py uses importlib.resources to locate packaged assets, then copies them to platform-specific directories under the user's home directory.
• Installation clears existing directories first to prevent stale files, with automatic fallback creation if no agent directories exist.
• The _uninstall_skill function removes the agent-reach directory from all known locations, handling both regular directories and symlinks.
• Skills auto-install during agent-reach install and doctor commands, ensuring continuous synchronization.

Frequently Asked Questions

Where does Agent-Reach install skill files by default?

Agent-Reach prioritizes ~/.agents/skills for generic agents, followed by ~/.openclaw/skills for OpenClaw and ~/.claude/skills for Claude Code. If none exist, it creates ~/.agents/skills/agent-reach to ensure the skill is always available.

How does Agent-Reach handle existing skill installations?

Before copying new assets, the _install_skill function clears any existing agent-reach directory in the target location【line 389‑397】. This prevents stale documentation or reference files from interfering with the current version.

Can the skill be installed manually without using the CLI?

Yes. The skill assets reside in the agent_reach/skill/ directory within the package. You can manually copy this directory (including SKILL.md and the references/ folder) to any supported agent's skills directory, typically located at ~/.agents/skills/agent-reach.

What triggers automatic skill installation in Agent-Reach?

Beyond the explicit skill --install command, Agent-Reach automatically installs skills when running agent-reach install or agent-reach doctor【line 1492‑1493】. This ensures the skill package remains synchronized with the core tool unless explicitly disabled.

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