Understanding the Client-Neutral Architecture Boundary in reverse-skill

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 definitions, routing.json configuration, 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 and 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 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.

5. Testing Consistency – Automated test suites like 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 processes the client-neutral routing.json to match user hints against skill keywords. Platform-specific entry points in 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 file defines all available security workflows using pure JSON, independent of any client implementation:

{
  "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 demonstrates the thin adapter pattern:

#!/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:

# 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 – Defines the explicit requirement that routing core files must remain independent of any client, located at the repository root.
• docs/ARCHITECTURE.md – Visualizes the separation between the shared platform-neutral layer and the Windows/Kali platform-specific layers.
• 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.
• 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 and 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 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 files within skill-specific subdirectories (e.g., skills/apk-reverse/SKILL.md). Never place skill logic in client-specific adapter directories. The routing configuration in 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 and verify-routing-coherence.ps1, which validate the 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.

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