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

> Learn about the client-neutral boundary in reverse-skill. Discover how to implement optional client adapters to isolate host-specific behavior without altering core skill files.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: deep-dive
- Published: 2026-08-15

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)**, the structured routing configuration consumed by all clients
- **Test scripts** and generated artifacts
- **[`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```powershell

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/adapter.yaml) manifest provides the required metadata:

```yaml

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)**: Defines the client-neutral contract and explicitly prohibits client-specific adapters from residing in the core.
- **[`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md)**: The primary entry point for routing decisions used by all clients.
- **[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.