# How to Add a Custom Skill Module with Proper Routing Rules in routing.json

> Learn to add a custom skill module to reverse-skill. Define routing rules in routing.json, create a skill folder, and update priority for seamless integration.

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

---

**To add a custom skill module to the reverse-skill framework, create a folder under `skills/` containing a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file, define a routing entry in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) with keyword matching rules, and insert the corresponding label into the priority array to activate the route.**

The reverse-skill repository centralizes all routing logic in a single JSON configuration file that serves as the single source of truth for both PowerShell and Bash dispatchers. Understanding how to properly extend [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) allows you to integrate new capabilities while maintaining deterministic task routing and CI compliance.

## Understanding the Routing Architecture

The routing system treats [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) as the exclusive authority for matching user hints to skill modules. When a user submits a task via `master-route.ps1 -Hint "<task>"`, the router loads this JSON file and evaluates entries sequentially according to the **priority array** defined at line 308.

Each routing entry contains:
- **`label`**: A human-readable identifier shown in UIs and error messages
- **`skill`**: The relative path to the module's [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) (e.g., [`my-awesome-skill/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/my-awesome-skill/SKILL.md))
- **Keyword rules**: Regex patterns including `must`, `mustAll`, and `exclude` that determine when a hint matches
- **Optional `note`**: Documentation explaining the routing intent

The **priority array** must maintain a 1-to-1 correspondence with the route objects. The CI test `test-routing.ps1` enforces this relationship, failing builds where labels are missing or out of sync.

## Step-by-Step Implementation

### Step 1: Create the Skill Folder Structure

Create a new directory under `skills/` using kebab-case naming. The folder must contain a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file that describes the skill's purpose and usage patterns.

```powershell

# Create the skill directory

mkdir skills/my-awesome-skill

```

Inside [`skills/my-awesome-skill/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/my-awesome-skill/SKILL.md), include descriptive metadata and optional command examples:

```markdown

# My Awesome Skill

This skill performs X-Y analysis on binary data files.

## Usage

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

```

```

### Step 2: Define Routing Rules in routing.json

Open [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and append a new route object to the routes collection. The `skill` field must point to your newly created [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) relative to the `skills/` directory.

```json
{
  "label": "My Awesome Skill",
  "skill": "my-awesome-skill/SKILL.md",
  "must": "\\bawesome\\b|\\bx-y\\b|\\banalysis\\b",
  "mustAll": "",
  "exclude": "\\bsimple\\b",
  "note": "Handles complex X-Y analysis; exclude when user asks for simple checks"
}

```

The `must` field accepts pipe-delimited regex patterns. The router evaluates these against the user hint, selecting the first match in the priority order.

### Step 3: Update the Priority Array

Locate the `priority` array at the bottom of [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) (around line 308). Insert your new label at the desired evaluation position. The order is critical: earlier entries take precedence when multiple regex patterns match.

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

```

Ensure your label string matches exactly the `label` value defined in your route object.

## Validating Your Configuration

Before committing changes, run the validation scripts to verify JSON integrity and routing coherence.

**Verify structural integrity:**

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

```

This script checks that every route has a valid label, that referenced [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files exist, and that the priority array contains no orphaned entries.

**Run regression tests:**

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

```

The test suite executes 162 validation cases. Both commands must report **"Ok"** for your new route to pass CI gates.

## Code Examples

### Minimal Skill Implementation

```

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

```

### Complete Routing Entry

```json
{
  "label": "Custom APK Decompiler",
  "skill": "custom-apk/SKILL.md",
  "must": "\\bapk\\b.*\\bdecompile\\b|\\breverse.*apk\\b",
  "mustAll": "\\bsmali\\b|\\bdex\\b",
  "exclude": "\\bipa\\b|\\bios\\b",
  "note": "Advanced APK reverse engineering; requires Smali knowledge"
}

```

### Priority Array Update

```json
"priority": [
  "APK reverse",
  "Custom APK Decompiler",
  "Mobile reverse (Android+iOS)"
]

```

## Summary

- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** serves as the sole routing authority; never hard-code routes in dispatcher scripts.
- Create skill folders under `skills/` with a mandatory [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) describing the capability.
- Define keyword matching rules using regex in the `must`, `mustAll`, and `exclude` fields.
- Always update the `priority` array to include new labels, maintaining the exact string match with route objects.
- Execute `verify-routing-coherence.ps1` and `test-routing.ps1` before submitting changes to ensure CI compliance.

## Frequently Asked Questions

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

If you add a routing entry but omit the label from the `priority` array, the `verify-routing-coherence.ps1` script will fail with a consistency error. The router iterates exclusively over the priority list, so missing labels result in unreachable skills that can never match user hints.

### Can I use negative lookaheads in the regex patterns?

Yes, the [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) file supports standard PCRE-compatible regex in the `must`, `mustAll`, and `exclude` fields. You can use negative lookaheads in the `exclude` field to prevent matching specific contexts while allowing broader `must` patterns.

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

The router evaluates skills in the exact order defined by the `priority` array and selects the first match. Place more specific rules (longer regex patterns or restrictive `mustAll` criteria) higher in the priority list to ensure they take precedence over general-purpose skills.

### Where should I place shared utility scripts for my custom skill?

Place reusable scripts in a `scripts/` subdirectory within your skill folder (e.g., `skills/my-awesome-skill/scripts/`). Reference these in your [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) documentation using relative paths. The router only cares about the location of [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md); all other assets follow your organizational preference.