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

To add a custom skill module with routing rules to routing.json, create a skill folder with a 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. The master-route.ps1 and 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 – The exclusive routing database containing labels, skill paths, keyword rules, and the priority array [routing.json line 308]
• master-route.ps1 – PowerShell entry point that parses hints and dispatches matches [master-route.ps1 line 3]
• 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

Create a new directory under skills/ and add a SKILL.md following the established pattern:

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

Example SKILL.md content:

# 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].

Step 3: Update the Priority Array

Add your label to the priority array at the bottom of routing.json. Position determines evaluation order—earlier entries match first:

"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:

# 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 -File skills/scripts/master-route.ps1 -Hint "run myskill on this file"

Expected output: the path to your SKILL.md file.

Summary

• Create a skill folder with SKILL.md under skills/<name>/
• Define routing rules in 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 (Bash) read 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].

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