# Understanding Keyword Matching Rules in reverse-skill: A Technical Deep Dive

> Learn about the keyword matching rules in reverse-skill. This technical deep dive explains how routing.json and master-route.ps1 determine skill module selection for user requests.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: deep-dive
- Published: 2026-08-26

---

**reverse-skill determines the correct skill module for a user request by evaluating keyword rules defined in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and applied through the PowerShell script `skills/scripts/master-route.ps1`.**

The routing system matches natural language hints against regular-expression patterns to select specialized reverse-engineering skills. This article examines the exact matching logic implemented in the zhaoxuya520/reverse-skill repository, including rule structure, scoring algorithms, and conflict resolution.

## Keyword Rule Structure in routing.json

The central configuration file [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) defines each route (R1, R2, etc.) with a `keywords` array containing objects that specify matching conditions. Every keyword object supports four properties that control how user hints are evaluated.

### The must Parameter

The `must` field contains a regular expression that **must** match the lower-cased user hint for the rule to trigger. This serves as the primary filter for identifying relevant requests.

Example from the APK reverse engineering route:

```json
"R1": {
  "label": "APK reverse",
  "skill": "apk-reverse/SKILL.md",
  "keywords": [
    { 
      "must": "\\bapk\\b|smali|jadx|apktool|\\bandroid\\b|android.?reverse|安卓|反编译.?apk",
      "note": "android 裸词/root 检测/证书校验/pinning 绕过 均为 APK 分析常见诉求"
    }
  ]
}

```

(source: [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) lines 14-18)

### The mustAll Parameter

For scenarios requiring multiple independent conditions, the `mustAll` array accepts additional regex patterns. **All** patterns in this array must match for the rule to fire, enabling precise targeting of complex tasks.

This is commonly used for iOS jailbreak detection or LLM security analysis where the hint must contain both a primary term and contextual qualifiers.

### The exclude Parameter

The `exclude` field prevents false positives by specifying a regex pattern that **disqualifies** the match if present. When a hint matches the exclusion pattern, the entire keyword object is discarded regardless of other matches.

This mechanism ensures that ambiguous terms like "jailbreak" route to mobile security skills rather than LLM prompt injection tasks when the hint contains LLM-specific vocabulary.

## The Matching Algorithm in master-route.ps1

The `skills/scripts/master-route.ps1` script implements a three-phase matching engine that processes user hints against the routing configuration.

### Normalization and Evaluation

The algorithm first converts the input hint to lowercase (`$t`), then evaluates each keyword object through conditional logic:

```powershell
if ($null -ne $kw.must -and $t -match $kw.must) { $hit = $true }
if ($hit -and $null -ne $kw.mustAll) {
    foreach ($m in $kw.mustAll) {
        if ($t -notmatch $m) { $hit = $false; break }
    }
}
if ($hit -and $null -ne $kw.exclude -and $t -match $kw.exclude) { $hit = $false }

```

(source: `master-route.ps1` lines 35-50)

Each successful match increments the route's score, allowing multiple keyword objects within a single route to accumulate evidence.

## Route Selection and Scoring

After evaluating all routes against the hint, the system selects the PRIMARY route through a deterministic scoring mechanism.

### Candidate Ranking

Each matching route receives a score equal to the number of keyword objects that fired. The system then consults the `priority` array defined in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) to resolve ties. Routes appearing earlier in the priority list win when scores are equal.

If no routes match, the system falls back to route `R0`, ensuring every request receives a default handler.

(source: `master-route.ps1` lines 74-87)

### Confidence Reporting

The system reports match confidence based on result uniqueness:

- **High**: Exactly one route matches (`$uniq.Count -eq 1`)
- **Medium**: Multiple routes match but one has higher score/priority
- **Low**: No routes match, triggering fallback to R0

(source: `master-route.ps1` lines 90-97)

## Practical Code Examples

### Example 1: APK Reverse Engineering Detection

Matching simple APK-related requests uses the `must` regex with Chinese and English terms:

```powershell
master-route.ps1 -Hint "I need to decompile an APK and bypass its certificate pinning"

```

This triggers **R1** because the hint contains both "apk" and "pinning" within the `must` regex pattern.

### Example 2: Complex Matching with mustAll

Jailbreak detection requires both the primary term and platform context:

```powershell
master-route.ps1 -Hint "jailbreak iPhone with Frida"

```

This matches **R2** only because the hint satisfies the `must` pattern for "jailbreak" and the `mustAll` requirement containing one of `["ios","iphone","ipad","mobile","objection","ipa"]`.

### Example 3: Exclusion-Based Filtering

Preventing false positives on ambiguous terminology:

```powershell
master-route.ps1 -Hint "jailbreak model for prompt injection"

```

Despite containing "jailbreak," this routes to **R14** (LLM/Agent security) rather than mobile jailbreak analysis because the R2 rule includes an `exclude` pattern filtering LLM-related terms like "prompt injection."

## Summary

- **Configuration source**: All keyword matching rules reside in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), making it the single source of truth for routing logic.
- **Three-tier matching**: Rules combine `must` (required), `mustAll` (additive), and `exclude` (preventive) parameters for precise targeting.
- **Scoring system**: Routes accumulate points based on the number of matching keyword objects, with the `priority` array serving as the tie-breaker.
- **Fallback handling**: When no rules match, the system defaults to route `R0` with low confidence reporting.
- **Language support**: Regex patterns support Unicode for matching Chinese technical terms alongside English keywords.

## Frequently Asked Questions

### What file defines the keyword matching rules in reverse-skill?

The file [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) contains all route definitions and their associated keyword patterns. This JSON structure maps route IDs (R1, R2, etc.) to skill modules and specifies the regex conditions required for activation.

### How does reverse-skill prevent false positive matches?

The system uses `exclude` parameters within keyword objects to filter out hints that contain misleading terminology. Additionally, the `mustAll` array requires multiple independent pattern matches, reducing accidental triggers on ambiguous single words.

### What happens when multiple routes match the same hint?

Each matching route receives a score based on the count of satisfied keyword objects. The route with the highest score wins; if scores are equal, the `priority` array order in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) determines the winner. If no routes match, the system falls back to route `R0`.

### How is match confidence determined in master-route.ps1?

Confidence levels derive from result cardinality: **high** confidence requires exactly one matching route, **medium** confidence indicates multiple matches with clear scoring distinctions, and **low** confidence indicates zero matches triggering the R0 fallback. This metric helps downstream components understand routing reliability.