# Understanding the Client-Neutral Architecture Boundary in reverse-skill

> Discover the client-neutral architecture boundary in reverse-skill. Learn how this separation enables universal AI host workflows and simplifies reverse-engineering across multiple platforms.

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

---

**The client-neutral architecture boundary is a deliberate separation between the platform-independent core in the `skills/` directory and client-specific adapters, enabling the same reverse-engineering workflows to run across Claude Code, Cursor, Codex, and other AI hosts without modification.**

The *reverse-skill* repository implements a strict architectural boundary that keeps its security workflows and routing logic completely independent of any specific AI client. This design ensures that skill definitions, test suites, and documentation generators remain portable while thin platform-specific adapters handle client integration. Understanding this boundary is essential for anyone extending the system or integrating it with new AI development environments.

## What Is the Client-Neutral Architecture Boundary?

The **client-neutral architecture boundary** is an explicit design constraint that isolates platform-independent logic from client-specific implementation details. In the *reverse-skill* codebase, this manifests as a strict directory-level separation enforced by architectural rules.

The **core layer** lives entirely under the `skills/` directory and contains [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) definitions, [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) configuration, [`routing.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.md) documentation, the `field-journal/` knowledge base, and shared code generators. According to **RULES.md**, these files constitute the "platform-neutral core" and must not contain any configuration, scripts, or logic tied to a particular AI client or host.

Client-specific adapters reside outside this core. Platform-specific scripts are isolated in `skills/scripts/` (PowerShell for Windows, Bash for Linux/macOS) or `kali/scripts/` for Kali Linux environments. Platform-specific rule files like [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) and [`kali/RULES-kali.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/RULES-kali.md) extend the core without modifying it.

As documented in the source:

> "The files in `skills/`, routing configuration, tests, manifests, case artifacts, and reports are the platform-neutral core. A host such as Claude Code, Codex, Cursor, OpenCode, or another agent may load this repository through its own project-instruction or skill adapter, but **no host-specific file is required for routing or tests**."

The **ARCHITECTURE.md** diagram visualizes this as the **"共享层（平台无关）"** (shared layer) containing core skills, the CTF sandbox orchestrator, and documentation generators, while platform-specific scripts sit outside this boundary.

## Why the Client-Neutral Boundary Matters

This architectural pattern delivers five critical benefits for security tooling and AI integration:

1. **Portability** – The [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) file and core logic can be imported by any AI client without modification. The same routing decisions and skill definitions run consistently on Windows, Linux, macOS, or Kali Linux without code duplication.

2. **Maintainability** – Changes to routing rules or skill documentation are made once in the shared layer. Client-specific adapters remain untouched, eliminating the risk of regressions in platform-specific integrations when updating core functionality.

3. **Security and Isolation** – Core scripts never write global client configuration files (such as `~/.claude/mcp.json`). This prevents accidental leakage of client-specific secrets and ensures the repository can be safely audited without exposing host environment details.

4. **Extensibility** – New AI clients require only a thin adapter wrapper that points to the shared core. Contributors can add support for additional hosts without forking or copying the entire repository, typically requiring only a single shell script that sources [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh).

5. **Testing Consistency** – Automated test suites like [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh) and `verify-routing-coherence.ps1` target the shared routing JSON and skill files directly. This guarantees that every client implementation exhibits identical behavior when resolving security workflows.

## Implementation in the Source Code

The boundary is physically enforced through directory structure and import constraints. The **shared layer** contains all routing intelligence, while **platform adapters** act as thin delegates.

The core router in [`skills/router.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/router.sh) processes the client-neutral [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) to match user hints against skill keywords. Platform-specific entry points in [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) (Bash) and `skills/scripts/master-route.ps1` (PowerShell) serve as thin wrappers that locate the shared configuration and delegate execution to the core router.

This structure means that adding support for a new operating system or AI client requires only creating a new adapter script that correctly resolves paths to the shared `skills/` directory, without duplicating routing logic or modifying the core skill definitions.

## Code Examples

### Client-Neutral Routing Configuration

The [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) file defines all available security workflows using pure JSON, independent of any client implementation:

```json
{
  "routes": {
    "R1": {
      "label": "APK reverse",
      "skill": "apk-reverse/SKILL.md",
      "keywords": [ { "must": "\\bapk\\b|smali|jadx|apktool|\\bandroid\\b" } ]
    },
    "R10": {
      "label": "Attack chain",
      "skill": "attack-chain/SKILL.md",
      "keywords": [ { "must": "attack.?chain|red.?team|lateral|domain.?pentest" } ]
    }
  }
}

```

Because this file lives under `skills/`, it remains completely independent of any AI client or host environment.

### Platform-Specific Master Router Adapter

The Linux and macOS entry point at [`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) demonstrates the thin adapter pattern:

```bash
#!/usr/bin/env bash

# Platform-native entry – thin wrapper around the client-neutral core

HINT="${1:-}"

# Load the shared routing table (client-neutral)

ROUTING_JSON="$(dirname "$(realpath "$0")")/../config/routing.json"

# Resolve the primary skill using the core script

bash "$(dirname "$0")/../router.sh" --routing "$ROUTING_JSON" --hint "$HINT"

```

This script contains no routing logic itself; it only forwards the user hint to the shared router and passes the path to the client-neutral configuration.

### Adding a New Client Adapter

To integrate with a hypothetical "OpenCode" client, only a minimal wrapper is required:

```bash

# opencode/adapter/run.sh

#!/usr/bin/env bash

# Minimal adapter that re-uses the core router

source "$(git rev-parse --show-toplevel)/skills/scripts/master-route.sh" "$@"

```

Because the core already provides all routing, tool discovery, and bootstrap logic, this single-line wrapper enables full functionality for the new client without duplicating code.

## Key Files Defining the Boundary

- **[`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)** – Defines the explicit requirement that routing core files must remain independent of any client, located at the repository root.
- **[`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md)** – Visualizes the separation between the shared platform-neutral layer and the Windows/Kali platform-specific layers.
- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)** – The single source of truth for all routing decisions, residing entirely within the client-neutral core.
- **`skills/scripts/master-route.*`** – Thin platform-specific entry points (PowerShell and Bash) that delegate to the core router without embedding client logic.
- **`skills/scripts/bootstrap-reverse.*`** – Platform-specific bootstrap scripts that install missing tools based on the client-neutral [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md).
- **[`field-journal/_index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/field-journal/_index.md)** – Central knowledge base accessible by the core regardless of which AI client loads the repository.

## Summary

- The **client-neutral architecture boundary** strictly separates platform-independent core logic in `skills/` from client-specific adapters.
- This design ensures **portability** across Claude Code, Cursor, Codex, and other AI hosts without modifying core files.
- **Security** is enhanced because core scripts never write global client configuration or expose host-specific secrets.
- New AI clients can be supported by creating **thin adapter scripts** that reference the shared router, eliminating the need to fork the repository.
- All **automated tests** target the shared routing configuration, guaranteeing consistent behavior across every client implementation.

## Frequently Asked Questions

### How does the client-neutral boundary prevent vendor lock-in?

By keeping all routing logic and skill definitions in the platform-neutral `skills/` directory, the repository avoids dependencies on proprietary client APIs or configuration formats. Organizations can migrate from Claude Code to Cursor or Codex without modifying their security workflows, as each client simply loads the same [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) and [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files through its own thin adapter.

### Can I add platform-specific tools without breaking the boundary?

Yes. Platform-specific tool installation scripts belong in `skills/scripts/` (for Windows/Linux/macOS) or `kali/scripts/` (for Kali Linux), where they can reference the client-neutral [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) for requirements. These scripts handle environment setup while the core remains unaware of the underlying platform, preserving the architectural separation.

### Where should new skill documentation be placed to maintain neutrality?

All skill documentation must reside within the `skills/` directory tree, typically as [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/SKILL.md) files within skill-specific subdirectories (e.g., [`skills/apk-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/apk-reverse/SKILL.md)). Never place skill logic in client-specific adapter directories. The routing configuration in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) should point to these neutral paths using relative references.

### How do automated tests verify client-neutral behavior?

The test suite includes [`test-routing.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-routing.sh) and `verify-routing-coherence.ps1`, which validate the [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) schema and ensure that all skill paths resolve correctly without requiring client-specific context. These tests run against the shared layer directly, confirming that routing decisions remain consistent regardless of which AI host executes them.