# How to Add a Custom Skill Module with Routing Rules to `routing.json` in reverse-skill

> Learn to add a custom skill module with routing rules to routing.json in reverse-skill. Follow steps to create a skill, define rules, and update priority for seamless integration.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-13

---

**To add a custom skill module with routing rules to [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), create a skill folder with a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file, add a routing entry with keyword rules, update the priority array, and run the validation scripts.**

The `reverse-skill` repository implements a **single source of truth** routing system where all dispatch decisions originate from one JSON file. Understanding this architecture allows you to extend the platform with new capabilities while maintaining deterministic, testable routing behavior.

## Understanding the Routing Architecture

`reverse-skill` centralizes all routing logic in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). The `master-route.ps1` and [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) scripts read this file, evaluate keyword rules against user hints, and return the matching skill path according to the priority list.

Key components work together:

- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** – The exclusive routing database containing labels, skill paths, keyword rules, and the priority array [[routing.json line 308](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json#L308)]
- **`master-route.ps1`** – PowerShell entry point that parses hints and dispatches matches [[master-route.ps1 line 3](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.ps1#L3)]
- **[`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files** – Human-readable skill descriptions referenced by routing entries
- **Validation scripts** – CI-enforced checks ensuring routing consistency

## Step-by-Step: Adding a Custom Skill Module

### Step 1: Create the Skill Folder and [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md)

Create a new directory under `skills/` and add a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) following the established pattern:

```

reverse-skill/
└─ skills/
   └─ my-awesome-skill/
      └─ SKILL.md

```

Example [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) content:

```markdown

# My Awesome Skill

Performs X-Y analysis on Z data for reverse engineering workflows.

## Usage

```powershell
powershell -File scripts/do-awesome.ps1 -Input <file>

```

```

Reference existing skills like [[`apk-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/apk-reverse/SKILL.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/apk-reverse/SKILL.md) for formatting conventions.

### Step 2: Add the Routing Entry to [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json)

Insert a new route object with these fields:

| Field | Description | Example |
|-------|-------------|---------|
| `label` | Human-readable identifier | `"My Awesome Skill"` |
| `skill` | Relative path to [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) | `"my-awesome-skill/SKILL.md"` |
| `must` | Regex pattern for keyword matching | `"\\bawesome\\b|\\bmyskill\\b"` |
| `mustAll` | (Optional) All patterns must match | `["\\bandroid\\b", "\\breverse\\b"]` |
| `exclude` | (Optional) Patterns that disqualify | `"\\bios\\b"` |
| `note` | (Optional) Intent clarification | `"Triggers for custom Awesome analysis"` |

Complete routing entry example:

```json
{
  "label": "My Awesome Skill",
  "skill": "my-awesome-skill/SKILL.md",
  "must": "\\bawesome\\b|\\bmyskill\\b|\\bX‑Y\\b",
  "note": "Triggers when the user explicitly asks for the custom Awesome analysis."
}

```

This mirrors built-in routes like the APK reverse entry [[routing.json lines 14-15](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json#L14-L15)].

### Step 3: Update the Priority Array

Add your label to the `priority` array at the bottom of [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). Position determines evaluation order—earlier entries match first:

```json
"priority": [
  "APK reverse",
  "Mobile reverse (Android+iOS)",
  "...",
  "My Awesome Skill"
]

```

The priority array and route objects must maintain 1-to-1 correspondence; the `test-routing.ps1` suite validates this.

### Step 4: Validate Your Changes

Run both verification scripts before committing:

```powershell

# Lint routing.json structure and consistency

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1

# Execute 162-case regression suite

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-routing.ps1

```

Both must report **"Ok"** for the new route. CI enforcement prevents merging if either script fails.

## Keyword Rule Reference

The routing engine supports four rule types evaluated as regular expressions:

- **`must`** – At least one pattern must match the user hint
- **`mustAll`** – Every pattern in the array must match
- **`exclude`** – No pattern may match (disqualifies otherwise valid matches)
- **`note`** – Documentation field, not evaluated during matching

Rules combine logically: a route matches when `(must OR mustAll satisfied) AND NOT exclude`.

## Testing Your New Skill

Verify end-to-end functionality with the master router:

```powershell
powershell -File skills/scripts/master-route.ps1 -Hint "run myskill on this file"

```

Expected output: the path to your [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file.

## Summary

- **Create** a skill folder with [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) under `skills/<name>/`
- **Define** routing rules in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) using `label`, `skill`, and keyword fields
- **Position** your label in the `priority` array to control matching precedence
- **Validate** with `verify-routing-coherence.ps1` and `test-routing.ps1` before submission
- **Reference** actual source paths and maintain 1-to-1 label-to-route correspondence

## Frequently Asked Questions

### What happens if I forget to update the priority array?

The `verify-routing-coherence.ps1` script detects the mismatch and fails with a descriptive error. The CI gate prevents merging inconsistent routing configurations—every route entry requires a corresponding priority list entry.

### Can I use complex regex patterns in keyword rules?

Yes. The `must`, `mustAll`, and `exclude` fields accept full PCRE-compatible regular expressions. Use word boundaries (`\b`) to prevent substring false positives, and escape special characters properly for JSON strings.

### How do I prioritize my skill over existing routes?

Insert your label **earlier** in the `priority` array. The router evaluates entries sequentially and returns the first match, so earlier positions take precedence. Position carefully to avoid unintentionally shadowing related skills.

### Where does the routing data actually get consumed?

Both `skills/scripts/master-route.ps1` (PowerShell) and [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) (Bash) read [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) directly—no compiled code or secondary caches. This design guarantees that editing the JSON file immediately affects all routing behavior without rebuild steps [[AGENTS.md line 11](https://github.com/zhaoxuya520/reverse-skill/blob/main/AGENTS.md#L11)].