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

The 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 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 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, while "search" routes to 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:

1. Scan for trigger words: The agent parses the request against the trigger definitions in 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)
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 at runtime to route requests:

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:

# 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:

# ① 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: 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, references/search.md)
• agent_reach/cli.py: CLI entry point that parses arguments and invokes routing logic
• agent_reach/doctor.py: Diagnostics engine reporting active backends; its JSON output informs the routing layer
• agent_reach/core.py: Core implementation that reads SKILL.md and dispatches to appropriate channels

Summary

• SKILL.md functions as the central routing manifest in 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 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 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) to determine which backend is currently active and authenticated for a given platform. The routing table in 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, create a new routing table entry mapping the intent to 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, 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.

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