# How reverse-skill Routes Cybersecurity Tasks: A Complete Guide to the Deterministic Routing Engine

> Learn how reverse-skill routes cybersecurity tasks using its deterministic engine. Discover how it maps hints to skills via regex patterns for efficient security operations.

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

---

**reverse-skill implements a deterministic, score-based routing engine that maps user-provided task hints to specific skill modules by matching regex keyword patterns defined in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), falling back to general reverse‑engineering when no patterns match.**

The zhaoxuya520/reverse-skill repository provides a structured approach to organizing complex cybersecurity workflows. Understanding how reverse-skill routes cybersecurity tasks requires examining its three-layer architecture, which separates routing logic from documentation while maintaining strict consistency through automated verification scripts.

## The Three-Layer Routing Architecture

The routing system processes every task hint through distinct phases, from initial invocation to final skill selection.

### Entry Points: Platform-Specific master-route Scripts

When a hint contains security-related keywords, the platform-specific `master-route` script serves as the execution gateway. According to [`AGENTS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md), the invocation differs by operating system:

- **Windows**: `powershell … -File skills/scripts/master-route.ps1 -Hint "<task>"`
- **Linux/macOS/Kali**: `bash skills/scripts/master-route.sh --hint "<task>"`

These scripts load the routing configuration and initiate the matching process against the JSON rule set.

### Routing Logic: The JSON Configuration Engine

All routing rules reside in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), the single source of truth for the system. Each route entry (e.g., `R1`, `R2`) contains three critical components:

- **label**: Human-readable identification of the security domain
- **skill**: Path to the corresponding markdown file containing implementation details
- **keywords**: Array of regex patterns including `must`, `exclude`, and `mustAll` rules

The engine scans the supplied hint against every `must` pattern while respecting exclusion criteria. When multiple routes match, the system employs a scoring mechanism that awards one point per matched rule.

### Prioritization and Conflict Resolution

After scoring, the engine selects the route with the highest point total. If two routes achieve identical scores, the order defined in the `priority` array within [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) resolves the tie. When no patterns match the input hint, the system defaults to route `R0` (General reverse‑engineering).

## Routing Flow Visualization

The complete routing flow follows this deterministic path:

```

User hint → master-route script → load routing.json
          → keyword matching → score each route
          → pick highest-scoring route (or fallback) → launch skill markdown

```

This design isolates routing decisions from implementation details, allowing skill directories like [`apk-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/apk-reverse/SKILL.md) to focus exclusively on technical content while the JSON configuration drives selection logic.

## Practical Usage Examples

Running task hints varies by platform but follows consistent invocation patterns.

On Linux and macOS:

```bash

# Route a request to APK reverse analysis

bash skills/scripts/master-route.sh --hint "decode apk and bypass certificate pinning"

```

On Windows:

```powershell

# Route a request to API security scanning

powershell -NoProfile -ExecutionPolicy Bypass `
    -File skills/scripts/master-route.ps1 -Hint "test graphql endpoint for injection"

```

### Programmatic Implementation

The following Python pseudo-code demonstrates the core matching algorithm as implemented in the `reverse-skill` source:

```python
import json, re, subprocess, sys

# Load routing table

with open("skills/config/routing.json") as f:
    routing = json.load(f)

def match_route(hint):
    scores = {}
    for rid, data in routing["routes"].items():
        score = 0
        for kw in data["keywords"]:
            must = kw.get("must")
            exclude = kw.get("exclude")
            must_all = kw.get("mustAll")
            if must and not re.search(must, hint, re.I):
                continue
            if exclude and re.search(exclude, hint, re.I):
                continue
            if must_all:
                if not all(re.search(p, hint, re.I) for p in must_all):
                    continue
            score += 1
        if score:
            scores[rid] = score
    if not scores:
        return routing["fallbackId"]
    # Highest score, then priority order

    best = max(scores, key=lambda k: (scores[k],
        -routing["priority"].index(k)))
    return best

hint = " ".join(sys.argv[1:])
route_id = match_route(hint)
skill_md = routing["routes"][route_id]["skill"]
print(f"Selected route {route_id}: {skill_md}")

```

## Maintaining Routing Coherence

The repository includes verification scripts to ensure [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) remains synchronized with documentation:

- **`verify-routing-coherence.ps1`**: Validates that the priority list in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) matches the order defined in [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md)
- **[`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh)**: Executes comprehensive routing tests to verify correct pattern matching for each defined route

Run the coherence check on Linux systems with:

```bash
bash skills/scripts/verify-routing-coherence.sh

```

## Summary

- **reverse-skill** routes cybersecurity tasks through a deterministic, score-based engine defined in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)
- Platform-specific **master-route** scripts (`master-route.ps1` for Windows, [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) for Unix) serve as entry points
- The routing engine matches hints against regex patterns using `must`, `exclude`, and `mustAll` rules, awarding one point per match
- Ties resolve using the `priority` array order; unmatched hints fall back to route **R0** (General reverse‑engineering)
- Verification scripts ensure routing logic remains consistent with human-readable documentation in [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md)

## Frequently Asked Questions

### What file contains the routing rules for reverse-skill?

All routing rules reside in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). This single source of truth defines each route's label, associated skill markdown file, keyword patterns, priority order, and fallback configuration. The JSON structure separates routing logic from the skill implementation documents stored in directories like [`apk-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/apk-reverse/SKILL.md).

### How does reverse-skill handle ambiguous task hints?

When multiple routes match a hint, the engine calculates a score by counting matched keyword patterns. The route with the highest score wins. If two routes achieve identical scores, the system consults the `priority` array in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) to break the tie, selecting the route that appears earlier in the list.

### What happens when no routing rules match the input?

If the hint fails to match any defined patterns, the system defaults to route **R0**, which corresponds to General reverse‑engineering. This fallback ensures that even vague or novel cybersecurity tasks receive relevant guidance rather than failing silently.

### How can I verify that my routing configuration is correct?

Execute the platform-appropriate verification script. On Linux or macOS, run `bash skills/scripts/verify-routing-coherence.sh` to check that [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) aligns with [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md). For comprehensive functional testing, use `bash skills/scripts/test-routing.sh` to validate that specific hints correctly trigger their intended routes.