master-route.ps1 vs routing.md: Understanding the Primary Router and Advisory Matrix in zhaoxuya520/reverse-skill

The master-route.ps1 script is the executable routing engine that programmatically selects skills, while skills/routing.md is a human-readable advisory matrix used only for documentation and manual disambiguation.

In the zhaoxuya520/reverse-skill repository, routing decisions follow a clear separation of concerns: one automated, one advisory. The PowerShell script master-route.ps1 at skills/scripts/master-route.ps1 serves as the single source of execution, consuming skills/config/routing.json to match user hints against keywords, score candidates, and output a definitive route-scope.md. The Markdown file skills/routing.md provides a 3-axis reference view (Target Type × User Intent × Toolchain) that analysts consult when automated results need human verification.

---

How master-route.ps1 Executes Primary Routing

The master-route.ps1 script implements the complete routing logic through a four-stage workflow. It never hard-codes routes—every decision flows from the JSON configuration.

Stage 1: Load the Configuration

The script reads skills/config/routing.json as its single source of truth. This JSON defines all available routes, their associated keywords, priority ordering, and fallback assignments.

Stage 2: Match and Score Candidates

User hints are matched against the keywords array for each route. The script builds a candidate list, applies priority-based scoring, and ranks potential matches.

Stage 3: Select PRIMARY or Fallback

The highest-scoring candidate becomes the PRIMARY skill. If no match exceeds the confidence threshold, the script falls back to the fallbackId defined in configuration.

Stage 4: Generate route-scope.md

Output is written to route-scope.md containing:

• Selected primary skill path
• Confidence level
• Secondary candidates
• Next-step instructions

The script exits with status 0 on success or 2 on configuration errors.

# Execute the primary router with a user hint

.\skills\scripts\master-route.ps1 -Hint "decompile / IDA analyze"

---

The Role of skills/routing.md as Advisory Matrix

Unlike the executable script, skills/routing.md performs no programmatic routing. Its purpose is documentation and human guidance through a structured 3-axis view.

What the Matrix Contains

Axis	Purpose
Target Type	What is being analyzed (APK, ELF, PE, firmware, etc.)
User Intent	What the analyst wants to accomplish (decompile, debug, unpack, etc.)
Toolchain	Recommended tools and skill modules for the combination

When to Consult routing.md

• The primary router's output shows low confidence
• Multiple candidate skills score similarly
• A reviewer needs to verify mapping correctness
• Training new team members on skill organization

The Hierarchy Rule

The matrix explicitly acknowledges its subordinate role: "JSON-driven script wins if sources disagree"【2†L3-L5】. This prevents conflicting guidance—when automation and documentation diverge, the executable router's decision stands.

# Open advisory matrix for human review

code .\skills\routing.md

Sample matrix entry:

Target Type	Recommended Entry	Alternative
APK / Android app	apk-reverse/ — jadx decompile + apktool unpack	ida-reverse/ if core logic is in .so

---

Key Architectural Differences

Aspect	master-route.ps1	skills/routing.md
Function	Executable routing engine	Documentation and guidance
Input	routing.json, user hint	None (static reference)
Output	route-scope.md with PRIMARY skill	None (human reads directly)
Automation	Fully automated	Manual consultation only
Source of truth	Secondary (reads JSON)	None (advisory only)
Update mechanism	Modify routing.json or script	Direct Markdown edits
Exit codes	0 success, 2 config error	N/A

---

File Relationships and Dependencies

Three files form the complete routing system in zhaoxuya520/reverse-skill:

• skills/scripts/master-route.ps1 — The routing engine【1†L3-L86】
• skills/config/routing.json — Single source of truth for all route definitions
• skills/routing.md — Human-readable advisory matrix

The script consumes the JSON; the Markdown stands independent. Changes to routing behavior require JSON or script modifications. Changes to routing documentation require Markdown edits.

---

Summary

• master-route.ps1 is the executable primary router that reads routing.json, scores candidate skills by keyword matching and priority, and outputs route-scope.md
• skills/routing.md is the advisory matrix providing 3-axis human guidance with no programmatic function
• The JSON-driven script always prevails when documentation and automation conflict
• Exit code 2 indicates configuration errors in the primary router
• Both systems serve distinct audiences: automation for speed, documentation for clarity and training

---

Frequently Asked Questions

What happens if routing.json and routing.md recommend different skills?

The master-route.ps1 script's recommendation always takes precedence. The advisory matrix explicitly states that the JSON-driven script wins in conflicts【2†L3-L5】. The Markdown exists for human review, not override.

Can I run the router without PowerShell?

No—master-route.ps1 is a PowerShell script with no alternative implementation in the repository. The routing logic depends on PowerShell's JSON parsing, string matching, and file output capabilities.

How do I add a new skill to the routing system?

Modify skills/config/routing.json to define the new route, its keywords, priority, and fallbackId. The script will automatically include it in candidate scoring. Optionally update skills/routing.md to document the new skill's placement in the 3-axis matrix.

Why does the script generate route-scope.md instead of returning the skill directly?

The route-scope.md file serves as an audit trail and execution contract. It captures not just the selected skill but confidence levels, secondary candidates, and next-step instructions—information that ephemeral console output would lose.

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