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

Adding a new skill module to reverse-skill requires creating a SKILL.md file with YAML frontmatter in skills/<module-name>/, registering it in 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. 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 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:

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 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【/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, and keyword rules that trigger the route.

Edit skills/config/routing.json to append your route:

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

"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【/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 to include your new skill in the documentation and client-neutral navigation.

Run the index generation script:

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

This script scans the frontmatter of every 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 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 as the primary entry point.

Summary

• Skill modules require a directory under skills/ containing a SKILL.md with YAML frontmatter (name and description).
• Route registration happens exclusively in 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.
• Documentation sync requires running extract-summaries.sh -Check to update INDEX.md.
• Quality assurance relies on verify-routing-coherence.sh and 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 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:

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

The extract-summaries.sh script parses these fields to generate 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 correctly reflects the "priority" array in routing.json. Both scripts must pass before your changes are considered safe for production.

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