# Client‑Neutral Architecture in reverse‑skill: A Portable AI Routing Framework

> Explore the client-neutral architecture in reverse-skill. This three-layer design enables seamless AI routing across various clients like Claude Code, Codex, and Cursor without custom code.

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

---

**The client‑neutral architecture in reverse‑skill is a three‑layer design that lets any AI coding client (Claude Code, Codex, Cursor, OpenCode, etc.) drive the same routing workflow without client‑specific code.**

This architecture separates core routing logic, tool discovery, and optional adapters into isolated, platform‑agnostic components. According to the **reverse‑skill** source code, this design ensures portability across operating systems and prevents any single client from bypassing authorization controls.

---

## Three Layers of the Client‑Neutral Design

The **client‑neutral architecture** in **reverse‑skill** (as implemented in `zhaoxuya520/reverse‑skill`) organizes functionality into distinct layers that never depend on a particular AI client.

### Layer 1: Core Routing & Contracts

This layer determines *what* skill to run, validates authorization, and defines execution contracts.

- **Single source of truth**: [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) (lines 3‑6) enforces client‑neutrality across all operations
- **Structured routing data**: [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) contains machine‑readable rules
- **Human‑readable matrix**: [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) provides a 3‑axis view (target / intent / toolchain)

All routing enforcement happens through generic scripts in `skills/scripts/`. These scripts never reference a particular AI client. The authoritative rule set lives at the repository root and serves as the entry point for every client.

### Layer 2: Tool Discovery & Bootstrap

This layer detects locally installed tools, installs missing ones, and maintains a shared registry.

- **Platform‑agnostic registry**: [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) stores absolute tool paths
- **Universal bootstrap scripts**: `skills/scripts/bootstrap-reverse.ps1` and [`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh) handle installation
- **No hard‑coded paths**: All clients read the same index file

When a tool is missing, the bootstrap scripts use [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) to enumerate supported capabilities. This prevents ad‑hoc tool names from entering the system.

### Layer 3: Optional Client Adapters

Thin wrappers for specific hosts live in isolated documentation folders.

- **Complete isolation**: Adapters reside in folders like `kali/README‑kali.md` or `docs/platforms/*.md`
- **Never required**: The core routing flow runs entirely without adapters
- **Clean boundary**: Documented in the "Client integration boundary" section of [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)

---

## Execution Flow: How Clients Interact With the Core

The **client‑neutral architecture** follows a strict sequence that any AI client can trigger:

1. **Load the contract** — Read [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) to initialize the routing system
2. **Detect repository root** — Derived from the location of [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)
3. **Run primary ladder** — [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) or `skills/scripts/master-route.ps1` selects a *PRIMARY* skill based on JSON rules
4. **Initialize the case** — `skills/scripts/case-init.ps1` creates `work/<case>/scope.md` and verifies `auth.status=granted`
5. **Verify tools** — Read [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md); trigger bootstrap if tools are missing
6. **Execute skill** — The selected skill's [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) runs using standard contract and evidence‑chain mechanisms (`ops/*`)
7. **Optional adapter loading** — Client‑specific configuration only if needed; core never depends on it

Every step uses language‑agnostic scripts (PowerShell, Bash, Python) and data files (JSON, Markdown). The system works unchanged on Windows, Linux, macOS, or Kali.

---

## Running the Client‑Neutral Scripts

### Primary Routing From Any Client

```powershell

# PowerShell (Windows)

powershell -NoProfile -ExecutionPolicy Bypass `
  -File "skills/scripts/master-route.ps1" -Hint "analyze malicious APK"

```

```bash

# Bash (Linux/macOS/Kali)

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

```

The script reads [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), consults [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md), and writes the selected skill path to `work/master-route-<ts>/route-scope.md`.

### Refreshing the Shared Tool Index

```powershell
powershell -NoProfile -ExecutionPolicy Bypass `
  -File "skills/scripts/refresh-tool-index.ps1"

```

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

```

All clients subsequently read [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) to obtain absolute tool locations.

### Bootstrapping a Missing Tool

```powershell
powershell -NoProfile -ExecutionPolicy Bypass `
  -File "skills/scripts/bootstrap-reverse.ps1" -Capability @('jadx') -StartServices

```

```bash
bash skills/scripts/bootstrap-reverse.sh jadx --start-services

```

The manifest [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) enumerates supported capabilities, ensuring no ad‑hoc tool names are introduced.

---

## Why Client‑Neutrality Matters

The **reverse‑skill** source code emphasizes four advantages of this architecture:

| Advantage | Implementation |
|-----------|---------------|
| **Portability** | Same repository works with dozens of agents without modification |
| **Safety** | Client‑specific logic cannot bypass the `auth.status=granted` gate |
| **Maintainability** | Routing rules, tool definitions, and evidence contracts evolve in one place; adapters add or remove without touching core logic |
| **Testability** | Regression suite (`skills/scripts/test-routing.ps1`) validates 163 benchmark cases on Windows and Ubuntu, guaranteeing client independence |

---

## Key Files in the Client‑Neutral Architecture

| File | Role |
|------|------|
| [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) | Global single source of truth; enforces client‑neutrality |
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Structured routing data used by all clients |
| [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md) | Human‑readable 3‑axis matrix |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | Primary fast‑track ladder for skill selection |
| `skills/scripts/master-route.ps1` / [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) | Platform‑agnostic entry points |
| `skills/scripts/case-init.ps1` / [`case-init.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/case-init.sh) | Case scaffolding and auth gate enforcement |
| [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) | Shared registry of absolute tool paths |
| `skills/scripts/bootstrap-reverse.*` | Generic bootstrap for missing capabilities |
| `skills/scripts/refresh-tool-index.*` | Updates the shared tool index |
| [`skills/INDEX.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/INDEX.md) | Auto‑generated client‑neutral navigation index |

---

## Summary

The **client‑neutral architecture** in **reverse‑skill** delivers a portable, secure routing framework through these design principles:

- **Declarative routing contract** in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and [`skills/routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/routing.md)
- **Platform‑agnostic scripts** in PowerShell, Bash, and Python with no client dependencies
- **Shared tool index** at [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) that all clients consume uniformly
- **Isolated optional adapters** that never interfere with core routing logic
- **Authorization gate** (`auth.status=granted`) enforced before any skill execution

---

## Frequently Asked Questions

### What makes reverse‑skill "client‑neutral" compared to other AI routing systems?

Most AI routing systems embed client‑specific logic in their core workflows. **reverse‑skill** keeps all routing rules in language‑agnostic data files ([`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json), [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md)) and generic scripts. Client adapters are strictly optional and isolated. Any AI client that can execute shell commands can drive the system without code changes.

### Can I use reverse‑skill with Claude Code, Cursor, and Codex simultaneously?

Yes. Clone the repository once. Each client invokes the same entry point—`skills/scripts/master-route.ps1` on Windows or [`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh) on Unix systems. The routing decisions depend on the hint you provide and the structured rules, not on which client initiated the request.

### How does the architecture prevent clients from bypassing security controls?

The authorization gate (`auth.status=granted`) is enforced in `skills/scripts/case-init.ps1` before any skill runs. Because this script is part of the client‑neutral core— not an adapter—no client can skip it. Clients can only invoke the provided scripts; they cannot inject alternative workflows.

### Where should I add support for a new AI client like OpenCode?

Create a folder such as `adapters/opencode/` with documentation explaining working directory setup and script invocation. Do not modify `skills/scripts/`, [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json), or any core file. The adapter is purely instructional; the core routing flow remains untouched.