# How the Client-Neutral Core of reverse-skill Works: Architecture and Execution Flow

> Discover how the client-neutral core of reverse-skill works. This three-layer engine maps natural language hints to security workflows, automates tool installation, and executes tasks across PowerShell Bash and AI clients.

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

---

**The client-neutral core of reverse-skill is a three-layer routing engine that maps natural-language hints to structured security workflows, automatically discovers and installs required tools, and executes tasks identically across PowerShell, Bash, and AI clients without platform-specific dependencies.**

The **reverse-skill** repository by zhaoxuya520 implements a truly **client-neutral core** that decouples cybersecurity task execution from any specific AI client or operating system. This architecture ensures that whether you invoke commands from Windows PowerShell, Linux Bash, macOS Terminal, or an MCP-compatible AI assistant, the routing logic and case lifecycle remain identical and auditable.

## Three-Layer Architecture of the Client-Neutral Core

The core consists of three tightly integrated layers that handle decision-making, execution, and continuous improvement.

### Routing Layer (Hint to Skill ID)

The **routing layer** serves as the decision engine that translates vague user hints into concrete skill identifiers. It maintains a single source of truth in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), which defines 41 distinct routing rules (R0-R40) mapping to specific security disciplines like APK reverse engineering, binary diffing, or CTF challenges.

For rapid resolution, [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) provides a fast-path contract that [`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) consult first. When the fast-path lookup fails to match a hint like *"analyze this APK"*, the engine falls back to [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md), a human-readable matrix that disambiguates similar requests and suggests the appropriate primary skill ID (e.g., `apk-reverse/`).

### Execution Layer (Case Lifecycle)

The **execution layer** drives the complete case lifecycle through platform-agnostic scripts. Once routing identifies a primary skill, [`skills/scripts/case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/case-init.sh) or `case-init.ps1` creates a scoped workspace at `work/<case>/`, populating it with [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md), a forensic timeline, and trackable work-items.

During execution, [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) (auto-generated) validates the availability of external dependencies like IDA Pro, radare2, or Frida. If a required tool is missing, the bootstrap process defined in [`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md) triggers automatic installation via GitHub releases, pip, npm, winget, or local HTTP MCP servers, updating [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) with installation metadata before proceeding.

### Evolution Layer (Knowledge Persistence)

The **evolution layer** ensures the system improves with each engagement. After skill execution completes, results flow into `field-journal/` as structured **Evidence → Finding → Path** entries. The `docs-generator/` and `diagram-generator/` modules then produce final markdown reports and visual diagrams, updating [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) to reflect new capabilities or routing refinements.

## From Natural Language to Skill Execution

The journey from a user hint to an executed security workflow follows a strict pipeline defined in [`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md).

### Fast-Path Routing with MASTER-ROUTING

When a hint enters the system—whether from a human operator or an AI client—the `master-route` scripts perform immediate classification:

```bash

# Linux/macOS/Kali: Fast-path routing to identify primary skill

bash skills/scripts/master-route.sh --hint "analyze this apk"

```

```powershell

# Windows: Equivalent PowerShell execution

powershell -File skills\scripts\master-route.ps1 -Hint "analyze this apk"

```

These scripts load [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and return a **PRIMARY** identifier (e.g., `apk-reverse/`) that points to the skill's [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) entry point. The fast-path prioritizes common security tasks (R1, R33, etc.) to minimize latency.

### Routing Matrix Fallback

If the fast-path returns ambiguous or null results, the engine consults [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) to disambiguate similar terms like *"reverse APK"* versus *"decompile Android"*. This secondary lookup ensures comprehensive coverage without bloating the primary routing table.

## Tool Discovery and Self-Bootstrap Mechanism

Before executing any skill, the core validates the tool chain through [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md). When `skills/scripts/case-init.*` detects a missing dependency, it references [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) to determine the correct installer for the host platform:

- **GitHub release zips** for standalone binaries
- **pip/npm** for Python and Node.js packages  
- **winget/apt** for system package managers
- **Local HTTP MCP** for proprietary toolchains

Once installation completes successfully, the new tool path is appended to [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md), and the skill execution proceeds without manual intervention.

## The Case Workflow Lifecycle

The **client-neutral core** orchestrates a repeatable four-phase workflow:

1. **Initialization**: `case-init` establishes the forensic workspace at `work/<case>/` with [`scope.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scope.md) defining boundaries and authorization levels per [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md).

2. **Execution**: The primary skill runs its internal scripts (e.g., `apk-reverse/analysis.ps1`), operating solely within the case directory to maintain evidence integrity.

3. **Evidence Collection**: Structured findings are written to `field-journal/` with full provenance chains, creating an auditable record independent of the invoking client.

4. **Report Generation**: `python3 skills/docs-generator/generate_report.py work/<case>/` consumes the field journal to produce standardized markdown reports and architectural diagrams.

```bash

# Complete Linux workflow example

bash skills/scripts/case-init.sh --hint "apk reverse" --case-name "malware-2024"
cd work/malware-2024

# ... skill execution happens here ...

python3 skills/docs-generator/generate_report.py work/malware-2024

```

```powershell

# Complete Windows workflow example

powershell -File skills\scripts\case-init.ps1 -Hint "apk reverse" -CaseName "malware-2024"

# ... skill execution ...

python3 skills\docs-generator\generate_report.py work\malware-2024

```

## Cross-Platform Client Neutrality

The core achieves true **client neutrality** by enforcing strict architectural boundaries: no AI client-specific code exists within the routing or execution layers. All logic is implemented in portable **PowerShell**, **Bash**, and **Python** scripts that interact through standardized JSON manifests and markdown contracts.

This design guarantees that the same routing logic works identically on Windows PowerShell, Linux/macOS Bash, and Kali environments. An AI client loads the repository and invokes `master-route.*` or `case-init.*` as subprocess calls, receiving structured output without needing to understand internal skill implementations.

## Summary

- The **client-neutral core** consists of three layers: routing (decision), execution (action), and evolution (learning).
- **Routing** uses [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) to map hints to skill IDs via fast-path or matrix fallback.
- **Tool discovery** relies on [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and automatic bootstrapping via [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) when dependencies are missing.
- **Case workflows** follow a standardized lifecycle: `case-init` → skill execution → `field-journal` persistence → `docs-generator` reporting.
- All components are implemented in cross-platform scripts (PowerShell/Bash/Python) ensuring identical behavior across Windows, Linux, macOS, and AI clients.

## Frequently Asked Questions

### What makes the reverse-skill core "client-neutral"?

The core contains no dependencies on specific AI client APIs, SDKs, or interfaces. All functionality is exposed through standard shell scripts ([`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh), `case-init.ps1`) and JSON configuration files ([`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json)). Any client—whether Claude, GPT, or a human terminal—invokes the same entry points and receives identical structured output, ensuring consistent security workflows regardless of the invocation method.

### How does the routing layer handle ambiguous or novel hints?

When a hint does not match the fast-path rules in [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md), the system falls back to [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md), a human-readable matrix that disambiguates similar security tasks. If no match exists, the routing engine returns a suggestion to create a new skill entry, triggering the evolution layer to document the gap in `field-journal/` for future routing updates.

### Can custom security skills be added without modifying the core?

Yes. New skills are added by creating a directory under `skills/` (e.g., `skills/custom-audit/`) containing a [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) entry point and execution scripts. You then register the skill in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) with a unique R-ID (e.g., R41) and update [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) with fast-path keywords. The existing `master-route` and `case-init` scripts automatically recognize and execute the new skill without code changes.

### Which operating systems does the client-neutral core support?

The core officially supports **Windows** (PowerShell 5.1+), **Linux** (Bash), **macOS** (Bash/Zsh), and **Kali Linux** (Bash). All scripts in `skills/scripts/` provide parallel implementations (`.ps1` for Windows, `.sh` for Unix-like systems), while Python components in `docs-generator/` and `diagram-generator/` are platform-agnostic. The [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) defines OS-specific installation commands, ensuring tools deploy correctly regardless of the host environment.