# How Reverse-Skill Implements Priority-Ordered Keyword Matching for Deterministic Routing

> Discover how reverse-skill's routing system uses priority-ordered keyword matching. It sorts rules by priority and executes the first script matching your hint for deterministic routing.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: internals
- Published: 2026-08-21

---

**The reverse-skill routing system implements priority-ordered keyword matching by loading [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), sorting rules by descending numeric priority values, and executing the first matching script where the normalized hint contains the rule's keyword.**

The open-source reverse-skill project routes user requests through a deterministic engine that relies on **priority-ordered keyword matching** to select the appropriate automation script. At the heart of this system lies a single JSON configuration file that defines routing rules with explicit priority values, ensuring specific keywords always override generic ones. This article examines the implementation details found in the `zhaoxuya520/reverse-skill` repository to explain how the engine guarantees consistent, reproducible routing decisions across Windows, Linux, and macOS platforms.

## Core Components of the Routing System

The routing architecture separates configuration from execution, storing the logic in two primary locations that work in tandem to resolve user hints to specific scripts.

### The Routing Configuration ([`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json))

The file [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) serves as the single source of truth for all routing decisions. Each entry in this JSON array defines a rule containing three critical fields: a `keyword` (or *hint* pattern) to match against incoming requests, a numeric `priority` value, and a `script` path pointing to the target automation file. According to the source code, the engine evaluates rules from highest to lowest priority, guaranteeing that the most specific match wins regardless of the rule's physical position in the file.

### Platform Entry Points and Documentation

The [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) file provides the human-readable specification for the routing flow, describing how the engine parses incoming hints and invokes platform-specific scripts. On Windows, the system executes `skills/scripts/master-route.ps1`, while Linux, macOS, and Kali systems use [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh). Both scripts implement the identical priority-ordered matching algorithm, ensuring cross-platform behavioral consistency.

## How Priority-Ordered Keyword Matching Works

The routing engine follows a four-step deterministic process to resolve every user request. This sequence ensures that **higher priority values always take precedence** over lower ones, creating a predictable hierarchy of rule specificity.

### 1. Hint Normalization

When a user issues a task, the incoming hint string undergoes immediate normalization. The engine converts the text to lowercase and trims surrounding quotation marks, ensuring that `Windows-AD`, `"windows-ad"`, and `WINDOWS-AD` all resolve to the same canonical form before matching begins.

### 2. Rule Loading and Sorting

The routing engine loads [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) into memory and sorts the rule array by the `priority` field in descending order (highest numeric value first). This pre-sorting operation is crucial because it allows the system to use a simple sequential scan rather than complex comparison logic during the hot path of request processing.

### 3. Sequential Keyword Scanning

With the rules sorted, the engine iterates through the array and performs a substring check for each rule:

```powershell

# Conceptual logic implemented in master-route.ps1 and master-route.sh

for rule in sorted_rules:
    if hint contains rule.keyword:
        execute rule.target_script
        break

```

Because the list is pre-sorted by priority, the first rule that matches the hint is automatically the *winning* rule. The engine executes the associated script immediately and terminates the search, preventing further evaluation of lower-priority matches.

### 4. Fallback Handling

If no specific rule matches the normalized hint, the system falls back to a default "catch-all" rule configured with the lowest priority value. This final rule routes the request to the generic router (`master-route.ps1` or [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh)), ensuring every request receives a handler even when no specific keyword matches.

## Platform-Specific Implementations

While the algorithm remains consistent, the concrete implementations differ between PowerShell and Bash environments to leverage native JSON parsing capabilities.

### Windows PowerShell Implementation

In `skills/scripts/master-route.ps1`, the routing logic utilizes PowerShell's `ConvertFrom-Json` cmdlet to ingest the configuration:

```powershell
$hint = $args[0].ToLower().Trim('"')
$rules = Get-Content -Raw "$PSScriptRoot/../config/routing.json" | ConvertFrom-Json
$sorted = $rules | Sort-Object -Property priority -Descending

foreach ($rule in $sorted) {
    if ($hint -like "*$($rule.keyword)*") {
        & $rule.script -Hint $hint
        break
    }
}

```

This snippet demonstrates the **sequential, priority-driven search** that underpins the Windows routing path, using PowerShell's native sorting and wildcard matching operators.

### Linux and macOS Bash Implementation

The Unix variant in [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) uses `jq` for JSON parsing and `sort` for ordering:

```bash
hint="${1,,}"
mapfile -t rules < <(jq -c '.[]' "$PWD/../config/routing.json" | sort -t: -k2 -nr)

for entry in "${rules[@]}"; do
    keyword=$(jq -r '.keyword' <<<"$entry")
    script=$(jq -r '.script' <<<"$entry")
    if [[ "$hint" == *"$keyword"* ]]; then
        "$script" --hint "$hint"
        break
    fi
done

```

Both implementations maintain identical semantics: sort by priority descending, iterate sequentially, execute on first match, and break.

## Design Benefits of Priority-Based Routing

The explicit priority system solves several critical routing challenges that emerge in extensible automation frameworks.

### Specificity vs. Generality

Keywords like `"windows-ad"` or `"apk-reverse"` are inherently more specific than generic terms such as `"reverse"`. By assigning higher priority values to specific patterns, the system prevents generic rules from "hijacking" requests that should be handled by specialized scripts. This hierarchical matching ensures that adding a new skill with precise targeting will always take precedence over existing, broader matches.

### Conflict Resolution Without Lexical Ordering

When two rules share overlapping keywords—for example, `"reverse-skill"` versus `"reverse-skill-go"`—the numeric priority explicitly resolves the conflict. Developers do not need to rely on the file's physical ordering or rename keywords to force precedence; they simply assign appropriate priority integers to establish the desired resolution order.

### Safe Extensibility

New skills can be added to [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) by appending a rule with an appropriate priority value. The routing engine automatically respects the ordering without requiring modifications to the core matching logic in `master-route.ps1` or [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh). This design decouples skill development from routing maintenance, allowing the ecosystem to grow without risking regression in existing routing behavior.

## Summary

- The reverse-skill routing system uses a centralized configuration in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) that defines keywords, priorities, and target scripts.
- Rules are sorted by descending numeric priority, then scanned sequentially to ensure the highest-priority matching rule executes first.
- Hint normalization (lowercasing and quote trimming) ensures case-insensitive matching across all platforms.
- Platform-specific entry points (`master-route.ps1` for Windows, [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) for Unix) implement identical priority-ordered matching algorithms.
- The priority system resolves conflicts between overlapping keywords and enables safe addition of new skills without modifying core routing code.

## Frequently Asked Questions

### What happens when two routing rules match the same keyword?

When multiple rules match the hint substring, the system executes only the rule with the highest numeric priority value. Because [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) is sorted by priority before scanning begins, the first match encountered is always the highest-priority match, and the engine breaks the loop immediately after execution.

### How does the system handle case sensitivity in keyword matching?

The routing engine normalizes all hints to lowercase before comparison, and keywords in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) should be defined in lowercase to match. This normalization occurs in both the PowerShell (`ToLower()`) and Bash (`${1,,}`) implementations, ensuring consistent behavior whether the user types `Windows-AD`, `WINDOWS-AD`, or `"windows-ad"`.

### Where is the routing configuration stored in reverse-skill?

All routing rules reside in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) relative to the repository root. This single file acts as the source of truth for both the Windows PowerShell router (`skills/scripts/master-route.ps1`) and the Unix Bash router ([`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh)), as documented in [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md).

### Can I add new routing rules without modifying the core scripts?

Yes. You can extend the system by adding new entries to [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) with unique priority values. The master routing scripts load and sort this configuration dynamically at runtime, so new skills integrate automatically without requiring changes to the PowerShell or Bash code.