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

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 (lines 3‑6) enforces client‑neutrality across all operations
• Structured routing data: skills/config/routing.json contains machine‑readable rules
• Human‑readable matrix: 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 stores absolute tool paths
• Universal bootstrap scripts: skills/scripts/bootstrap-reverse.ps1 and 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 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

---

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 to initialize the routing system
2. Detect repository root — Derived from the location of RULES.md
3. Run primary ladder — 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; trigger bootstrap if tools are missing
6. Execute skill — The selected skill's 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 (Windows)

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

# Bash (Linux/macOS/Kali)

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

The script reads skills/config/routing.json, consults skills/tool-index.md, and writes the selected skill path to work/master-route-<ts>/route-scope.md.

Refreshing the Shared Tool Index

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

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

All clients subsequently read skills/tool-index.md to obtain absolute tool locations.

Bootstrapping a Missing Tool

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

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

The manifest 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	Global single source of truth; enforces client‑neutrality
skills/config/routing.json	Structured routing data used by all clients
skills/routing.md	Human‑readable 3‑axis matrix
skills/MASTER-ROUTING.md	Primary fast‑track ladder for skill selection
skills/scripts/master-route.ps1 / master-route.sh	Platform‑agnostic entry points
skills/scripts/case-init.ps1 / case-init.sh	Case scaffolding and auth gate enforcement
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	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 and skills/routing.md
• Platform‑agnostic scripts in PowerShell, Bash, and Python with no client dependencies
• Shared tool index at 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, 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 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, or any core file. The adapter is purely instructional; the core routing flow remains untouched.

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