How to Add a New Custom Skill to the MASTER-ROUTING.md Matrix

To add a new custom skill to the MASTER-ROUTING.md matrix, create a skill folder containing a structured SKILL.md definition, register the skill in the priority table with a unique Rxx identifier, and validate the routing using the provided PowerShell scripts.

The MASTER-ROUTING.md file serves as the primary fast-path routing mechanism in the zhaoxuya520/reverse-skill repository, mapping task hints to concrete skill implementations via a priority-based lookup table. Adding a custom skill requires registering it in this matrix to ensure automated discovery and proper resolution. This guide references the actual source file paths, including the priority table at lines 49-90 in skills/MASTER-ROUTING.md, to walk through the complete integration process.

Create the Skill Package

Start by establishing the skill folder structure and documentation. Choose a logical category (such as wifi-wireless/ or a new top-level directory) and create a folder containing a SKILL.md file.

In SKILL.md, include a clear title, a concise description, and the primary tag (such as R31). The file should follow the standard template used across the repository, beginning with a header and detailing the contract, inputs, and outputs. Refer to existing skill definitions like skills/wifi-wireless/SKILL.md for the exact formatting conventions.

A proper skill definition includes three main sections:

• 契约 (Contract): Defines inputs (e.g., PCAP files, protobuf definitions) and outputs (e.g., protocol documentation, decode scripts)
• 实现 (Implementation): Lists required tools and workflows (e.g., protoc, Wireshark plugins)
• 参考 (References): Links to external documentation and dependencies

Register the Skill in the Routing Matrix

Open skills/MASTER-ROUTING.md and locate the Priority table (lines 49-90). This table maps task hints to skill folders using a three-column format.

Append a new row with the following components:

• ID: A unique Rxx identifier (e.g., R40) or reuse an existing one if the skill fits an existing category
• Condition: Keywords that will appear in user hints (e.g., "新的协议分析 / protobuf / gRPC")
• PRIMARY: The relative path to your new skill folder (e.g., my-protocol-reverse/)

Example entry:

| **R40** | 新的协议分析 / protobuf / gRPC | `my-protocol-reverse/` |

This syntax mirrors existing entries such as | **R21** | 协议 / Protobuf / PCAP 协议 | \protocol-reverse/` |` found in the matrix. Place your entry among the other rows in the "Priority (高 → 低)" table to establish its resolution priority.

Update the Auxiliary Matrix (Optional)

For secondary routing or documentation completeness, you may also register the skill in skills/routing.md. This full three-axis matrix provides additional context for ambiguity resolution. While optional for basic skill registration, updating this file ensures comprehensive coverage across all routing mechanisms in the repository.

Validate the Routing Configuration

After registering the skill, verify that the hint-to-skill mapping resolves correctly using the provided PowerShell scripts.

Run the routing helper script to test your specific hint:

powershell -File skills/scripts/master-route.ps1 -Hint "分析 protobuf 协议"

The script parses MASTER-ROUTING.md and should return the path to your new skill, typically generating a file at work/master-route-<timestamp>/route-scope.md pointing to your skill folder.

Next, execute the coherence checker to ensure matrix consistency:

powershell -File skills/scripts/verify-routing-coherence.ps1

This validation step confirms no duplicate IDs exist and that all entries follow the required syntax, preventing ambiguous routing scenarios.

Code Examples

Sample SKILL.md for Protocol Reverse Engineering

Create the following content in your new skill folder (e.g., skills/my-protocol-reverse/SKILL.md):

# My Protocol Reverse Engineering

## 契约

- **输入**: PCAP / protobuf 定义文件  
- **输出**: 协议文档、解码脚本、示例流量

## 实现

- 使用 `protoc` 生成解析代码  
- 通过 `Wireshark` 插件自动化解析

## 参考

- https://github.com/protocolbuffers/protobuf
- https://github.com/wireshark/wireshark

This structure aligns with existing skill files such as skills/wifi-wireless/SKILL.md, ensuring consistency across the repository.

Routing Table Entry Format

Add this line to the priority table in skills/MASTER-ROUTING.md:

| **R40** | 新的协议分析 / protobuf / gRPC | `my-protocol-reverse/` |

Ensure the entry appears within lines 49-90 among the other priority rows.

Verification Command Output

Expected output when testing the new routing:

# Command:

powershell -File skills/scripts/master-route.ps1 -Hint "分析 protobuf 协议"

# Expected result:

work/master-route-<timestamp>/route-scope.md → my-protocol-reverse/

Key Files in the Routing Architecture

Understanding the repository's routing structure helps ensure proper skill integration:

• skills/MASTER-ROUTING.md: The primary routing matrix where new skills must be registered with unique Rxx identifiers
• skills/scripts/master-route.ps1: Helper script that parses the master matrix and resolves user hints to skill paths
• skills/routing.md: Optional three-axis matrix for secondary routing and comprehensive documentation
• skills/scripts/verify-routing-coherence.ps1: Consistency checker that validates matrix integrity and prevents duplicate IDs
• <your-skill>/SKILL.md: The skill definition file containing contract, implementation, and reference documentation

Summary

Adding a custom skill to the MASTER-ROUTING.md matrix involves four critical actions:

• Create a dedicated skill folder containing a properly structured SKILL.md with contract and implementation details
• Register the skill in skills/MASTER-ROUTING.md by adding a row to the priority table (lines 49-90) with a unique Rxx ID, condition keywords, and folder path
• Validate the routing using master-route.ps1 to confirm hint resolution and verify-routing-coherence.ps1 to check matrix consistency
• Commit the new folder, skill documentation, and updated routing files following the repository's contribution workflow

This process maintains the repository's fast-path routing architecture and enables automated skill discovery.

Frequently Asked Questions

What format should I use for the skill ID in the routing matrix?

Use the Rxx format where xx represents a unique number (e.g., R40, R41). According to the source code in skills/MASTER-ROUTING.md, existing entries use identifiers like R21 for protocol-related skills. Choose a number that doesn't conflict with existing IDs in the priority table.

Do I need to update both MASTER-ROUTING.md and routing.md?

Updating skills/MASTER-ROUTING.md is mandatory as it serves as the primary fast-path routing mechanism. Updating skills/routing.md is optional and only necessary if you want the skill available in the full three-axis matrix for secondary routing or enhanced documentation coverage.

How do I ensure my skill routing doesn't conflict with existing entries?

Run skills/scripts/verify-routing-coherence.ps1 after adding your entry. This script checks for duplicate IDs and ambiguous routing conditions across the matrix. Additionally, test your specific hint using master-route.ps1 to verify it resolves to your intended skill folder rather than an existing one.

What should I include in the SKILL.md file to match repository standards?

Follow the three-section structure used in existing skills like skills/wifi-wireless/SKILL.md: include a 契约 section defining inputs and outputs, an 实现 section detailing tools and workflows, and a 参考 section listing external dependencies. Start the file with a clear H1 header describing the skill's purpose.

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