# What Is the SKILL.md File in Agent Reach and How Does It Route Requests?

> Discover the SKILL.md file in Agent Reach. Learn how this routing manifest maps user intents to CLI commands, defining triggers and routing without code edits for efficient request handling.

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

---

**The [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) file acts as a declarative routing manifest that maps user intents to specific CLI commands by defining trigger keywords, a routing table, and reference documents without requiring code changes.**

In the *Agent Reach* framework, [`agent_reach/skill/SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/skill/SKILL.md) serves as the central configuration hub that enables AI agents to understand natural language requests and translate them into executable platform-specific actions. This file eliminates hard-coded routing logic by keeping the decision-making data in a readable Markdown format that can be updated simply by editing text.

## Understanding the SKILL.md Structure

The [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) file organizes routing logic into distinct sections that agents parse at runtime to determine how to handle incoming requests.

### Metadata and Triggers

The file begins with a **metadata block** (YAML front-matter) that declares the skill name, description, and the *open-claw* homepage. Following this, the **triggers** section defines keyword groups—including `research`, `search`, `social`, `career`, `dev`, `web`, `video`, and `finance`—that the skill recognizes in user requests. Each group contains language-specific aliases supporting both Chinese and English variations.

### Routing Table

Located in the Markdown section *“路由表”* (approximately lines 60-70), the **routing table** maps user intents to reference documents that hold concrete command sets. For example, a trigger match for "social" routes to [`references/social.md`](https://github.com/Panniantong/Agent-Reach/blob/main/references/social.md), while "search" routes to [`references/search.md`](https://github.com/Panniantong/Agent-Reach/blob/main/references/search.md).

### Command Categories

The manifest distinguishes between two execution types:

- **Zero-configuration commands**: Ready-to-run CLI snippets for platforms requiring no authentication (e.g., Exa web search, Jina Reader, GitHub CLI)
- **Authenticated-backend commands**: Operations that require a logged-in backend, selected based on the output of `agent-reach doctor --json`

## How Agents Use SKILL.md to Route Requests

When an agent receives a user request, it follows a four-step resolution process defined in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py):

1. **Scan for trigger words**: The agent parses the request against the trigger definitions in [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) (lines 20-38) to identify intent
2. **Select the matching category**: Based on detected keywords (e.g., `social` → `Twitter`), the agent determines the target platform
3. **Lookup the reference file**: The agent consults the routing table to locate the specific reference document (e.g., [`references/social.md`](https://github.com/Panniantong/Agent-Reach/blob/main/references/social.md))
4. **Execute the CLI command**: The agent runs the concrete command defined in the reference file, using the active backend reported by `agent-reach doctor`

This declarative approach allows the system to support new platforms by updating Markdown text rather than modifying Python implementation files.

## Implementation Examples

### Detecting Intent and Selecting Backends

The following Python code demonstrates how the agent parses [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) at runtime to route requests:

```python
from agent_reach.skill import SKILL  # SKILL.md content parsed at runtime

def route_request(user_input: str):
    # 1️⃣ Find matching trigger

    intent = SKILL.match_trigger(user_input)        # returns e.g. "social"

    # 2️⃣ Resolve the reference doc

    ref_doc = SKILL.routing[intent]                # e.g. "references/social.md"

    # 3️⃣ Load the concrete command

    command = SKILL.load_command(ref_doc, user_input)
    # 4️⃣ Run the command (agent executes the CLI string)

    return command

```

### Running Zero-Configuration Searches

For generic search requests requiring no authentication, the agent automatically selects the Exa web search backend:

```bash

# Exa web search - automatically selected for "search" requests

mcporter call 'exa.web_search_exa(query: "agent reach", numResults: 5)'

```

### Executing Authenticated Platform Commands

For platforms requiring authentication, the agent first verifies the active backend:

```bash

# ① Run diagnostics to identify active backend

agent-reach doctor --json

# ② Execute using the reported backend (e.g., twitter-cli)

twitter search "Agent Reach" -n 10

```

## Key Files in the Routing System

The declarative routing architecture relies on the following components:

- **[`agent_reach/skill/SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/skill/SKILL.md)**: Master routing manifest containing triggers, routing table, and operational rules
- **`agent_reach/skill/references/*.md`**: Detailed command recipes for each category (e.g., [`references/social.md`](https://github.com/Panniantong/Agent-Reach/blob/main/references/social.md), [`references/search.md`](https://github.com/Panniantong/Agent-Reach/blob/main/references/search.md))
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)**: CLI entry point that parses arguments and invokes routing logic
- **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)**: Diagnostics engine reporting active backends; its JSON output informs the routing layer
- **[`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py)**: Core implementation that reads [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) and dispatches to appropriate channels

## Summary

- **[`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md)** functions as the central routing manifest in [`agent_reach/skill/SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/skill/SKILL.md), defining how agents interpret natural language
- **Trigger keywords** (research, search, social, etc.) map user intents to platform categories without code changes
- **Reference documents** in `references/` contain the actual CLI commands, keeping command logic separate from routing logic
- **Zero-config and authenticated commands** are handled differently based on backend status reported by `agent-reach doctor`
- **Declarative updates** allow adding new platforms by editing Markdown files rather than modifying Python source code

## Frequently Asked Questions

### What makes SKILL.md different from traditional routing code?

Unlike traditional hard-coded routing logic found in Python files, [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) uses a declarative Markdown format that separates intent recognition from command execution. This allows non-developers to modify routing behavior by adding trigger keywords or reference documents without touching [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) or other implementation files.

### How does the agent know which backend to use for authenticated commands?

The agent consults the output of `agent-reach doctor --json` (implemented in [`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)) to determine which backend is currently active and authenticated for a given platform. The routing table in [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md) then identifies the appropriate reference document containing backend-specific command syntax.

### Can I add support for a new platform without modifying Python code?

Yes. To support a new platform like "FooChat", you would add its aliases to the `triggers` section of [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md), create a new routing table entry mapping the intent to [`references/foochat.md`](https://github.com/Panniantong/Agent-Reach/blob/main/references/foochat.md), and write the concrete commands in that reference file. The agent immediately recognizes the new platform upon the next request without requiring code deployment.

### Where are the trigger keywords defined in SKILL.md?

The trigger keywords are defined in the `triggers` section of [`SKILL.md`](https://github.com/Panniantong/Agent-Reach/blob/main/SKILL.md), approximately spanning lines 20-38, where each category (such as `social`, `search`, or `dev`) lists language-specific aliases in both English and Chinese. These triggers enable the agent to categorize diverse user inputs into specific routing intents.