# How reverse-skill Maintains Client Neutrality: Architecture and Implementation > Learn how reverse-skill maintains client neutrality with its three-layer architecture. Discover how to keep AI clients free from dependencies unless explicitly requested. - Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill) - Tags: architecture - Published: 2026-08-23 --- **The reverse-skill repository enforces client neutrality through a three-layer architecture that keeps the routing core, bootstrap process, and tool registry free from AI client-specific dependencies unless explicitly requested via the `--mcp-host` flag.** The zhaoxuya520/reverse-skill project implements a strict **client neutrality** policy that prevents vendor lock-in and accidental credential leakage. Unlike frameworks that default to specific AI clients like Claude or Codex, reverse-skill treats all LLM integrations as optional adapters while maintaining a portable core. This design ensures that skill definitions and reverse engineering capabilities remain accessible to any client without requiring proprietary configuration files. ## The Three-Layer Neutrality Architecture ### Routing Core: Client-Agnostic Skill Mapping According to [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) line 5, the routing core must remain strictly client-neutral. The canonical skill map lives in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) and is invoked via `master-route` scripts that never touch client-specific configurations. This layer operates independently of Claude, Codex, Cursor, or any other LLM client, ensuring that the **routing core stays client-neutral** as explicitly mandated in the source rules. ### Bootstrap Layer: Opt-In Client Registration The bootstrap scripts ([`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) and `bootstrap-reverse.ps1`) default to a client-neutral mode. When you run the bootstrap without flags, it prepares runtimes and discovers tools but intentionally does not write to `~/.claude/mcp.json` or `~/.codex/config.toml`. Only when passing the explicit `--mcp-host=` flag (e.g., `--mcp-host=claude`, `--mcp-host=codex`, or `--mcp-host=both`) does the script generate client-specific configurations. This behavior is documented in [`docs/platforms/linux.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) and [`docs/platforms/macos.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/macos.md), which explain that the bootstrap **defaults to client-neutral mode** and requires explicit flags to register MCP hosts. ### Tool-Index: Shared Registry The [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) and [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) files serve as a shared registry generated after bootstrap. Because this index stores absolute paths and capability flags in a client-agnostic format, any LLM client can read it without modification. The same tool index powers Claude, Codex, Cursor, or custom adapters simultaneously, acting as a **single source of truth** for tool discovery. ## Client-Neutral Bootstrap Workflow The default workflow follows three steps: 1. **Neutral Installation**: Run `bash skills/scripts/bootstrap-reverse.sh radare2` to build capabilities without registering any MCP host. 2. **Index Update**: The script refreshes [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) with the new binary location but leaves `CLAUDE_MCP_CONFIG` and `CODEX_CONFIG_PATH` undefined. 3. **Explicit Registration**: Later, add `--mcp-host=claude` or `--mcp-host=codex` only when you need client-specific MCP integration, which writes the appropriate config files and marks capabilities as `ready` in the tool-index. ## Validating Neutrality: Automated Testing The [`skills/scripts/test-client-neutral-bootstrap.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/test-client-neutral-bootstrap.sh) script enforces the neutrality contract through automated assertions. Lines 66-85 verify three critical conditions: - After a plain bootstrap run, no client-config files exist. - After `--mcp-host=codex`, [`codex.toml`](https://github.com/zhaoxuya520/reverse-skill/blob/main/codex.toml) appears and the capability is marked ready. - After `--mcp-host=claude`, [`claude.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/claude.json) appears and the capability is marked ready. If all assertions pass, the script outputs `client-neutral Bash bootstrap/discovery regression passed`, confirming the repository maintains its **client-neutral default** and **explicit registration path**. ## Why Client Neutrality Matters **Adapter-Free Core**: The routing and skill definitions operate without requiring specific binaries or configurations, allowing consumption by any LLM client without modification. **Safety**: The default behavior prevents accidental credential leakage by never creating hidden global state (such as Claude tokens) unintentionally, eliminating the risk of sensitive data exposure during installation. **Extensibility**: New clients integrate through separate MCP adapters. The core remains unchanged because [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) explicitly states that *"Client-specific adapters are optional and MUST NOT be required by core workflows."* ## Practical Examples ### Example 1: Client-Neutral Bootstrap ```bash # Prepare radare2 without client registration bash skills/scripts/bootstrap-reverse.sh radare2 # Refresh the shared tool index bash skills/scripts/refresh-tool-index.sh ``` **Result**: [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) contains the `radare2` entry, but `~/.claude/mcp.json` and `~/.codex/config.toml` remain untouched. ### Example 2: Explicit Codex Registration ```bash # Install and register specifically for Codex bash skills/scripts/bootstrap-reverse.sh jshookmcp --mcp-host=codex # Verify the configuration cat "$HOME/.codex/config.toml" ``` **Result**: The file contains a `[mcp_servers.jshook]` section, and the tool-index marks `jshookmcp` as `ready`. ### Example 3: Running the Regression Test ```bash # Verify the neutrality contract bash skills/scripts/test-client-neutral-bootstrap.sh ``` **Result**: Prints `client-neutral Bash bootstrap/discovery regression passed` if all assertions succeed. ### Example 4: Reading the Tool-Index from Any Client ```bash # Claude or any client can read shared paths cat skills/tool-index.md | grep radare2 ``` **Result**: Returns the absolute path without requiring Claude-specific configuration. ## Summary - The reverse-skill repository enforces **client neutrality** through a routing core, bootstrap layer, and shared tool-index that operate independently of specific AI clients. - The bootstrap scripts default to neutral mode and require the `--mcp-host=` flag to generate client-specific MCP configurations like [`claude.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/claude.json) or [`codex.toml`](https://github.com/zhaoxuya520/reverse-skill/blob/main/codex.toml). - The [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) file explicitly mandates that client-specific adapters remain optional and must not be required for core workflows. - Automated testing in [`test-client-neutral-bootstrap.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/test-client-neutral-bootstrap.sh) validates that default installations create no client config files while explicit registrations write the correct files. - This architecture prevents credential leakage, eliminates vendor lock-in, and allows seamless integration with Claude, Codex, Cursor, or future LLM clients. ## Frequently Asked Questions ### What is client neutrality in reverse-skill? **Client neutrality** is the architectural principle that the core reverse-skill engine operates without dependencies on specific AI clients such as Claude, Codex, or Cursor. According to the source code in [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md), the routing core remains client-agnostic, and all client integrations are treated as optional adapters rather than required dependencies. ### How do I install reverse-skill without registering a specific AI client? Run the bootstrap script without the `--mcp-host` flag, for example: `bash skills/scripts/bootstrap-reverse.sh radare2`. This updates the shared `tool-index` but intentionally skips writing to `~/.claude/mcp.json` or `~/.codex/config.toml`, leaving your system free of client-specific configuration files. ### Can I use reverse-skill with multiple AI clients simultaneously? Yes. The [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) serves as a shared registry that any client can read. You can bootstrap tools in client-neutral mode, then later register specific capabilities for Claude with `--mcp-host=claude`, for Codex with `--mcp-host=codex`, or for both using `--mcp-host=both` without conflicts. ### How does reverse-skill prevent accidental credential leaks? By defaulting to client-neutral mode, the bootstrap scripts never create hidden global state or store authentication tokens unless you explicitly pass the `--mcp-host` flag. This prevents scenarios where a default installation might accidentally write sensitive Claude or Codex credentials to your filesystem without your knowledge.