how-to-guide

How to Add Support for New Platforms Beyond Windows, Kali, and macOS in reverse-skill

August 5, 2026 zhaoxuya520/reverse-skill ↗

The reverse-skill repository can be extended to new platforms by creating platform-specific documentation, bootstrap scripts, skill definitions, and updating the routing rules that govern the skill-router architecture.

The reverse-skill project uses a modular, declarative design centered on a skill-router that dispatches tasks to platform-specific implementations. Adding support for additional operating systems—such as Ubuntu, FreeBSD, or Android—requires following the established patterns found in the existing Windows, Kali, and macOS implementations. This guide walks through the exact steps and file locations needed to integrate a new platform cleanly.

Understanding the Platform Support Architecture

Before adding a new platform, examine how current platforms are organized. The repository separates concerns across documentation, scripting, skill definitions, and routing configuration.

Key Directories and Their Roles

Directory	Purpose
`docs/platforms/`	Markdown documentation describing each supported OS
`kali/scripts/`	Bootstrap and utility scripts (used as templates for Unix-like platforms)
`platforms/`	Platform-specific script folders (e.g., `kali/`, implied structure for others)
`skills/`	Skill definitions, tool indices, and operational mappings
`skills/ops/`	Routing rules, role maps, and operational documentation

The routing logic that connects platform identifiers to skill files resides in RULES.md and skills/ops/role-map.md.

Step 1: Create Platform Documentation

Start by adding a documentation page under docs/platforms/ that describes the new OS, required tools, and setup procedures.

The existing docs/platforms/linux.md provides the template structure: overview, prerequisites, installation commands, and known issues.

<!-- docs/platforms/ubuntu.md -->

# Ubuntu Platform Support

## Overview

Ubuntu 22.04 LTS and later are supported for penetration testing workflows.

## Prerequisites

- sudo access
- Internet connectivity
- 4GB RAM minimum

## Installation

```bash
sudo apt-get update && sudo apt-get install -y git curl python3-pip

Known Issues

AppArmor may block certain reconnaissance tools; disable for lab environments only.


---

## Step 2: Add Platform-Specific Scripts

Create a dedicated folder for the new platform and add bootstrap scripts that install dependencies and register **skill-router entry points**.

Reference [`kali/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/bootstrap-reverse.sh) for the expected script structure:

```bash
#!/usr/bin/env bash

# Located at: kali/scripts/bootstrap-reverse.sh

set -euo pipefail

echo "[*] Reverse-Skill Kali bootstrap starting..."

# Tool installation

sudo apt-get update
sudo apt-get install -y \
    nmap metasploit-framework bloodhound impacket-scripts

# Environment setup

mkdir -p ~/reverse-skill/{logs,stash,reports}

echo "[+] Kali platform ready"

For a new Ubuntu platform, create platforms/ubuntu/bootstrap.sh:

#!/usr/bin/env bash

# platforms/ubuntu/bootstrap.sh

set -e

echo "[*] Reverse-Skill Ubuntu bootstrap"

# Core dependencies

sudo apt-get update && sudo apt-get install -y \
    build-essential curl git python3-pip \
    nmap nikto gobuster

# Clone repository if missing

REPO_PATH="${HOME}/reverse-skill"
if [[ ! -d "$REPO_PATH" ]]; then
    git clone https://github.com/zhaoxuya520/reverse-skill "$REPO_PATH"
fi

# Execute tool index refresh

bash "${REPO_PATH}/kali/scripts/refresh-tool-index.sh"

echo "[+] Ubuntu platform registered with skill-router"

Step 3: Update the Tool Index

The tool index at skills/tool-index.md catalogs all executable tools and their capabilities. This file is auto-generated by scripts located in skills/scripts/.

Run the appropriate refresh script after adding new platform scripts:


# For Unix-like platforms including new additions

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

# Or the PowerShell equivalent for Windows-integrated workflows

powershell skills/scripts/refresh-tool-index.ps1

The refresh scripts scan script directories and update skills/tool-index.md with discovered commands, flags, and platform associations.

Step 4: Extend Routing Rules and Role Mappings

The skill-router relies on declarative mappings to dispatch commands. Two files require updates:

Update `RULES.md`

Add the new platform identifier to the platform list:


# Platform Identifiers

- windows
- kali
- macos
- ubuntu   # <-- newly added

- freebsd  # <-- additional example

Update `skills/ops/role-map.md`

Map platform-specific roles to skill files:

| Platform | Role | Skill File |
|----------|------|------------|
| ubuntu | recon | skills/ubuntu/recon.md |
| ubuntu | exploit | skills/ubuntu/exploit.md |
| ubuntu | post-exploit | skills/ubuntu/persistence.md |

Step 5: Create Skill Definition Files

Each platform exposes capabilities through skill markdown files that document commands, inputs, outputs, and permissions. Model these after skills/windows-ad/SKILL.md.

Create skills/ubuntu/SKILL.md:


# Ubuntu Skill

## Purpose

Provides penetration testing commands optimized for Ubuntu environments.

## Commands

### `ubuntu:install-tools`

Installs curated hacking utilities via apt.

**Parameters:** None
**Returns:** Installation log path

### `ubuntu:run-recon`

Executes network reconnaissance using nmap and nikto.

**Parameters:**
- `target`: IP or CIDR range
- `intensity`: quick|normal|deep

**Returns:** XML and markdown reports in `stash/recon/`

### `ubuntu:exploit`

Wraps Metasploit modules for Ubuntu targets.

**Parameters:**
- `module`: Metasploit module path
- `options`: Key-value pairs for module options

## Usage Example

```powershell

# From master router

Invoke-Skill -Platform ubuntu -Action run-recon -Parameters @{target="192.168.1.0/24"}


---

## Step 6: Add Test Workflows

Document realistic use-cases under `skills/field-journal/` to validate the new platform integration:

```markdown
<!-- skills/field-journal/ubuntu-pentest-2024.md -->

# Ubuntu Target Pentest Workflow

**Platform:** ubuntu
**Date:** 2024-01-15

## Phase 1: Reconnaissance

```bash
reverse-skill exec ubuntu:run-recon -t 10.0.0.0/24

Phase 2: Exploitation

Identified vsftpd vulnerability; used ubuntu:exploit with exploit/unix/ftp/vsftpd_234_backdoor.


---

## Step 7: Verify and Regenerate Documentation

Run coherence checks to ensure routing consistency:

```bash

# Verify routing matrix integrity

bash skills/scripts/verify-routing-coherence.sh

Update README.md and PLATFORMS.md to list the newly supported platform alongside Windows, Kali, and macOS.

Summary

Documentation: Create docs/platforms/{platform}.md with OS-specific setup instructions
Scripts: Add bootstrap scripts in platforms/{platform}/ following kali/scripts/bootstrap-reverse.sh
Tool Index: Run refresh-tool-index.sh to regenerate skills/tool-index.md
Routing: Update RULES.md and skills/ops/role-map.md with new platform identifiers
Skills: Write skills/{platform}/SKILL.md defining commands, parameters, and usage
Testing: Add field journal entries and run verify-routing-coherence.sh

Frequently Asked Questions

What file structure should I follow when adding a new platform?

Mirror the existing platform implementations. Use docs/platforms/linux.md as your documentation template, kali/scripts/bootstrap-reverse.sh for script structure, and skills/windows-ad/SKILL.md for skill definition format. The skill-router expects this consistent structure to dispatch commands correctly.

Where is the platform routing logic defined?

Platform routing is declared in RULES.md (platform identifiers) and skills/ops/role-map.md (role-to-skill mappings). The master router reads these files to determine which skill files to invoke for a given platform and action combination.

Do I need to manually edit `skills/tool-index.md`?

No. This file is auto-generated by kali/scripts/refresh-tool-index.sh or skills/scripts/refresh-tool-index.ps1. Run the appropriate script after adding new platform scripts to update the index automatically.

How do I validate that my new platform integration works correctly?

Execute skills/scripts/verify-routing-coherence.sh to check that all platform identifiers in RULES.md have corresponding entries in the role map and that skill files exist at the declared paths. Add a field journal entry under skills/field-journal/ to document a realistic workflow that exercises your new platform commands.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

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

Ask your agent:

"Use Instagit MCP to understand how zhaoxuya520/reverse-skill works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →