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

reverse-skill determines the correct skill module for a user request by evaluating keyword rules defined in 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 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:

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

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

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:

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:

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

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