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

> Learn how to add a new skill to the reverse-skill package with this step-by-step guide. Create a skill directory, register it in routing.json, and regenerate the index.

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

---

**Adding a new skill to the reverse-skill package requires creating a skill directory with a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) entry point, registering the skill in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file that serves as the **master entry point**.

```bash

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and add a new object under the `"routes"` key:

```json
{
  "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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```json
"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:

```bash

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) and rebuilds [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md), the central navigation index referenced by the README
- **`verify-routing-coherence.ps1`** — Cross-checks that [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md) priority order matches [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md)
- Run `verify-routing-coherence.ps1` to validate priority consistency with [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) and [`MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/MASTER-ROUTING.md). Always include the new ID in the priority array and run the verification suite before submitting.