How the Client-Neutral Core of reverse-skill Works: Architecture and Execution Flow

The client-neutral core of reverse-skill is a three-layer routing engine that maps natural-language hints to structured security workflows, automatically discovers and installs required tools, and executes tasks identically across PowerShell, Bash, and AI clients without platform-specific dependencies.

The reverse-skill repository by zhaoxuya520 implements a truly client-neutral core that decouples cybersecurity task execution from any specific AI client or operating system. This architecture ensures that whether you invoke commands from Windows PowerShell, Linux Bash, macOS Terminal, or an MCP-compatible AI assistant, the routing logic and case lifecycle remain identical and auditable.

Three-Layer Architecture of the Client-Neutral Core

The core consists of three tightly integrated layers that handle decision-making, execution, and continuous improvement.

Routing Layer (Hint to Skill ID)

The routing layer serves as the decision engine that translates vague user hints into concrete skill identifiers. It maintains a single source of truth in skills/config/routing.json, which defines 41 distinct routing rules (R0-R40) mapping to specific security disciplines like APK reverse engineering, binary diffing, or CTF challenges.

For rapid resolution, skills/MASTER-ROUTING.md provides a fast-path contract that skills/scripts/master-route.sh (Linux/macOS/Kali) and skills/scripts/master-route.ps1 (Windows) consult first. When the fast-path lookup fails to match a hint like "analyze this APK", the engine falls back to skills/routing.md, a human-readable matrix that disambiguates similar requests and suggests the appropriate primary skill ID (e.g., apk-reverse/).

Execution Layer (Case Lifecycle)

The execution layer drives the complete case lifecycle through platform-agnostic scripts. Once routing identifies a primary skill, skills/scripts/case-init.sh or case-init.ps1 creates a scoped workspace at work/<case>/, populating it with scope.md, a forensic timeline, and trackable work-items.

During execution, skills/tool-index.md (auto-generated) validates the availability of external dependencies like IDA Pro, radare2, or Frida. If a required tool is missing, the bootstrap process defined in docs/ARCHITECTURE.md triggers automatic installation via GitHub releases, pip, npm, winget, or local HTTP MCP servers, updating skills/scripts/bootstrap-manifest.json with installation metadata before proceeding.

Evolution Layer (Knowledge Persistence)

The evolution layer ensures the system improves with each engagement. After skill execution completes, results flow into field-journal/ as structured Evidence → Finding → Path entries. The docs-generator/ and diagram-generator/ modules then produce final markdown reports and visual diagrams, updating skills/INDEX.md to reflect new capabilities or routing refinements.

From Natural Language to Skill Execution

The journey from a user hint to an executed security workflow follows a strict pipeline defined in docs/ARCHITECTURE.md.

Fast-Path Routing with MASTER-ROUTING

When a hint enters the system—whether from a human operator or an AI client—the master-route scripts perform immediate classification:

# Linux/macOS/Kali: Fast-path routing to identify primary skill

bash skills/scripts/master-route.sh --hint "analyze this apk"

# Windows: Equivalent PowerShell execution

powershell -File skills\scripts\master-route.ps1 -Hint "analyze this apk"

These scripts load skills/config/routing.json and return a PRIMARY identifier (e.g., apk-reverse/) that points to the skill's SKILL.md entry point. The fast-path prioritizes common security tasks (R1, R33, etc.) to minimize latency.

Routing Matrix Fallback

If the fast-path returns ambiguous or null results, the engine consults skills/routing.md to disambiguate similar terms like "reverse APK" versus "decompile Android". This secondary lookup ensures comprehensive coverage without bloating the primary routing table.

Tool Discovery and Self-Bootstrap Mechanism

Before executing any skill, the core validates the tool chain through skills/tool-index.md. When skills/scripts/case-init.* detects a missing dependency, it references skills/scripts/bootstrap-manifest.json to determine the correct installer for the host platform:

• GitHub release zips for standalone binaries
• pip/npm for Python and Node.js packages
• winget/apt for system package managers
• Local HTTP MCP for proprietary toolchains

Once installation completes successfully, the new tool path is appended to tool-index.md, and the skill execution proceeds without manual intervention.

The Case Workflow Lifecycle

The client-neutral core orchestrates a repeatable four-phase workflow:

1. Initialization: case-init establishes the forensic workspace at work/<case>/ with scope.md defining boundaries and authorization levels per RULES.md.

2. Execution: The primary skill runs its internal scripts (e.g., apk-reverse/analysis.ps1), operating solely within the case directory to maintain evidence integrity.

3. Evidence Collection: Structured findings are written to field-journal/ with full provenance chains, creating an auditable record independent of the invoking client.

4. Report Generation: python3 skills/docs-generator/generate_report.py work/<case>/ consumes the field journal to produce standardized markdown reports and architectural diagrams.

# Complete Linux workflow example

bash skills/scripts/case-init.sh --hint "apk reverse" --case-name "malware-2024"
cd work/malware-2024

# ... skill execution happens here ...

python3 skills/docs-generator/generate_report.py work/malware-2024

# Complete Windows workflow example

powershell -File skills\scripts\case-init.ps1 -Hint "apk reverse" -CaseName "malware-2024"

# ... skill execution ...

python3 skills\docs-generator\generate_report.py work\malware-2024

Cross-Platform Client Neutrality

The core achieves true client neutrality by enforcing strict architectural boundaries: no AI client-specific code exists within the routing or execution layers. All logic is implemented in portable PowerShell, Bash, and Python scripts that interact through standardized JSON manifests and markdown contracts.

This design guarantees that the same routing logic works identically on Windows PowerShell, Linux/macOS Bash, and Kali environments. An AI client loads the repository and invokes master-route.* or case-init.* as subprocess calls, receiving structured output without needing to understand internal skill implementations.

Summary

• The client-neutral core consists of three layers: routing (decision), execution (action), and evolution (learning).
• Routing uses skills/config/routing.json and skills/MASTER-ROUTING.md to map hints to skill IDs via fast-path or matrix fallback.
• Tool discovery relies on skills/tool-index.md and automatic bootstrapping via skills/scripts/bootstrap-manifest.json when dependencies are missing.
• Case workflows follow a standardized lifecycle: case-init → skill execution → field-journal persistence → docs-generator reporting.
• All components are implemented in cross-platform scripts (PowerShell/Bash/Python) ensuring identical behavior across Windows, Linux, macOS, and AI clients.

Frequently Asked Questions

What makes the reverse-skill core "client-neutral"?

The core contains no dependencies on specific AI client APIs, SDKs, or interfaces. All functionality is exposed through standard shell scripts (master-route.sh, case-init.ps1) and JSON configuration files (routing.json, bootstrap-manifest.json). Any client—whether Claude, GPT, or a human terminal—invokes the same entry points and receives identical structured output, ensuring consistent security workflows regardless of the invocation method.

How does the routing layer handle ambiguous or novel hints?

When a hint does not match the fast-path rules in skills/MASTER-ROUTING.md, the system falls back to skills/routing.md, a human-readable matrix that disambiguates similar security tasks. If no match exists, the routing engine returns a suggestion to create a new skill entry, triggering the evolution layer to document the gap in field-journal/ for future routing updates.

Can custom security skills be added without modifying the core?

Yes. New skills are added by creating a directory under skills/ (e.g., skills/custom-audit/) containing a SKILL.md entry point and execution scripts. You then register the skill in skills/config/routing.json with a unique R-ID (e.g., R41) and update skills/MASTER-ROUTING.md with fast-path keywords. The existing master-route and case-init scripts automatically recognize and execute the new skill without code changes.

Which operating systems does the client-neutral core support?

The core officially supports Windows (PowerShell 5.1+), Linux (Bash), macOS (Bash/Zsh), and Kali Linux (Bash). All scripts in skills/scripts/ provide parallel implementations (.ps1 for Windows, .sh for Unix-like systems), while Python components in docs-generator/ and diagram-generator/ are platform-agnostic. The bootstrap-manifest.json defines OS-specific installation commands, ensuring tools deploy correctly regardless of the host environment.

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