# How to Add a New Skill Module to reverse-skill: A Complete Developer Guide

> Learn how to add a new skill module to reverse-skill. Follow this developer guide to create, register, and validate your new skill for the project.

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

---

**Adding a new skill module to reverse-skill requires creating a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file with YAML frontmatter in `skills/<module-name>/`, registering it in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) with unique route IDs and keywords, updating the priority array, and running the validation scripts to sync documentation and verify routing logic.**

The reverse-skill repository dynamically routes user tasks to specialized skill modules through a configuration-driven architecture centered on [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). To extend its capabilities, developers must follow a structured workflow that coordinates multiple configuration files and validation scripts. This guide walks through the exact steps to add a new skill module while maintaining routing integrity.

## Create the Skill Module Directory and SKILL.md

Every skill module resides in its own subdirectory under `skills/` and must contain a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file with standardized YAML frontmatter. This file serves as the entry point the router opens after selecting 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 frontmatter must include a unique `name` identifier and a `description` that the index generator uses for documentation. Refer to existing modules like [`skills/ghidra-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ghidra-reverse/SKILL.md) for the exact format recognized by the parser.

## Register the Route in routing.json

The router discovers available skills exclusively through [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)【/cache/repos/github.com/zhaoxuya520/reverse-skill/main/skills/config/routing.json†L1-L7】. You must add a new route entry with a unique ID (e.g., `R42`), a human-readable label, the relative path to your [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md), and keyword rules that trigger the route.

Edit [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) to append your route:

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

```

The `keywords` array drives the primary-route decision. Each object can contain `must` (required terms) and `should` (optional boosters) patterns using regular expressions. The router parses this file for every task and matches against the user's input text.

## Configure Route Priority

The `"priority"` array in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) determines the evaluation order when multiple routes match a query【/cache/repos/github.com/zhaoxuya520/reverse-skill/main/skills/config/routing.json†L16-L22】. Insert your new route ID at the appropriate position—higher priority routes appear earlier in the array.

Update the priority list in the same file:

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

```

The router selects the **first** matching route in this order. You must keep this array synchronized with the human-readable priority table documented in [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md)【/cache/repos/github.com/zhaoxuya520/reverse-skill/main/skills/MASTER-ROUTING.md†L77-L84】 to prevent routing conflicts.

## Regenerate the Skill Index

After creating the module and updating the configuration, regenerate [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) to include your new skill in the documentation and client-neutral navigation.

Run the index generation script:

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

```

This script scans the frontmatter of every [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file under `skills/` and rebuilds the index automatically.

## Validate the Implementation

Before committing changes, execute the routing regression suite and coherence checker to ensure your new route does not break existing logic and that all configuration files remain synchronized.

Run the validation scripts:

```bash
bash skills/scripts/verify-routing-coherence.sh   # Validates priority table ↔ JSON alignment

bash skills/scripts/test-routing.sh              # Executes 163 regression test cases

```

If both scripts exit without errors, the router will now match any task containing "example", "demo", or "custom skill" and direct it to [`skills/example-skill/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/example-skill/SKILL.md) as the primary entry point.

## Summary

- **Skill modules** require a directory under `skills/` containing a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) with YAML frontmatter (`name` and `description`).
- **Route registration** happens exclusively in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), where you define unique IDs, labels, paths, and keyword matching rules.
- **Priority ordering** in the `"priority"` array determines which route wins when multiple patterns match; keep this synchronized with [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md).
- **Documentation sync** requires running `extract-summaries.sh -Check` to update [`INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/INDEX.md).
- **Quality assurance** relies on [`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 maintain the integrity of all 163 routing scenarios.

## Frequently Asked Questions

### What is the exact frontmatter format required for SKILL.md?

Your [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) must begin with YAML frontmatter enclosed in triple dashes containing exactly two fields: `name` (a unique identifier for the skill) and `description` (a concise summary shown in the index). For example:

```yaml
---
name: example-skill
description: Demonstrates how to add a custom skill module.
---

```

The [`extract-summaries.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/extract-summaries.sh) script parses these fields to generate [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md).

### How does the keyword matching work in routing.json?

The `keywords` array in each route entry supports regular expression patterns. Use `"must"` for required terms that must appear in the user query for the route to qualify, and `"should"` for optional terms that increase match confidence. The router evaluates routes in priority order and selects the first route where all `"must"` conditions are satisfied.

### Why is the order of the priority array important?

The router iterates through the `"priority"` array sequentially and stops at the first route whose keywords match the current task. Therefore, placing your route earlier in the array gives it precedence over more generic routes that might also match the same keywords. Misordering can cause specialized skills to be shadowed by general-purpose ones.

### How do I verify that my new skill won't break existing routing?

Run `bash skills/scripts/test-routing.sh` to execute the full regression suite of 163 test cases that validate routing behavior across all defined scenarios. Additionally, run `bash skills/scripts/verify-routing-coherence.sh` to confirm that the priority table in [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) correctly reflects the `"priority"` array in [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json). Both scripts must pass before your changes are considered safe for production.