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

To add a new skill module to reverse-skill, create a directory with a SKILL.md file containing valid front-matter, register the module in 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 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 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:

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 for the standard format.

Registering the Module in routing.json

The 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 and append a new route definition:

{
  "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 file
• keywords: Array of matching rules using regular expressions (must specifies required patterns)

The JSON schema is defined at the top of routing.json for reference.

Setting Priority Order

The "priority" array in skills/config/routing.json determines evaluation order—earlier entries take precedence. Insert your route ID at the appropriate position based on specificity:

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

Regenerating the Skill Index

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

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

This regenerates skills/INDEX.md by parsing the front-matter from every 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:

# 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 and 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	Route definitions and priority array
skills/MASTER-ROUTING.md	Human-readable priority documentation
skills/INDEX.md	Auto-generated skill registry

Summary

• Create a SKILL.md with valid front-matter in skills/<new-name>/
• Register the route in 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
• Execute verify-routing-coherence.sh and 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 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 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.

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