# How to Add a New Skill Module to reverse-skill: A Step-by-Step Guide

> Learn how to add a new skill module to reverse-skill with this step-by-step guide. Create a skill file, register it, and regenerate the index for seamless integration.

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

---

**To add a new skill module to reverse-skill, create a directory with a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file containing valid front-matter, register the module in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) with keywords and priority, then regenerate the index and run validation scripts.**

The reverse-skill repository uses a centralized routing system to dispatch user tasks to appropriate skill modules. Understanding how to add a new skill module requires familiarity with the [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) configuration format and the supporting tooling that keeps the system synchronized. This guide walks through the complete process based on the zhaoxuya520/reverse-skill source code.

## Creating the Skill Module Directory and SKILL.md

Every skill module begins as a folder under `skills/` containing a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file with standardized front-matter. This file serves as the entry point when the router selects your module.

Create the directory structure and [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md):

```bash
mkdir -p skills/example-skill
cat > skills/example-skill/SKILL.md <<'EOF'
---
name: example-skill
description: Demonstrates how to add a custom skill module.
---

# Example Skill

## ACTION REQUIRED

1. Read the target sample.
2. Run the custom analysis tool.
3. Produce a concise report.
EOF

```

The front-matter block (between `---` delimiters) must include:
- **name**: A unique identifier for the skill
- **description**: A human-readable summary

Reference existing modules like [`ghidra-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/ghidra-reverse/SKILL.md) for the standard format.

## Registering the Module in routing.json

The [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) file is the single source of truth for all routing decisions. Add your skill by inserting a new route entry with a unique ID (conventionally `R` + number).

Open [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and append a new route definition:

```json
{
  "R42": {
    "label": "Example skill",
    "skill": "example-skill/SKILL.md",
    "keywords": [
      { "must": "example|demo|custom\\s+skill" }
    ]
  }
}

```

Each route entry requires:
- **Unique route ID** (e.g., `R42`): Must not collide with existing entries
- **label**: Human-readable name for documentation
- **skill**: Relative path to the [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file
- **keywords**: Array of matching rules using regular expressions (`must` specifies required patterns)

The JSON schema is defined at the top of [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) for reference.

## Setting Priority Order

The `"priority"` array in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) determines evaluation order—earlier entries take precedence. Insert your route ID at the appropriate position based on specificity:

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

```

High-priority routes (more specific matchers) should appear earlier. Keep this in sync with the priority table documented in [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md).

## Regenerating the Skill Index

After adding your module, update the auto-generated documentation by running the extraction script:

```bash
bash skills/scripts/extract-summaries.sh -Check

```

This regenerates [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) by parsing the front-matter from every [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file in the repository. The `-Check` flag validates that all entries are properly formatted before writing.

## Validating Your Changes

Run the validation suite to ensure your new skill integrates correctly without breaking existing routing:

```bash

# Verify priority table matches JSON definitions

bash skills/scripts/verify-routing-coherence.sh

# Run 163 regression test cases

bash skills/scripts/test-routing.sh

```

The coherence check validates that [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) and [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) stay synchronized. The routing test suite confirms that keyword matching still works correctly for all routes including your new addition.

## Key Integration Points

When adding a new skill module to reverse-skill, these files must remain consistent:

| File | Purpose |
|------|---------|
| `skills/<name>/SKILL.md` | Skill implementation and instructions |
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Route definitions and priority array |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Human-readable priority documentation |
| [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) | Auto-generated skill registry |

## Summary

- Create a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) with valid front-matter in `skills/<new-name>/`
- Register the route in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) with unique ID, path, and keywords
- Insert the route ID into the `"priority"` array at the appropriate position
- Run `extract-summaries.sh -Check` to update [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md)
- Execute [`verify-routing-coherence.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/verify-routing-coherence.sh) and [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh) to validate

## Frequently Asked Questions

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

The router evaluates routes in `priority` array order and selects the first match. Place more specific routes earlier in the array to ensure precise matching. The [`verify-routing-coherence.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/verify-routing-coherence.sh) script can detect potential conflicts.

### Can I use PowerShell instead of Bash scripts?

Yes. The repository provides PowerShell equivalents for all scripts in `skills/scripts/`. Use `extract-summaries.ps1`, `verify-routing-coherence.ps1`, and `test-routing.ps1` on Windows systems.

### What is the naming convention for route IDs?

Route IDs follow the pattern `R` followed by a number (e.g., `R42`). The highest existing ID in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) indicates the next available number. IDs must be unique and stable once assigned.

### How do I test my skill's keyword matching locally?

Run `bash skills/scripts/test-routing.sh` with the `--interactive` flag to input sample queries and see which route the matcher selects. This helps tune your regex patterns before committing.