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

Adding a custom skill requires four coordinated steps: create a skill directory with the required skeleton, write a compliant SKILL.md, update the routing matrix in 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: master routing → primary SKILL.md → optional 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.

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 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 for specific mandatory sections. Missing these blocks causes routing failures. Copy the template from skills/CONTRIBUTING.md and ensure these elements are present:

---
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 for dimensional matching and the root SKILL.md for module registration.

Editing 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:

## 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:

## 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:

## By Toolchain

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

Updating Root SKILL.md for Module Discovery

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

## 已注册 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, then regenerate the tool index:

# 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 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
2. Enter — Loads the matched 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, which may propose creating a new skill.

Key Files for Custom Skill Development

File	Purpose
skills/MASTER-ROUTING.md	Defines the three-step routing contract and master routing logic
skills/routing.md	The dimensional routing matrix you extend with new rules
skills/CONTRIBUTING.md	Authoritative template for SKILL.md structure and conventions
skills/SKILL.md (root)	Top-level skill registry; update when adding modules
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
• Write a SKILL.md containing ACTION REQUIRED and "任务完成自检" mandatory blocks
• Update routing.md with dimensional rules (target type, user intent, toolchain) and register in root 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 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 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, and the 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 and skill-level SKILL.md?

The root skills/SKILL.md is a registry — a flat list of all available skills for module discovery. Each skill's SKILL.md is an executable contract containing the workflow, requirements, and quality gates that the router actually runs.

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