How to Route APK Analysis Tasks to the Correct Skill Module in Reverse-Skill

The reverse-skill platform routes APK analysis requests through a regex-based scoring system defined in skills/config/routing.json, where natural-language hints are matched against keyword patterns to select the appropriate skill module before executing authorization checks and analysis scripts.

The zhaoxuya520/reverse-skill repository provides an automated routing system that connects natural-language analysis requests with specialized reverse-engineering skill modules. When you submit a request to analyze an Android APK—whether for decompilation, certificate pinning bypass, or smali inspection—the platform's router interprets your intent and dispatches the task to the correct automation scripts. Understanding this routing workflow is essential for extending the platform or troubleshooting why a specific APK analysis task triggered a particular skill module.

The 8-Step APK Analysis Routing Workflow

The complete workflow transforms a free-form text hint into a concrete, reproducible analysis session. Each stage is handled by specific scripts and configuration files within the repository.

Step 1: Submit the Analysis Hint

The process begins when you invoke the primary routing command with a natural-language description of your APK analysis goal. You can use either the PowerShell or Bash entry point located in skills/scripts/.

# PowerShell invocation

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 -Hint "decompile APK with jadx apktool smali"

# Bash invocation

bash skills/scripts/master-route.sh --hint "apk certificate pinning bypass"

Both master-route.ps1 and master-route.sh accept the hint parameter and begin the evaluation process.

Step 2: Load the Central Routing Table

Both routing scripts read skills/config/routing.json, which serves as the single source of truth for all routing decisions. This JSON file contains the "routes" object where each skill module is defined with specific matching criteria.

Step 3: Score Routes Using Keyword Matching

For each entry under the "routes" object, the router evaluates the "keywords" array against your hint text. The matching logic supports three regex-based conditions:

• must – A regex that must appear in the hint for the route to score
• mustAll – A list of regexes that all must match simultaneously
• exclude – A regex that, if present, disqualifies the route

For APK analysis, route R1 (APK reverse) uses patterns like \bapk\b|smali|jadx|apktool to capture typical reverse-engineering terminology. Each successful match contributes to the route's cumulative score.

Step 4: Select the Primary Route by Priority

After scoring all routes, the router selects the entry with the highest score. If multiple routes achieve identical scores, the "priority" list defined in routing.json (lines 308-311) determines the winner. If no patterns match, the system falls back to the fallbackId (R0).

Step 5: Load the Skill Documentation

The chosen route's "skill" field points to a markdown file describing the module's capabilities. For APK tasks, this resolves to apk-reverse/SKILL.md, which documents available scripts and typical workflows for Android reverse engineering.

Step 6: Validate Authorization and Scope

Before executing tools, the case guard (case-guard.ps1 or case-guard.sh) performs mandatory validation checks:

• Verifies auth.status=granted for the current user
• Confirms the scope contains an APK file using the regex \.apk\b

If the guard detects no APK in scope, it rejects the request with an error message: "BAD: Scope does not contain a .apk, .bin or .exe file."

Step 7: Initialize the Case Environment

Once authorization passes, case-init.sh creates a dedicated workspace under work/<case>/. This directory contains scope.md and other artifacts required for the analysis session, ensuring isolated, reproducible investigations.

Step 8: Execute the Skill Scripts

Finally, the platform invokes the skill-specific scripts. For APK decompilation, this means running apk-reverse/scripts/decode.ps1, which utilizes the ToolDiscovery.ps1 layer to verify that tools like jadx, apktool, and frida are installed before processing the binary.

# Manual invocation example after routing

powershell -NoProfile -ExecutionPolicy Bypass -File apk-reverse/scripts/decode.ps1 -CaseName demo -Sample ./app.apk

Routing Configuration Deep Dive

The routing.json Structure

The routing table defines route objects with unique IDs, keyword arrays, and skill mappings. The APK reverse entry (R1) specifically targets Android analysis workflows by matching terms associated with Dalvik bytecode, decompilation tools, and mobile security testing.

Regex Patterns for APK Detection

The platform uses sophisticated regex patterns to distinguish APK analysis from other reverse-engineering tasks (like PE binary or firmware analysis). The must and mustAll arrays allow precise control over routing logic, ensuring that hints mentioning "apk" alongside "decompile" route to the Android skill while hints about "bypass" alone might require additional context.

Case Guard and Initialization Scripts

The guard scripts act as a security and sanity check layer. Located at skills/scripts/case-guard.ps1 and skills/scripts/case-guard.sh, they ensure that:

1. The user possesses valid authorization credentials
2. The input scope actually contains an Android package file
3. The environment meets prerequisites before creating case artifacts

Only after passing these checks does skills/scripts/case-init.sh scaffold the work/<case>/ directory structure and prepare the analysis environment.

Summary

• Routing starts with a hint submitted to master-route.ps1 or master-route.sh, which parses natural-language descriptions of APK analysis tasks.
• Scoring happens in routing.json, where regex patterns in must, mustAll, and exclude arrays determine the best-matching skill module.
• Route R1 handles APK reverse engineering, matching keywords like "apk", "smali", "jadx", and "apktool" to identify Android-specific requests.
• Authorization gates exist in case-guard.ps1 and case-guard.sh, verifying both user permissions and the presence of .apk files in scope.
• Execution occurs through skill scripts like apk-reverse/scripts/decode.ps1, which leverage ToolDiscovery.ps1 to ensure required reverse-engineering tools are available.

Frequently Asked Questions

How does the router handle ambiguous hints that match multiple skills?

When multiple routes achieve identical match scores, the router consults the "priority" list in skills/config/routing.json (defined around lines 308-311) to determine the winning route. If no routes match at all, the system defaults to the fallbackId (R0), ensuring the request always resolves to a skill module rather than failing silently.

What happens if the case guard rejects my APK analysis request?

The guard scripts (case-guard.ps1 or case-guard.sh) terminate the workflow with an explicit error message such as "BAD: Scope does not contain a .apk, .bin or .exe file." You must ensure your case scope includes a file matching the \.apk\b regex pattern and that your authorization status equals granted before the platform will allow case-init.sh to create the analysis environment.

Can I manually invoke APK analysis scripts without using the router?

Yes, you can bypass the routing system and directly execute skill scripts like apk-reverse/scripts/decode.ps1 by specifying the -CaseName and -Sample parameters. However, this skips the automated tool discovery and case initialization steps, so you must manually ensure that jadx, apktool, and other dependencies are installed and that your case directory structure exists under work/<case>/.

Where are the routing rules defined for custom APK analysis tasks?

All routing logic resides in skills/config/routing.json. To add custom APK analysis workflows, you would modify the "routes" object to include new entries with appropriate keywords arrays containing must, mustAll, or exclude patterns that match your specific analysis terminology. The verify-routing-coherence.ps1 script can validate your changes for consistency, checking for route count parity and missing skill references.

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