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

> Discover how Agent Reach skill registration works with OpenClaw and .agents directories. Learn about detecting compatible directories, copying skill packages, and exposing Python entry points for agent invocation.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-15

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/manifest.json) and [`agent_reach/skill/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/skill/__init__.py) directly into the agent's skills directory.

### Step 3: Configuring the Entry Point

The [`manifest.json`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/manifest.json) file enable skill execution?

The [`manifest.json`](https://github.com/Panniantong/Agent-Reach/blob/main/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.