How reverse-skill Maintains Client Neutrality: Architecture and Implementation

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 line 5, the routing core must remain strictly client-neutral. The canonical skill map lives in 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 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 and 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 and 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 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 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 appears and the capability is marked ready.
• After --mcp-host=claude, 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 explicitly states that "Client-specific adapters are optional and MUST NOT be required by core workflows."

Practical Examples

Example 1: Client-Neutral Bootstrap

# 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 contains the radare2 entry, but ~/.claude/mcp.json and ~/.codex/config.toml remain untouched.

Example 2: Explicit Codex Registration

# 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

# 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

# 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 or codex.toml.
• The 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 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, 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 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.

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