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

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

# Route a request to APK reverse analysis

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

On Windows:

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

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 remains synchronized with documentation:

• verify-routing-coherence.ps1: Validates that the priority list in routing.json matches the order defined in MASTER-ROUTING.md
• 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 skills/scripts/verify-routing-coherence.sh

Summary

• reverse-skill routes cybersecurity tasks through a deterministic, score-based engine defined in skills/config/routing.json
• Platform-specific master-route scripts (master-route.ps1 for Windows, 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

Frequently Asked Questions

What file contains the routing rules for reverse-skill?

All routing rules reside in 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.

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 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 aligns with MASTER-ROUTING.md. For comprehensive functional testing, use bash skills/scripts/test-routing.sh to validate that specific hints correctly trigger their intended routes.

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