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

To add a custom skill module to the reverse-skill framework, create a folder under skills/ containing a SKILL.md file, define a routing entry in 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 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 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 (e.g., 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 file that describes the skill's purpose and usage patterns.

# Create the skill directory

mkdir skills/my-awesome-skill

Inside skills/my-awesome-skill/SKILL.md, include descriptive metadata and optional command examples:

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

"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 -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1

This script checks that every route has a valid label, that referenced SKILL.md files exist, and that the priority array contains no orphaned entries.

Run regression tests:

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

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

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

Summary

• 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 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 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 documentation using relative paths. The router only cares about the location of SKILL.md; all other assets follow your organizational preference.

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