How the Core Routing Flow Is Structured in reverse‑skill

The reverse‑skill routing system maps free‑form user hints to skill modules through a JSON‑driven keyword‑matching algorithm that runs identically on PowerShell and Bash.

Understanding how routing decisions are made is essential for extending the reverse‑skill framework. The routing flow in zhaoxuya520/reverse‑skill is built around a single source of truth—the JSON configuration at skills/config/routing.json—that both platform entry points consume to resolve user intent into executable skill paths.

The Routing Architecture

At its core, reverse‑skill implements a platform‑neutral routing pipeline. Rather than duplicating logic across operating systems, the project maintains parallel implementations in PowerShell (skills/scripts/master-route.ps1) and Bash (skills/scripts/master-route.sh) that execute identical algorithms against the same structured data.

This design ensures that a routing decision on Windows produces the same result as on Linux, macOS, or Kali.

Step‑by‑Step Routing Flow

Step 1: Hint Parsing and Normalization

The routing flow begins when the user invokes master-route with a free‑form text hint:

# Bash entry point

bash skills/scripts/master-route.sh --hint "analyse Android APK and bypass certificate pinning"

# PowerShell entry point

powershell -File skills/scripts/master-route.ps1 -Hint "Find hidden services in a Kubernetes cluster"

Both scripts perform identical preprocessing:

1. Convert the hint to lowercase
2. Tokenize and scan against regular‑expression patterns defined in routing.json
3. Accumulate match scores per route ID

Step 2: Keyword Matching and Scoring

The matching engine evaluates every route defined in skills/config/routing.json. Each route contains a "keywords" array of regex patterns. For every pattern that matches the hint, the corresponding route receives a score increment.

The algorithm prioritizes specificity through accumulation—routes with multiple matching keywords outrank those with single matches.

Step 3: Priority‑Based Route Selection

After scoring completes, the resolver iterates through the "priority" array in order. The first route ID in this list with a non‑zero score becomes the PRIMARY selection. This tiered approach ensures:

• Deterministic tie‑breaking: Earlier entries in "priority" win when scores are equal
• Controlled fallback: When no keywords match, the system defaults to "fallbackId": "R0"

Step 4: Output Generation and User Direction

The resolved route triggers two outputs:

• A timestamped route‑scope.md file in work/master-route-{YYYYMMDD-HHMMSS}/ containing the route label, skill file path, confidence level, and operational notes
• Console output directing the user to open the selected SKILL.md and execute the action required

Visualization of the Routing Flow

┌─────────┐     ┌─────────────────┐     ┌─────────────────────┐
│  Hint   │────→│  master-route   │────→│   routing.json      │
└─────────┘     │ (PS1 / Bash)    │     │ (single source of   │
                │                 │     │  truth)             │
                │  • lower‑case   │     └─────────────────────┘
                │  • keyword scan │              │
                │  • regex match  │              ▼
                │                 │     ┌─────────────────────┐
                └─────────────────┘     │  keyword matching   │
                        │               │  → scoring engine   │
                        │               └─────────────────────┘
                        │                        │
                        └────────────────────────┘
                                     │
                                     ▼
                          ┌─────────────────┐
                          │  priority list  │
                          │  iteration      │
                          └─────────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────┐
                    │  PRIMARY route resolved  │
                    │  (SKILL.md path)         │
                    └──────────────────────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    ▼                             ▼
            ┌─────────────┐               ┌─────────────┐
            │ route-scope │               │   console   │
            │   .md file  │               │   output    │
            │  (artifact) │               │  (user dir) │
            └─────────────┘               └─────────────┘

Verification and Coherence Checking

To prevent drift between the JSON configuration and human‑readable documentation, reverse‑skill includes a dedicated verification script:

powershell -File skills/scripts/verify-routing-coherence.ps1

# → "ALL ROUTING COHERENCE CHECKS PASSED"

verify-routing-coherence.ps1 validates that:

• Every route ID in "routes" appears in the "priority" list
• The priority list contains no orphaned entries
• The markdown matrix (skills/routing.md) remains synchronized with the JSON source

This verification step ensures the routing integrity of the framework before deployment or after configuration changes.

Key Files in the Routing System

File	Responsibility
skills/config/routing.json	Central configuration: route definitions, keywords, priority order, fallback ID
skills/scripts/master-route.ps1	Windows entry point implementing the full routing algorithm
skills/scripts/master-route.sh	Linux/macOS/Kali entry point with matching logic
skills/scripts/verify-routing-coherence.ps1	Integrity checker for JSON/priority alignment
skills/MASTER-ROUTING.md	Contract documentation and usage guidelines
skills/routing.md	Three‑axis disambiguation matrix for vague hints

Summary

• Single source of truth: All routing decisions derive from skills/config/routing.json
• Platform parity: PowerShell and Bash entry points execute identical algorithms
• Scoring + priority: Routes accumulate keyword matches; priority list breaks ties deterministically
• Automated verification: Coherence checking prevents configuration drift
• Structured output: Every routing decision produces both artifacts (route-scope.md) and actionable console guidance

Frequently Asked Questions

What happens if multiple routes have the same keyword match score?

The routing system uses the "priority" array as a deterministic tie‑breaker. The first route ID in this ordered list with a matching score wins. This design guarantees predictable, reproducible routing decisions regardless of input order or platform.

Can I extend routing.json with new routes without modifying the scripts?

Yes. The routing algorithm is data‑driven—adding new route objects to skills/config/routing.json and including their IDs in the "priority" array automatically extends functionality. Run verify-routing-coherence.ps1 after modifications to validate structural integrity.

How does reverse‑skill handle platform differences between PowerShell and Bash?

Both master-route.ps1 and master-route.sh implement the same four‑step algorithm: hint normalization, regex keyword matching, priority‑based selection, and artifact generation. They differ only in syntax—JSON parsing, string manipulation, and file operations—while producing identical routing decisions from identical inputs.

What is the purpose of the routing.md matrix?

skills/routing.md provides a human‑readable three‑axis reference for disambiguating vague hints. When keyword matching is inconclusive or users are uncertain about phrasing, this matrix offers categorical guidance organized by domain, technique, and target platform.

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