How AI Clients Integrate with reverse-skill Without Modifying Core Routing Semantics

AI clients integrate with reverse-skill by cloning the repository, executing the client-neutral bootstrap scripts, and delegating task hints to the primary router, ensuring all client-specific configurations remain isolated from the core routing engine.

The reverse-skill repository by zhaoxuya520 implements a strictly client-neutral architecture that allows any AI assistant—whether Claude Code, Codex, Cursor, or OpenCode—to leverage its reverse-engineering capabilities without altering core routing semantics or injecting client-specific logic into shared configuration files.

Understanding the Client-Neutral Architecture

At the heart of reverse-skill lies a deliberate design choice to isolate routing logic from client implementations. The routing engine, regression suite, and all core workflows reside in a single, self-contained configuration file: skills/config/routing.json. This file serves as the immutable single source of truth for routing decisions and never depends on a specific AI client implementation.

According to RULES.md (line 5), the project enforces a strict policy: "Keep the routing core client-neutral. Client-specific adapters are optional and MUST NOT be required by core workflows." This guarantees that new AI clients can onboard without modifying existing routing tables or core scripts.

The Integration Workflow

AI clients connect to reverse-skill through a standardized five-step workflow that keeps all client-specific concerns outside the core repository structure.

Loading the Repository and Bootstrap Configuration

The integration begins when an AI client clones the repository or opens it via a native adapter. The client reads README_AI.md, which contains minimal instructions for initializing the client-side environment, such as setting a local MCP_HOST variable or exposing a client adapter script. This file provides entry-point documentation without embedding client logic into the core.

Bootstrapping the Core Environment

Once loaded, the client executes the core bootstrap script to discover available tools. The platform-agnostic scripts skills/scripts/refresh-tool-index.sh (Linux/macOS) and skills/scripts/refresh-tool-index.ps1 (Windows) scan the environment and build the client-neutral tool index at skills/tool-index.md.

As documented in docs/platforms/linux.md and docs/platforms/macos.md, this bootstrap process writes no client-specific configuration files. It populates skills/INDEX.md with an auto-generated, client-neutral navigation index that any AI client can consume.

Routing Tasks Through the Primary Router

When the AI client receives a user task, it forwards the raw hint string to the primary router: skills/scripts/master-route.ps1 (Windows) or skills/scripts/master-route.sh (Unix). The router reads skills/config/routing.json and selects the appropriate skill module—such as apk-reverse/, dotnet-reverse/, or pentest-tools/—based purely on data-driven pattern matching.

No client-specific logic is consulted during this decision. The router treats all incoming hints identically, whether they originate from Claude Code, GitHub Copilot, or a custom Python script.

Isolating Client-Specific Adapters

If an AI client requires additional capabilities—such as a Claude-specific MCP token or custom authentication headers—it supplies these through side-car adapters that live outside the core tree (for example, ~/.claude/mcp.json). The core routing engine never requires these files, and the presence or absence of client adapters does not alter routing behavior or skill execution.

Executing the Selected Skill

Finally, the selected skill module invokes its own scripts, tools, and MCP services. Because the routing matrix in skills/config/routing.json remains immutable and client-agnostic, every AI client executes identical workflows regardless of their specific implementation details.

Practical Implementation Examples

The following examples demonstrate how different AI clients interface with reverse-skill without modifying core files.

Initial Setup and Bootstrap

First, clone the repository and refresh the tool index using the client-neutral scripts:

# Clone the repository (once per client)

git clone https://github.com/zhaoxuya520/reverse-skill.git
cd reverse-skill

# Refresh the tool index (Linux/macOS)

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

# Or on Windows

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

Routing Tasks from AI Clients

Pass task hints directly to the primary router without client-specific preprocessing:

# Route a task from an AI client (e.g., Claude Code plugin)

powershell -NoProfile -ExecutionPolicy Bypass -File skills/scripts/master-route.ps1 -Hint "Analyze suspicious APK"

Minimal Python Client Adapter

Create an optional side-car adapter that invokes the core router without modifying core files:

import subprocess
import json
import pathlib

def route_task(hint: str):
    """
    Call the primary router with a task hint.
    No client-specific configuration is required in the core.
    """
    result = subprocess.check_output([
        "powershell",
        "-NoProfile",
        "-ExecutionPolicy",
        "Bypass",
        "-File",
        "skills/scripts/master-route.ps1",
        "-Hint",
        hint,
    ], text=True)
    return result

# Example usage

print(route_task("Extract strings from ELF binary"))

Summary

• Client-neutral core: All routing decisions in skills/config/routing.json remain independent of AI client implementations, as mandated by RULES.md.
• Standardized bootstrap: The skills/scripts/refresh-tool-index.* scripts initialize the environment without writing client-specific configurations.
• Data-driven routing: The primary routers (master-route.ps1 and master-route.sh) select skills purely from routing.json, ignoring client origin.
• Externalized adapters: Client-specific credentials and extensions reside in side-car files outside the core tree, ensuring zero core modifications when adding new AI clients.
• Universal execution: Skill modules run identically regardless of whether the task originates from Claude, Codex, Cursor, or custom scripts.

Frequently Asked Questions

What makes reverse-skill client-neutral?

The architecture enforces strict separation between routing logic and client implementations. The core routing table in skills/config/routing.json contains no client-specific conditionals, and RULES.md explicitly prohibits core workflows from requiring client adapters. All routing decisions are data-driven based on task hints rather than client identity.

Do I need to modify routing.json to add a new AI client?

No. Adding a new AI client requires zero changes to skills/config/routing.json. New clients simply clone the repository, run the bootstrap scripts, and invoke the primary router. Any client-specific configuration—such as API tokens or MCP settings—belongs in external side-car files (e.g., ~/.claude/mcp.json) that the core never reads or requires.

How does the primary router select skills without knowing the client?

The primary router scripts (skills/scripts/master-route.ps1 and master-route.sh) receive only a raw hint string from the AI client. They parse this against the patterns defined in skills/config/routing.json to select skill modules like apk-reverse/ or pentest-tools/. The routing logic is purely functional, mapping hint patterns to skill paths without inspecting which client submitted the request.

Where should client-specific credentials like MCP tokens be stored?

Store client-specific credentials in side-car configuration files outside the core repository tree, such as ~/.claude/mcp.json or your client's native configuration directory. The core reverse-skill engine never requires these files to execute routing or skills, maintaining strict client-neutral integrity while allowing clients to maintain their own authentication contexts.

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