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

> Extend reverse-skill to new platforms beyond Windows, Kali, and macOS. Learn to add custom documentation, bootstrap scripts, skill definitions, and update routing rules for seamless integration.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-05

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) and [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) provides the template structure: overview, prerequisites, installation commands, and known issues.

```markdown
<!-- 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/platforms/ubuntu/bootstrap.sh):

```bash
#!/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```bash

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)

Add the new platform identifier to the platform list:

```markdown

# Platform Identifiers

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

- freebsd  # <-- additional example

```

### Update [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ops/role-map.md)

Map platform-specific roles to skill files:

```markdown
| 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/windows-ad/SKILL.md).

Create [`skills/ubuntu/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ubuntu/SKILL.md):

```markdown

# 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README.md) and [`PLATFORMS.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/bootstrap-reverse.sh)
- **Tool Index**: Run [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) to regenerate [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md)
- **Routing**: Update [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) and [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) as your documentation template, [`kali/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/bootstrap-reverse.sh) for script structure, and [`skills/windows-ad/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) (platform identifiers) and [`skills/ops/role-map.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md)?

No. This file is auto-generated by [`kali/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/verify-routing-coherence.sh) to check that all platform identifiers in [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.