# How reverse-skill Routes AI Tasks for Cybersecurity: Architecture and Implementation

> Discover how reverse-skill routes AI cybersecurity tasks using natural language hints and a regex-based scoring algorithm to select the best skill module.

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

---

**reverse-skill routes AI cybersecurity tasks by parsing natural-language hints through a regex-based scoring algorithm defined in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), selecting the highest-priority matching skill module with deterministic confidence levels.**

The reverse-skill framework provides a deterministic routing mechanism that maps natural-language cybersecurity requests to specialized reverse-engineering and penetration-testing modules. Developed in the zhaoxuya520/reverse-skill repository, this system uses a declarative JSON configuration to eliminate hard-coded routing logic. Understanding how reverse-skill routes AI tasks for cybersecurity reveals a platform-neutral architecture designed for extensibility and auditability.

## The Routing Configuration Schema

The framework maintains a **single source of truth** in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). This declarative file defines forty-two distinct routes (`R0` through `R41`), each mapping to a specific cybersecurity analysis module.

Each route entry contains:
- **`label`**: Human-readable description of the skill
- **`primary_skill`**: Path to the corresponding markdown file (e.g., [`skills/apk-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/apk-reverse/SKILL.md))
- **`keywords`**: Regex-based matching rules including `must`, `mustAll`, and `exclude` patterns
- **`priority`**: Array determining tie-breaking order when multiple routes achieve equal scores
- **`fallbackId`**: Default route (`R0`) used when no keywords match

## The Eight-Step Routing Workflow

The routing algorithm executes through eight deterministic stages implemented in [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) and its PowerShell counterpart:

1. **Parse the hint** — The script reads the `--hint` or `-Hint` parameter into a lower-cased string.

2. **Keyword matching** — The embedded Python block iterates through all routes, evaluating regex rules. Each match against `must` patterns increments the route's score. Optional `mustAll` requires all specified patterns to match, while `exclude` patterns disqualify routes.

3. **Scoring and priority resolution** — After evaluating all routes, the algorithm identifies the highest-scoring candidate. When scores tie, the route appearing earliest in the `priority` array wins.

4. **Confidence assignment** — The system assigns `high` confidence when only one route scores, `medium` when multiple routes share the top score, and `low` when falling back to `R0`.

5. **Generate routing report** — The script creates `work/<timestamp>/route-scope.md` containing the selected primary route, its label, skill file path, confidence level, and secondary candidates.

6. **Trigger execution** — The router prints the mandatory action: `ACTION: Open PRIMARY SKILL.md now and execute ACTION REQUIRED.`

7. **Verification** — `skills/scripts/verify-routing-coherence.ps1` validates that the `priority` list remains synchronized with defined routes.

8. **Fallback documentation** — When confidence is low, the system directs users to [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) for manual disambiguation.

## Keyword Matching and Scoring Logic

The regex-based matching system provides fine-grained control without language-specific parsers. Each route in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) specifies:

- **`must`**: Mandatory regex patterns that trigger scoring when matched
- **`mustAll`**: Additional set of patterns requiring all to match simultaneously
- **`exclude`**: Disqualifying patterns that prevent route selection

The scoring algorithm allows multi-keyword routes to outrank single-keyword matches. For example, a hint containing both "decompile" and "APK" might match route `R1` (APK reverse) with a higher score than generic routes, ensuring precise skill selection.

## Platform-Neutral Implementation

The router achieves cross-platform compatibility through a Python core wrapped in shell scripts:

**Bash Entry Point** ([`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh)):
Loads [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), executes the matching algorithm via embedded Python, writes the route scope report, and prints execution instructions. Supports Linux, macOS, and Kali environments.

**PowerShell Entry Point** (`skills/scripts/master-route.ps1`):
Provides identical functionality for Windows environments, sharing the same JSON contract and output format.

Both implementations write to `work/master-route-<timestamp>/route-scope.md`, ensuring consistent audit trails across operating systems.

## Confidence Levels and Audit Trails

The system generates deterministic confidence metrics to guide analyst decision-making:

- **High confidence**: Indicates a unique match where only one route satisfied the keyword criteria
- **Medium confidence**: Indicates multiple routes achieved identical scores; the primary selection represents the highest-priority match from the tie
- **Low confidence**: Indicates fallback to `R0` when no patterns matched, requiring manual review

The generated [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) file contains:
- Creation timestamp and project root path
- Original hint text
- Primary route ID and label
- Path to the selected skill markdown
- Confidence level assessment
- List of secondary candidate routes

This documentation creates a reproducible record before any "ACT" (actual penetration testing) phase begins.

## Validation and Coherence Testing

The framework includes automated safeguards to maintain routing integrity:

**Coherence Verification** (`skills/scripts/verify-routing-coherence.ps1`):
Compares the `priority` array against the set of defined routes in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), ensuring the ordered list contains all route IDs without omissions or duplicates.

**Automated Testing** ([`skills/scripts/test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/test-routing.sh)):
Executes a predefined suite of hint strings through the router and asserts expected primary IDs (`R1`, `R6`, `R24`, etc.). Failures indicate regex misconfigurations or priority list misalignment with the JSON schema.

## Practical Routing Examples

### Routing an Android Reverse Engineering Task

```bash
bash skills/scripts/master-route.sh --hint "I need to decompile an Android APK and check certificate pinning"

```

**Console Output:**

```

PRIMARY -> skills/apk-reverse/SKILL.md
Label: APK reverse | confidence: high
Wrote /path/to/project/work/master-route-20260826-173045/route-scope.md
ACTION: Open PRIMARY SKILL.md now and execute ACTION REQUIRED.

```

**Generated [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md):**

```markdown

# reverse-skill Master route (PRIMARY)

- created: 2026-08-26T17:30:45+08:00
- package: reverse-skill
- hint: I need to decompile an Android APK and check certificate pinning
- primary: R1
- primary_label: APK reverse
- primary_skill: skills/apk-reverse/SKILL.md
- confidence: high
- project_root: /path/to/project
- secondary: (none)

## MUST open next

1. skills/MASTER-ROUTING.md
2. skills/apk-reverse/SKILL.md

```

### Handling Ambiguous Hints

```bash
bash skills/scripts/master-route.sh --hint "Investigate a suspicious Windows AD credential theft technique"

```

When multiple routes match (e.g., `R24` for Windows/AD and `R10` for Attack chains), the router returns **medium** confidence for the highest-priority match while listing secondary candidates in the report.

### Windows PowerShell Execution

```powershell
powershell -File skills\scripts\master-route.ps1 -Hint "Find a way to bypass EDR on a Windows host"

```

The PowerShell implementation produces identical routing logic and report generation, ensuring consistent behavior across operating systems.

### Continuous Integration Testing

```bash
bash skills/scripts/test-routing.sh

```

This validates the entire routing matrix against expected outputs, preventing regression when modifying [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) or keyword patterns.

## Summary

- **reverse-skill** uses [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) as the single source of truth for mapping forty-two cybersecurity skill modules to natural-language hints.
- The routing algorithm employs regex-based scoring with `must`, `mustAll`, and `exclude` patterns, resolving ties through an explicit priority array.
- Confidence levels (`high`, `medium`, `low`) provide immediate feedback on routing certainty, with automatic fallback to documented manual selection processes.
- Platform-neutral implementation via [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) (Bash) and `master-route.ps1` (PowerShell) ensures consistent operation across Windows, macOS, Linux, and Kali environments.
- Automated validation through `verify-routing-coherence.ps1` and [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh) maintains configuration integrity as the framework scales.

## Frequently Asked Questions

### How does reverse-skill handle ambiguous hints that match multiple routes?

When multiple routes achieve identical scores, reverse-skill assigns **medium** confidence to the primary selection and uses the explicit `priority` array defined in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) to break ties. The route appearing earliest in the priority list becomes primary, while secondary candidates are documented in [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) for analyst review.

### What happens when no keywords match the provided hint?

If no regex rules match, the system routes to the `fallbackId` (typically `R0`) with **low** confidence and directs the user to [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) for manual disambiguation. This ensures the framework never blocks execution while clearly communicating uncertainty.

### How do I add a new cybersecurity skill to the router?

Add a new entry to the `routes` object in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) with a unique ID (e.g., `R42`), specify the `label` and `primary_skill` path, define appropriate `keywords` with regex patterns, and append the ID to the `priority` array. No code changes are required; the router automatically recognizes the new route on next execution.

### Is the routing mechanism cross-platform compatible?

Yes. The routing logic is implemented once in embedded Python within [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh), which executes on Linux, macOS, and Kali. Windows compatibility is provided by `master-route.ps1`, which shares the same JSON contract and produces identical [`route-scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/route-scope.md) outputs, ensuring deterministic routing across all supported platforms.