How Agent Reach Skill Registration Works with OpenClaw and .agents Directories

Agent Reach registers itself as a skill by detecting compatible directories like ~/.agents/skills or ~/.openclaw/skills, copying its skill package from agent_reach/skill/, and exposing a Python entry point through manifest.json that any compatible AI agent can invoke.

Agent Reach, available in the Panniantong/Agent-Reach repository, functions as both a standalone CLI tool and an installable skill for AI coding agents. The Agent Reach skill registration process uses a file-system-based approach that works seamlessly with OpenClaw, Claude Code, and any agent supporting the .agents skill format, requiring no complex configuration or platform-specific binaries.

The Three-Step Registration Process

The registration logic in agent_reach/cli.py orchestrates a three-step deployment that makes the tool available as a native agent capability.

Step 1: Detecting the Target Skill Directory

The CLI examines three possible installation locations in order of priority:

1. ~/.agents/skills – The generic location used by any agent following the .agents convention.
2. ~/.openclaw/skills – The native OpenClaw skill folder.
3. ~/Library/Application Support/Claude Code/skills – The Claude Code skill storage path.

Whichever directory exists first becomes the install target. If none exist, the CLI creates ~/.agents/skills as a fallback, ensuring the skill works out-of-the-box for future agents reading that location.

Step 2: Deploying the Skill Package

Once the target is identified, the CLI copies the entire skill package from agent_reach/skill/ into the chosen directory. The package maintains this structure:

<skill-root>/agent-reach/
    ├─ manifest.json
    ├─ __init__.py
    └─ … (support modules)

This operation preserves the relative file structure, placing the agent-reach folder containing manifest.json and agent_reach/skill/__init__.py directly into the agent's skills directory.

Step 3: Configuring the Entry Point

The manifest.json file declares the skill's metadata and references the module's CLI entry point at agent_reach.cli:main. When OpenClaw or a .agents-compatible agent loads the skill, it imports this entry point and can invoke commands like agent-reach install or agent-reach doctor as native agent actions. This creates a thin wrapper around the same Python package that powers the standalone agent-reach command-line tool.

Cross-Compatibility Architecture

Agent Reach satisfies both OpenClaw and generic .agents runtimes through three design principles:

• Unified layout: Both ecosystems expect a folder named after the skill containing a manifest.json. By installing to the same structure, Agent Reach works with both without duplication.
• Platform-agnostic entry point: The manifest points to a pure-Python entry point (agent_reach.cli:main), eliminating the need for platform-specific binaries. The agent runs the Python code inside its sandboxed environment.
• Graceful fallback: If only the generic .agents directory exists, the skill installs there and activates immediately. OpenClaw users benefit from the native ~/.openclaw/skills path, which the runtime monitors for new skill folders.

Installing Agent Reach as a Skill

To register Agent Reach within your AI agent environment, run the installation command:

agent-reach install --env=auto

The CLI automatically detects the appropriate skill directory, copies the necessary files, and prints a confirmation:

✅ Skill installed to ~/.openclaw/skills/agent-reach (OpenClaw)

If your OpenClaw profile disables exec permissions, the CLI warns you to enable them first before the skill can function.

Summary

• Agent Reach skill registration uses a file-system-based approach requiring no complex configuration.
• The CLI in agent_reach/cli.py prioritizes ~/.agents/skills, then ~/.openclaw/skills, then Claude Code paths, creating the generic path as a fallback.
• The skill package in agent_reach/skill/ includes manifest.json, which references agent_reach.cli:main as the entry point.
• This architecture supports both OpenClaw and any .agents-compatible agent through a unified directory structure and pure-Python entry point.

Frequently Asked Questions

What is the .agents directory convention?

The .agents directory convention is a file-system standard where AI coding agents look for skills in a ~/.agents/skills folder. Each skill resides in its own subdirectory containing a manifest.json file that declares the skill's entry point and capabilities. Agent Reach supports this convention alongside OpenClaw's native directory structure.

Why does Agent Reach create ~/.agents/skills if no directories exist?

The CLI creates ~/.agents/skills as a fallback to ensure forward compatibility with any future AI agent that follows the .agents specification. This allows the skill to work out-of-the-box immediately after installation, even if the user has not yet installed OpenClaw or Claude Code.

How does the manifest.json file enable skill execution?

The manifest.json file in agent_reach/skill/ declares the skill name as agent-reach and specifies the Python entry point agent_reach.cli:main. When an agent like OpenClaw loads the skill, it imports this entry point, allowing the agent to invoke the CLI commands directly within its sandboxed environment.

Can I use Agent Reach as a skill without installing OpenClaw?

Yes. Agent Reach works with any AI coding agent that supports the .agents skill format, including Claude Code and potentially others. The registration process automatically detects the appropriate directory for your specific agent environment, defaulting to the generic .agents path when OpenClaw is not present.

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