Understanding the Client-Neutral Boundary and Optional Client Adapters in reverse-skill

The client-neutral boundary is an architectural contract in the zhaoxuya520/reverse-skill repository that isolates the core routing engine and skill definitions from AI-client-specific code, requiring all host-specific behavior to reside in optional external adapters that never modify files under skills/.

The zhaoxuya520/reverse-skill repository implements a strict client-neutral boundary to ensure its skill routing system remains portable across any AI host. This architecture mandates that the core engine—comprising skill definitions, routing logic, and test artifacts—must remain completely ignorant of which specific AI client (Claude Code, Codex, Cursor, etc.) is executing tasks.

What Is the Client-Neutral Boundary?

The client-neutral boundary is the strict architectural separation between the repository's core functionality and any AI-client-specific code. As defined in RULES.md, this boundary ensures that the routing engine, skill definitions, manifests, and test suites remain pure and host-agnostic, loadable by any supported host without requiring client-specific modifications.

Core Architecture Under skills/

The core implementation resides entirely within the skills/ directory. This directory contains:

• Skill definitions and their associated manifests
• skills/config/routing.json, the structured routing configuration consumed by all clients
• Test scripts and generated artifacts
• skills/MASTER-ROUTING.md, the primary entry point for routing decisions
• skills/scripts/master-route.ps1, the master router script that dispatches tasks

According to the source code rules, this core can be loaded by any host without requiring client-specific files, ensuring maximum portability across AI platforms.

The Prohibition on Client-Specific Code

A foundational rule of the boundary is that core scripts must never write client-global configuration. All host-specific behaviors—including authentication handling, environment setup, or client-specific metadata—must exist only in optional adapters that sit outside the core. These adapters must preserve the exact routing semantics defined by the core without altering any files inside skills/ or the routing configuration, as implemented in zhaoxuya520/reverse-skill.

How to Create Optional Client Adapters

Because the core is deliberately client-neutral, integrating new AI clients requires creating an adapter package that translates the client’s project-instruction format into the repository’s expected structure. The adapter acts as a thin wrapper that loads the repository and forwards commands without modifying core files.

Follow these five steps to implement a compliant adapter:

1. Create a dedicated adapter folder outside the skills/ directory, using the pattern adapters/<client-name>/ (e.g., adapters/claude/).

2. Add a manifest (adapter.yaml) that describes the client name, required entry point, and any client-specific launch scripts.

3. Implement a thin bootstrap script that:

   • Detects the repository root using the location of RULES.md
   • Calls the core's master router (skills/scripts/master-route.ps1) with the user-provided hint
   • Passes through any client-specific options (e.g., authentication tokens) without altering core files

4. Add the adapter to the top-level README under "Supported AI clients" so users know it is optional.

5. Document the adapter in docs/ (or adapters/README.md) and add a link from the README to keep the knowledge base up-to-date.

Minimal Adapter Implementation: Claude Code Example

Below is a complete, runnable PowerShell adapter that demonstrates the contract. This script resides at adapters/claude/run.ps1 and forwards Claude-specific task hints to the neutral core:

# adapters/claude/run.ps1

# Detect repository root

$repoRoot = (Get-Item (Join-Path $PSScriptRoot '..')).FullName

# Forward the task hint to the core router

& "$repoRoot/skills/scripts/master-route.ps1" -Hint $env:CLAUDE_TASK_HINT

The accompanying adapter.yaml manifest provides the required metadata:

# adapters/claude/adapter.yaml

client: Claude Code
entry: run.ps1
description: Minimal wrapper that forwards Claude-provided task hints to the core router.

This adapter merely invokes the core routing script; it does not modify any files under skills/, preserving the client-neutral contract.

Key Files Supporting the Boundary

Understanding the boundary requires familiarity with these specific source files:

• RULES.md: Defines the client-neutral contract and explicitly prohibits client-specific adapters from residing in the core.
• skills/MASTER-ROUTING.md: The primary entry point for routing decisions used by all clients.
• skills/config/routing.json: The structured routing configuration that adapters must consume without modification.
• skills/scripts/master-route.ps1: The master router that adapters call to dispatch tasks, accepting parameters like -Hint without client-specific logic.

Summary

• The client-neutral boundary strictly separates the skills/ core from AI-client-specific code.
• Core scripts under skills/ must never write client-global configuration or host-specific logic.
• Optional client adapters reside in adapters/ and act as thin wrappers that translate client formats to core expectations.
• Adapters detect the repository root via RULES.md and forward tasks to skills/scripts/master-route.ps1.
• Adapters must preserve exact routing semantics without modifying any files inside skills/ or the routing configuration.

Frequently Asked Questions

What happens if an adapter modifies files in the skills directory?

Modifying files under skills/ violates the client-neutral boundary and breaks the architectural contract. Such changes would make the repository dependent on specific client behaviors, preventing other AI hosts from correctly loading the core. The RULES.md explicitly prohibits this practice to maintain portability.

Can multiple client adapters coexist in the same repository?

Yes. The architecture supports multiple simultaneous adapters (e.g., adapters/claude/, adapters/cursor/, adapters/codex/) because each adapter is optional and external to the core. Each adapter simply wraps the same neutral core, allowing teams to use different AI clients with the same skill definitions and routing logic.

Where should adapter-specific configuration be stored?

Adapter-specific configuration—such as authentication tokens, client-specific environment variables, or host metadata—must reside within the adapter's own directory (e.g., adapters/claude/config/) or in client-specific environment variables. Never store client-specific configuration in skills/ or the core routing files.

How does the core router handle authentication tokens passed by adapters?

The core router (skills/scripts/master-route.ps1) receives client-specific options (including authentication tokens) via parameters or environment variables passed by the adapter, but it treats these as opaque pass-through values. The core does not persist or interpret client-global configuration, maintaining its neutrality while allowing adapters to handle host-specific authentication flows.

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