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

Adding a new skill to the reverse-skill package requires creating a skill directory with a SKILL.md entry point, registering the skill in skills/config/routing.json, and regenerating the auto-generated index through PowerShell helper scripts.

The reverse-skill package routes security and reverse-engineering requests to specialized capability modules called skills—self-contained workflows defined by markdown documentation and regex-based routing rules. This guide walks through the exact source code locations and commands needed to extend the system without breaking existing functionality.

Step 1: Create the Skill Directory and Entry Point

Every skill resides in its own folder under skills/ and must contain a SKILL.md file that serves as the master entry point.

# From the repository root

mkdir -p skills/my-new-skill
cat > skills/my-new-skill/SKILL.md <<'EOF'

# My New Skill

> Short description of what the skill does.

## Overview

Explain the workflow, required tools, and expected inputs/outputs.

## Steps

1. Prepare the environment.
2. Run the analysis.
3. Produce artifacts.

## References

- Link to any internal docs or external guides.
EOF

The router reads the skill field from routing.json and opens this markdown file when the route is selected. You may also add supporting files like tool configurations or reference materials in subdirectories such as references/.

Step 2: Register the Skill in routing.json

Open skills/config/routing.json and add a new object under the "routes" key:

{
  "R41": {
    "label": "My New Skill",
    "skill": "my-new-skill/SKILL.md",
    "keywords": [
      {
        "must": "mynew|awesome|customkeyword",
        "note": "These terms will cause the router to select this skill."
      }
    ]
  }
}

Field	Purpose
Route ID (e.g., R41)	Unique identifier; check existing IDs in routing.json and pick the next unused number
label	Human-readable name for the routing matrix
skill	Path relative to skills/ pointing to your SKILL.md
keywords	Matching rules using "must", "mustAll", or "exclude" regex patterns

The router first evaluates all routes whose keyword rules match, then selects the winner based on the "priority" array order. Insert your new route ID into this array at the appropriate position:

"priority": [
  "R4", "R1", "R39", "R41", "R0"
]

Place IDs near the top for high-priority matching, or near the bottom (just before the fallback R0) for catch-all behavior.

Step 3: Regenerate Indexes and Verify Routing

Run three PowerShell scripts to update auto-generated files and validate your changes:

# Regenerate the central navigation index from SKILL.md frontmatter

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/extract-summaries.ps1

# Verify routing.json matches MASTER-ROUTING.md priority order

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/verify-routing-coherence.ps1

# Execute the 163-case regression suite to detect broken routes

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/test-routing.ps1

These scripts serve distinct purposes according to the reverse-skill source:

• extract-summaries.ps1 — Parses frontmatter from every SKILL.md and rebuilds skills/INDEX.md, the central navigation index referenced by the README
• verify-routing-coherence.ps1 — Cross-checks that MASTER-ROUTING.md priority order matches routing.json
• test-routing.ps1 — Runs the full routing regression suite; any failure will block CI

Address any reported errors before committing your changes.

Step 4: Update Documentation and Tool Index (Optional)

For complete integration:

• Add a description to README.md so contributors discover the new skill
• Run skills/scripts/refresh-tool-index.* for your platform if the skill requires external binaries, ensuring skills/tool-index.md reflects tool availability

Summary

• Create skills/<new-skill>/SKILL.md as the entry point with workflow documentation and references
• Add a route object to skills/config/routing.json with unique ID, label, skill path, and keyword rules
• Insert the new route ID into the "priority" array to control evaluation order
• Run extract-summaries.ps1 to regenerate skills/INDEX.md
• Run verify-routing-coherence.ps1 to validate priority consistency with MASTER-ROUTING.md
• Run test-routing.ps1 to confirm all 163 regression cases pass
• Optionally update README documentation and refresh the tool index

Frequently Asked Questions

What file format must the skill entry point use?

The entry point must be a SKILL.md markdown file. The router specifically expects this filename and parses its frontmatter to populate the auto-generated index. No other file extensions are recognized as skill entry points.

How do I choose a route ID that won't conflict with future additions?

Route IDs follow the pattern R<number> where the number increments sequentially. Examine the existing "routes" object in skills/config/routing.json to find the highest current number, then use the next integer. The project maintains this convention to prevent collisions during parallel development.

What happens if I forget to update the priority array?

The router will fail to resolve your new skill deterministically. Requests matching your keywords may fall through to lower-priority routes, or the coherence verification script will flag the mismatch between routing.json and MASTER-ROUTING.md. Always include the new ID in the priority array and run the verification suite before submitting.

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