# How to Add a Custom Skill Module to the reverse-skill Routing Matrix

> Learn to add a custom skill module to the reverse-skill routing matrix by creating a skill folder registering it in routing.json and adjusting priority.

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

---

**Adding a custom skill module to the reverse-skill routing matrix requires creating a skill folder with a SKILL.md file, registering it in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) with a unique ID and keyword rules, and optionally adjusting the priority array.**

The **reverse-skill** repository by zhaoxuya520 implements a modular routing system for reverse engineering tasks. All routing decisions flow through a **single-source-of-truth** JSON configuration, making skill registration a straightforward three-step process with no code changes required to core routing logic.

## Understand the Routing Architecture

The routing system centers on [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), which serves as the authoritative registry mapping **skill IDs** to executable descriptions and trigger conditions. The primary routing script `master-route.ps1` consumes this file directly, along with supporting verification tools `test-routing.ps1` and `verify-routing-coherence.ps1`.

Key components:

- **Skill ID** — a unique identifier in `Rxx` format (e.g., `R42`, `R7`)
- **SKILL.md** — the human-readable entry point documenting purpose, usage, and prerequisites
- **Keyword rules** — regular expression patterns that determine when a skill activates
- **Priority array** — ordered list controlling evaluation sequence when keywords overlap

For authoritative context on the routing contract, consult [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md).

## Step 1: Create the Skill Bundle

Create a new folder under `skills/` containing at minimum a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file. Optional reference materials may reside in subdirectories.

### Folder structure

```

skills/my-custom-skill/
├─ SKILL.md           # Required: main skill documentation

└─ references/
   └─ overview.md     # Optional: supplementary documentation

```

### SKILL.md template

Model your file after [`skills/js-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/js-reverse/SKILL.md). A minimal valid structure:

```markdown

# My Custom Skill

Brief description of the skill's purpose and target scenarios.

## Prerequisites

- Required tools or environment setup

## Usage

```powershell
powershell -File skills\my-custom-skill\run.ps1 -Target <url>

```

## Output

Description of expected results.

```

The [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) path becomes the `skill` value in your routing entry, specified **relative to repository root**.

## Step 2: Register in routing.json

Append a new entry to [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) following the established schema.

### Example registration

```json
{
  "R42": {
    "label": "My Custom Skill",
    "skill": "my-custom-skill/SKILL.md",
    "keywords": [
      {
        "must": "mycustom|awesome|demo|example",
        "note": "Triggers when user mentions demo keywords"
      }
    ]
  }
}

```

### Field reference

| Field | Description |
|-------|-------------|
| `R42` | Unique skill ID; verify unused in existing entries |
| `label` | Display name for routing logs and diagnostics |
| `skill` | Relative path from repository root to SKILL.md |
| `keywords` | Array of condition objects with regex rules |

### Keyword rule options

The `keywords` array supports multiple condition types:

- **`must`** — Single-line regex; skill triggers if pattern matches
- **`mustAll`** — Array of patterns; all must match
- **`exclude`** — Pattern that disqualifies the match if present

Multiple keyword objects create **OR** logic between them.

## Step 3: Adjust Priority (Optional)

By default, new skills evaluate after all prioritized IDs. To override existing skills with overlapping keywords, insert your ID into the `"priority"` array near line 310 of [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json):

```json
"priority": [
  "R4", "R1", "R38", "R42", "R0"
]

```

Higher positions in the array receive earlier evaluation. Place `R42` where it should rank relative to existing skills.

## Step 4: Verify Routing Integrity

Run the verification suite from repository root:

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

```

Expected results:

- **Exit code 0** from both scripts
- "Routing matrix coherent" confirmation
- No regressions in the 162-case test suite

Failures indicate JSON syntax errors, missing [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files, or priority array inconsistencies. Address before committing changes.

## Summary

- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** — Central registry for all skill mappings; edit this to add your module
- **Unique `Rxx` ID** — Required identifier; check for collisions with existing entries
- **[`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) path** — Must be relative to repository root and point to an existing file
- **Keyword rules** — Regex-based triggers with `must`, `mustAll`, and `exclude` options
- **Priority array** — Controls evaluation order; modify only if keyword overlap demands precedence
- **Verification scripts** — `verify-routing-coherence.ps1` and `test-routing.ps1` validate changes

## Frequently Asked Questions

### What happens if two skills have identical keywords?

The **priority array** in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) determines evaluation order. The first matching skill in priority order wins. If neither skill appears in the priority array, their relative order follows JSON key iteration, which is unreliable—always specify priority for skills with potentially overlapping triggers.

### Can I use any ID format besides Rxx?

No. The `master-route.ps1` routing logic and verification scripts expect skill IDs in `R` followed by two digits format (`R00`–`R99`). Deviating from this pattern causes validation failures in `verify-routing-coherence.ps1`.

### Do I need to restart any services after editing routing.json?

No. All routing machinery—`master-route.ps1`, `test-routing.ps1`, and `verify-routing-coherence.ps1`—reads [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) at execution time. Changes take effect immediately on the next routing decision or test run.

### How do I test my skill's keyword matching without running full reverse operations?

Use `skills/scripts/test-routing.ps1` with targeted test cases, or create temporary test entries in the routing JSON and invoke `master-route.ps1` with sample input strings. The verification scripts provide coverage for 162 standard use cases to catch regressions.