# How Skill Modules Are Organized in reverse-skill: A Complete Architecture Guide

> Discover how reverse-skill organizes security capabilities into a modular skill router with 25+ domain-specific modules under skills/. Learn about the standardized SKILL.md file.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: architecture
- Published: 2026-08-25

---

**The reverse-skill repository organizes security capabilities into a modular skill router with 25+ domain-specific modules under `skills/`, each containing a standardized [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file that defines scope, required tools, and execution workflow.**

The **reverse-skill** project is a comprehensive security research framework that structures every capability as an independent, routable module. According to the source code in `zhaoxuya520/reverse-skill`, this architecture enables automated task routing, consistent documentation, and reproducible workflows across reverse engineering, penetration testing, and digital forensics disciplines.

## Three-Layer Architecture of Skill Modules

The codebase implements a clean separation of concerns across **Routing**, **Domain-Specific Skills**, and **Supporting Infrastructure** layers.

### Routing Layer

The routing layer determines which skill module executes a given task. It resides primarily in two locations:

- **[`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md)** — Master catalogue containing the complete module index
- **[`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json)** — Machine-readable routing table that maps task hints to skill directories

The platform-native router scripts—[`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) (Linux/macOS/Kali) and `skills/scripts/master-route.ps1` (Windows)—implement the routing logic. These scripts read [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json) to identify the **PRIMARY** skill, with fallback to [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) if the initial match fails.

### Domain-Specific Skill Modules

Each skill module lives in its own directory under `skills/` with a **mandatory standardized structure**:

```

skills/<module-name>/
│   SKILL.md            ← Required: module description, workflow, tool list
│   references/         ← Optional: cheatsheets, guides, external resources
│   … (module-specific scripts, configurations, or data files)

```

The [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file follows a strict contract. Here's the structure from [`skills/apk-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/apk-reverse/SKILL.md):

```markdown
---
name: apk-reverse
description: Android APK reverse-engineering (decompile, hook, re-sign)
---

# Workflow

1. Decode APK → `apktool` (bootstrap if missing)
2. Decompile → `jadx` (or `jeb-pro` if licensed)
3. Dynamic analysis → `frida` scripts
4. Re-package & sign → `apksigner`
5. Generate report → `docs-generator`

```

This **YAML-frontmatter + Markdown workflow** pattern repeats across every module, enabling automated parsing and execution.

### Supporting Infrastructure

Shared services that all skills consume include:

- **[`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md)** — Auto-generated inventory of available tools with paths and versions
- **[`field-journal/_index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/field-journal/_index.md)** — Evolving knowledge base of past case experiences
- **`docs-generator/`** — Automated report and diagram generation post-execution
- **`skills/scripts/case-init.{sh|ps1}`** — Case initialization with scope creation and authentication enforcement

## Complete Skill Module Inventory

The master [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) file catalogs 25+ specialized modules. Below are the core capabilities organized by security domain:

| Module | Directory | Primary Use Case |
|--------|-----------|----------------|
| **通用逆向** (General Reverse Engineering) | `reverse-engineering/` | GDB, Frida, angr, Unicorn, anti-analysis |
| **APK 逆向** | `apk-reverse/` | Android APK unpacking, jadx decompilation, Frida hooking |
| **.NET / C# 逆向** | `dotnet-reverse/` | Managed PE analysis with dnSpy and de4dot |

| **IDA Pro 逆向** | `ida-reverse/` | IDA MCP service, cross-references, data flow tracking |
| **前端 JS 逆向** | `js-reverse/` | Browser signature extraction, crypto parameter analysis |
| **radare2 分析** | `radare2/` | CLI binary reconnaissance and patching |
| **Ghidra 逆向** | `ghidra-reverse/` | Open-source decompilation, headless MCP automation |
| **CTF 入口** | `ctf-sandbox/` | Unified CTF entry point with orchestrator sub-skills |
| **RE → 利用链** | `pwn-chain/` | Stack, heap, and kernel exploitation with pwntools |
| **固件渗透链** | `firmware-pentest/` | OWASP FSTM nine-phase approach: emulation → fuzzing → exploitation |
| **EDR 绕过逆向** | `edr-bypass-re/` | EDR hook tables, ETW, AMSI, hardware breakpoint analysis |
| **恶意软件分析** | `malware-analysis/` | YARA, Sigma, sandbox orchestration |
| **移动逆向工程** | `mobile-reverse/` | Android + iOS Frida / Objection workflows |
| **N-day 补丁差分 → 利用** | `patch-diff-exploit/` | Vulnerability point localization and PoC development |
| **跨版本符号迁移** | `binary-diff/` | Symbol migration and PDB derivation |
| **数字取证** | `digital-forensics/` | Memory/disk timeline analysis, PCAP traceability |
| **代码审计 / SAST** | `code-audit/` | Semgrep and CodeQL security reviews |
| **API 安全测试** | `api-security/` | REST, GraphQL, WebSocket protocol testing |
| **LLM / AI 安全测试** | `llm-security/` | Prompt injection, tool abuse, memory poisoning |
| **供应链安全** | `supply-chain-security/` | SBOM, SCA, CI-CD pipeline security |
| **云 / 容器 / K8s** | `cloud-k8s/` | IMDS, container escape, RBAC analysis |
| **Windows / AD** | `windows-ad/` | Kerberos, BloodHound, domain path mapping |
| **浏览器 & 桌面自动化** | `browser-automation/` | Playwright with OpenReverse UIA/CUA |
| **攻击链编排** | `attack-chain/` | Multi-stage attack path planning and execution |
| **图表生成** | `diagram-generator/` | Mermaid, Graphviz, PlantUML visualization |

Additional specialized modules include `dsl-vm-re/` for custom instruction set VM analysis and ongoing expansion areas.

## How the Router Resolves Skills

The skill resolution process follows a deterministic three-step pipeline defined in [`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md):

1. **Hint parsing** — The `master-route` script receives a task hint (e.g., `"analyze suspicious APK"`)
2. **Primary lookup** — Query [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json) for exact match; if found, dispatch to that skill's [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md)
3. **Fallback matrix** — On miss, consult [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) three-axis matrix (target type × user intent × tool chain)

Once resolved, the selected skill's [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) becomes the **execution contract**—the router drives the documented workflow step-by-step.

## Practical Skill Module Interactions

### Route a Task to Its Primary Skill (Unix)

```bash
bash skills/scripts/master-route.sh --hint "analyze suspicious APK"

# Reads config/routing.json → selects apk-reverse as PRIMARY

```

### Initialize a New Case (Windows)

```powershell
powershell -File skills/scripts/case-init.ps1 -Hint "malware analysis of sample X"

# Verifies authentication, creates work/<case>/scope.md, enforces hard gate

```

### Minimal SKILL.md Template Structure

```markdown
---
name: <module-name>
description: <one-line capability summary>
---

# Workflow

1. <step> → <tool> (<bootstrap behavior>)
2. ...
N. Generate report → `docs-generator`

```

## Key Files Governing Skill Module Organization

| File | Purpose |
|------|---------|
| [`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md) | System diagram and module relationship map |
| [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) | Canonical skill catalogue with full module list |
| [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json) | Primary routing table (hint → directory mapping) |
| `skills/scripts/master-route.{sh\|ps1}` | Cross-platform router implementations |
| `skills/scripts/case-init.{sh\|ps1}` | Case initialization with scope enforcement |
| [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) | Auto-generated tool inventory |
| [`field-journal/_index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/field-journal/_index.md) | Experience-derived knowledge base |

## Summary

- **Skill modules** in reverse-skill are self-contained directories under `skills/`, each with a mandatory [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) contract
- **Standardized structure**: YAML frontmatter for metadata, Markdown workflow for execution steps, optional `references/` for documentation
- **Routing system** uses [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json) for primary dispatch with [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) fallback matrix
- **Cross-platform router scripts** ([`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh)/`master-route.ps1`) automate skill selection
- **Infrastructure services** ([`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md), `field-journal`, `docs-generator`) provide shared capabilities to all modules

## Frequently Asked Questions

### How does reverse-skill decide which skill module to execute?

The router scripts ([`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) or `master-route.ps1`) first consult [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json) for a PRIMARY match based on the task hint. If no exact match exists, the system falls back to [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md), which contains a three-axis decision matrix evaluating target type, user intent, and required tool chain.

### What must every skill module include to be recognized by the router?

Every valid skill module must contain a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) file in its root directory with YAML frontmatter specifying `name` and `description`, followed by a Markdown workflow section. This file serves as both documentation and execution contract—the router parses it to drive the skill's step-by-step operation.

### Can I add custom skill modules to reverse-skill?

Yes. Create a new directory under `skills/`, add a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) following the established YAML+Markdown structure, then register the module in both [`skills/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/SKILL.md) (catalogue) and [`config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/config/routing.json) (routing table). The router will automatically include it in task resolution.

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

[`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) is a **global, auto-generated inventory** of all available tools across the entire framework with their installation paths and versions. Individual [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files are **module-specific execution contracts** that declare which subset of tools that particular skill requires and how they orchestrate together.