# Reverse-Skill Routing Rules Configuration File: Location and Schema Guide

> Locate and understand the reverse-skill routing rules configuration file. This guide details the JSON schema for efficient task triage decisions in the repository.

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

---

**The reverse-skill routing rules configuration file is [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), a single JSON file that serves as the authoritative source for all task triage decisions in the repository.**

This article explains the structure, schema, and usage of the reverse-skill routing rules configuration file. The reverse-skill project by zhaoxuya520 uses this centralized JSON configuration to map incoming task hints to specialized security and reverse-engineering skills.

## Location of the Routing Configuration File

All routing logic in the reverse-skill repository reads from one location:

```

skills/config/routing.json

```

This path is hard-coded across all router implementations including `master-route.ps1` and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh). Because it is the **only** source of truth, any modification to routing behavior must be performed solely in this file.

## Schema Structure of routing.json

The reverse-skill routing rules configuration file follows a strict four-section schema:

| Section | Purpose |
|---------|---------|
| `schemaVersion` | Format version of the routing file |
| `meta` | Descriptive metadata, fallback route (`fallbackId`), scoring logic, and maintainer notes |
| `routes` | Map of route identifiers to skill definitions with keyword matching rules |
| `priority` | Ordered list of route IDs determining PRIMARY selection when scores tie |

### The routes Section

Each entry in `routes` uses a route ID (e.g., `R1`, `R2`) as the key and contains:

- **`label`** — Human-readable name for the route
- **`skill`** — Relative path to the skill's markdown definition
- **`keywords`** — Array of matching rules with `must`, `mustAll`, `exclude`, and optional `note` fields

### The priority Array

The `priority` array determines which matching route becomes the **PRIMARY** when multiple routes score equally. The first entry in this list that matches the highest score wins. If no rule matches, the router falls back to `meta.fallbackId` (typically `R0`).

## How Routing Scripts Consume the Configuration

### PowerShell Router

The `skills/scripts/master-route.ps1` script performs one-shot primary routing by loading and parsing [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json):

```powershell

# Example: run the primary router with a task hint

.\skills\scripts\master-route.ps1 -Hint "I need to analyze a malicious APK with obfuscation"

```

This script:

1. Loads [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)
2. Applies each route's `keywords` against the hint using regex matching
3. Scores matches, applies priority order, and outputs the selected skill markdown file

The same logic appears in the Bash counterpart at [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh).

### Validation and CI Integration

The repository includes dedicated scripts to ensure routing integrity:

- **`skills/scripts/verify-routing-coherence.ps1`** — Validates that the JSON stays in sync with skill files and priority list
- **`skills/scripts/test-routing.ps1`** — Automated test suite with 162 routing scenarios

Both scripts read [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) as their primary input, confirming that changes to the reverse-skill routing rules configuration file immediately propagate through the entire toolchain.

## Adding a New Route: Practical Example

To extend the routing configuration, add a new entry under `routes` and update `priority`:

```json
"R41": {
  "label": "Quantum cryptanalysis",
  "skill": "quantum-crypto/SKILL.md",
  "keywords": [
    { "must": "quantum|post‑quantum|qcrypto|shor|grover", "note": "Tasks involving quantum‑ready crypto analysis" }
  ]
}

```

**Required follow-up steps:**

1. Insert the new object under `"routes"`
2. Append the identifier to the `priority` array (e.g., after `"R40"`)
3. Commit the change
4. Run CI routing tests to verify consistency

## Programmatic Access in Python

For custom tooling, parse the reverse-skill routing rules configuration file directly:

```python
import json
import re
import pathlib

routing_path = pathlib.Path('skills/config/routing.json')
routing = json.loads(routing_path.read_text())

def route_for(text: str):
    scores = {}
    for rid, info in routing['routes'].items():
        for kw in info['keywords']:
            if 'must' in kw and not re.search(kw['must'], text, re.I):
                continue
            if 'exclude' in kw and re.search(kw['exclude'], text, re.I):
                continue
            scores[rid] = scores.get(rid, 0) + 1
    
    if not scores:
        return routing['meta']['fallbackId']
    
    # Select highest score, then apply priority order

    max_score = max(scores.values())
    candidates = [r for r, s in scores.items() if s == max_score]
    
    for pid in routing['priority']:
        if pid in candidates:
            return pid
    
    return routing['meta']['fallbackId']

print(route_for("Need to reverse‑engineer an iOS IPA with jailbreak detection"))

```

This implementation mirrors the logic in `master-route.ps1` and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh).

## Key Files in the Routing Architecture

| File | Role |
|------|------|
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Central routing definition (routes, keywords, priority) |
| `skills/scripts/master-route.ps1` | PowerShell entry point for PRIMARY skill selection |
| [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) | Bash entry point mirroring PowerShell router |
| `skills/scripts/verify-routing-coherence.ps1` | CI validation for routing/skill/priority consistency |
| `skills/scripts/test-routing.ps1` | Automated test suite (162 cases) |

These files constitute the complete routing architecture of reverse-skill, ensuring deterministic task-to-skill mapping for every security and reverse-engineering scenario.

## Summary

- **File location:** [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) is the sole configuration file for reverse-skill routing rules
- **Core schema:** Four sections (`schemaVersion`, `meta`, `routes`, `priority`) with strict validation
- **Keyword matching:** Supports `must`, `mustAll`, and `exclude` regex patterns per route
- **Tie-breaking:** Priority array determines PRIMARY when multiple routes score equally
- **Fallback behavior:** Routes to `meta.fallbackId` when no keywords match
- **Tooling:** PowerShell and Bash routers, plus CI validation scripts, all consume this single file

## Frequently Asked Questions

### What happens if I edit the routing.json file incorrectly?

The `verify-routing-coherence.ps1` script catches common errors including orphaned route IDs, missing priority entries, and skill file path mismatches. CI will fail until coherence is restored.

### Can I use multiple routing configuration files?

No. The reverse-skill architecture deliberately enforces a single source of truth. All scripts hard-code the path [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). Splitting configuration would break validation and routing consistency.

### How does the priority array handle new routes?

New routes must be manually inserted into the `priority` array. Position matters: earlier entries win when scores tie. The validation script ensures every route ID appears exactly once in priority.

### Is the routing.json schema versioned?

Yes. The `schemaVersion` field tracks format changes. Future schema upgrades would increment this value and likely require corresponding updates to `master-route.ps1`, [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh), and validation scripts.