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

The reverse-skill routing system implements priority-ordered keyword matching by loading 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)

The file 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 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. 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 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:

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

$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 uses jq for JSON parsing and sort for ordering:

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 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. 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 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 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 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 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 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), as documented in 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 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.

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