# How to Add a Custom Skill or Routing Rule to the reverse-skill Routing Matrix

> Learn how to add a custom skill or routing rule to the reverse-skill routing matrix. Follow four simple steps to integrate your new logic seamlessly.

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

---

**Adding a custom skill requires four coordinated steps: create a skill directory with the required skeleton, write a compliant [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md), update the routing matrix in [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md), and refresh the tool index so the bootstrap system can locate any new binaries.**

The reverse-skill framework routes every request through a strict three-layer hierarchy defined in [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md): **master routing** → **primary SKILL.md** → **optional [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) disambiguation**. To add a custom skill or routing rule, you must extend this matrix so the router can match new target types, user intents, or toolchains to your capability. This guide walks through the complete implementation based on the source code in `zhaoxuya520/reverse-skill`.

## The Four-Step Process to Add a Custom Skill

### Step 1: Create the Skill Directory Skeleton

Every skill lives under `skills/<skill-name>/` and must include a mandatory structure. The template is defined in [`skills/CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/CONTRIBUTING.md).

```bash
skills/
└── my-custom-skill/
    ├── SKILL.md          # required: entry document with mandatory sections

    ├── scripts/          # optional: automation scripts

    │   └── analyze.ps1
    └── references/       # optional: reference materials

        └── cheat-sheet.md

```

Directory naming follows kebab-case conventions. The [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file is the **only required file**; `scripts/` and `references/` are optional but recommended for complex workflows.

### Step 2: Write a Compliant SKILL.md Entry Document

The router parses [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) for specific mandatory sections. Missing these blocks causes routing failures. Copy the template from [`skills/CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/CONTRIBUTING.md) and ensure these elements are present:

```markdown
---
name: my-custom-skill
description: 自动化分析 XYZ 类型文件的完整工作流
---

# My Custom Skill

## 适用范围

<!-- 说明哪些任务应路由到这里 -->

## 工具依赖

| 工具 | 是否必需 | 用途 | 可自动安装 |
|------|----------|------|-------------|
| xyz-tool | ✅ | 解析 XYZ 文件 | ✅ |

## 工作流

1. `NOW`：确认目标文件是 XYZ 类型。
2. `NOW`：读取 `../tool-index.md`，校验 `xyz-tool` 是否可用。
3. `NEXT`：若缺工具，调用 bootstrap。
4. `ACT`：运行 `scripts/analyze.ps1` 并产出报告。

## ACTION REQUIRED（读完后立刻执行）

1. `NOW`：确认当前任务是否命中本 skill。
2. `NOW`：检查 `xyz-tool` 在 `tool-index.md` 中是否可用。
3. `NEXT`：缺工具时执行 bootstrap。
4. `ACT`：进入工作流第一步并执行。

## 任务完成自检（声称完成前 MUST 通过）

- □ 我是否执行了工作流中的每一步？
- □ 我是否基于 `tool-index` 使用了真实工具路径？
- □ 我是否产出了可复现的证据（命令/脚本/报告）？

```

**Critical required blocks:**
- **`ACTION REQUIRED`** — Tells the executor exactly what to do immediately after reading
- **"任务完成自检"** — Quality gate that must pass before the skill reports completion
- **Language-behavior contract** — Defines when this skill accepts a request

### Step 3: Update the Routing Matrix

The routing matrix spans two files: [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) for dimensional matching and the root [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) for module registration.

#### Editing [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) for Dimensional Routing

The router matches on three dimensions. Add entries to the appropriate table:

**By Target Type** — File format or system component being analyzed:

```markdown

## By Target Type

| Target Type | Recommended Entry | Alternative |
|-------------|------------------|-------------|
| XYZ / custom binary | `my-custom-skill/` — 自动化 XYZ 解析 | `binary-diff/` — 如需跨版本比较 |

```

**By User Intent** — Natural language phrases that trigger routing:

```markdown

## By User Intent

| User Says | Route To |
|-----------|----------|
| "解析 XYZ 文件" | `my-custom-skill/` |
| "analyze XYZ binary" | `my-custom-skill/` |

```

**By Toolchain** — Specific tools or MCP servers involved:

```markdown

## By Toolchain

| Primary Tool | Route To | Fallback |
|--------------|----------|----------|
| xyz-tool | `my-custom-skill/` | `generic-binary/` |

```

#### Updating Root [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) for Module Discovery

Add your skill to the top-level skill list so the master router knows it exists:

```markdown

## 已注册 Skill 模块

| Skill | 用途 | 入口 |
|-------|------|------|
| ... | ... | ... |
| my-custom-skill | XYZ 文件自动化分析 | `skills/my-custom-skill/SKILL.md` |

```

### Step 4: Refresh the Tool Index

If your skill introduces new tools or MCP servers, register them in [`scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/bootstrap-manifest.json), then regenerate the tool index:

```powershell

# Windows

powershell -NoProfile -ExecutionPolicy Bypass -File skills\scripts\refresh-tool-index.ps1

# Linux / macOS

bash skills/scripts/refresh-tool-index.sh

```

This updates [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) with real tool paths, enabling the `ACTION REQUIRED` block to validate tool availability before execution.

## How the Router Uses Your Custom Skill

The master routing implementation in `skills/scripts/master-route.ps1` processes requests through this flow:

1. **Match** — Compares request against target type, user intent, and toolchain tables in [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md)
2. **Enter** — Loads the matched [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) and validates mandatory sections
3. **Execute** — Runs the `ACTION REQUIRED` workflow, auto-installing missing tools via bootstrap if declared

If no match exists, the router triggers the **"Route Not Matched – Handling"** protocol defined in [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md), which may propose creating a new skill.

## Key Files for Custom Skill Development

| File | Purpose |
|------|---------|
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Defines the three-step routing contract and master routing logic |
| [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) | The dimensional routing matrix you extend with new rules |
| [`skills/CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/CONTRIBUTING.md) | Authoritative template for [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) structure and conventions |
| [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) (root) | Top-level skill registry; update when adding modules |
| [`scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/bootstrap-manifest.json) | Tool and MCP server registration for auto-installation |
| `skills/scripts/refresh-tool-index.ps1` | Regenerates tool indices after manifest changes |
| `skills/scripts/master-route.ps1` | The router implementation that consumes your matrix entries |

## Summary

- **Create** a directory under `skills/` with the required skeleton from [`CONTRIBUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/CONTRIBUTING.md)
- **Write** a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) containing `ACTION REQUIRED` and "任务完成自检" mandatory blocks
- **Update** [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) with dimensional rules (target type, user intent, toolchain) and register in root [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md)
- **Refresh** the tool index via `refresh-tool-index.ps1` if new tools are introduced
- The **master router** in `master-route.ps1` matches, enters, and executes your skill automatically

## Frequently Asked Questions

### What happens if I forget to update [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) after creating a skill?

The router in `skills/scripts/master-route.ps1` will not match requests to your new skill, triggering the "Route Not Matched – Handling" protocol. This either falls back to a generic skill or prompts skill creation. Your skill exists but is unreachable until you add dimensional routing rules.

### Can a skill work without the `scripts/` and `references/` directories?

Yes. Only [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) is mandatory. The `scripts/` directory holds optional automation code, and `references/` stores supplementary materials. Simple skills that rely entirely on external tools need only the entry document with proper `ACTION REQUIRED` instructions.

### How does the bootstrap system know which tools to install?

Tool availability is declared in two places: the `工具依赖` table within your [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md), and the [`scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/bootstrap-manifest.json) file which maps tool names to installation sources. When `ACTION REQUIRED` detects a missing tool, it consults both to trigger auto-installation before proceeding.

### What is the difference between root [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) and skill-level [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md)?

The root [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) is a **registry** — a flat list of all available skills for module discovery. Each skill's [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) is an **executable contract** containing the workflow, requirements, and quality gates that the router actually runs.