# How Cross-Platform Tool Indexes Are Generated in reverse-skill: Windows vs Linux/macOS

> Discover how reverse-skill generates cross-platform tool indexes using distinct Windows PowerShell and Linux/macOS shell scripts. Learn about their shared algorithm and native syntax.

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

---

**The reverse-skill repository generates machine-specific tool indexes through platform-specific scripts that share a common algorithm but use native shell syntax: `skills/scripts/refresh-tool-index.ps1` for Windows and [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) for Linux/macOS.**

The **reverse-skill** project maintains a *tool index* that catalogs every supported security and reverse-engineering tool—tracking availability, version, installation path, and MCP registration status. This index must work identically across Windows, Linux, and macOS environments despite fundamentally different command-line ecosystems.

## Core Architecture: One Algorithm, Two Implementations

Both platform scripts execute the same nine-step workflow, differing only in shell-specific syntax. The process is centralized around a static tool definition list and converges on identical JSON output regardless of host OS.

### Platform Detection Methods

Each script determines the runtime environment using native utilities:

- **Linux/macOS ([`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh)):** Uses `uname -s` to discriminate between `Darwin` (macOS), `Linux`, and `unknown`.

```bash
UNAME_S=$(uname -s)
case "$UNAME_S" in
  Darwin) PLATFORM="macos" ;;
  Linux)  PLATFORM="linux" ;;
  *)      PLATFORM="unknown" ;;
esac

```

- **Windows (`refresh-tool-index.ps1`):** Uses PowerShell automatic variables `$IsWindows` with fallbacks to `$PSVersionTable.OS` or `[System.Environment]::OSVersion`.

```powershell
if ($IsWindows) { $Platform = "windows" } else { $Platform = "unknown" }

```

## Tool Catalog and Probing Logic

The scripts reference a shared static array (`TOOLS=` in Bash, converted to PowerShell objects) that enumerates every supported binary with five fields: **name**, **skill category**, **description**, **command**, and **version command**.

### Availability Detection

Tool discovery uses platform-native existence checks:

| Platform | Command Probe | Path Probe |
|----------|---------------|------------|
| Linux/macOS | `command -v <cmd>` | `[[ -e <path> ]]` |
| Windows | `Get-Command` | `Test-Path` |

When a tool's command field is `none`, the script falls back to *path probes*—semicolon-separated candidate locations checked sequentially.

### Version Extraction

Upon successful discovery, the script executes the specified version command (e.g., `jadx --version`), captures **stdout**, trims to the first line, strips trailing whitespace, and stores the result.

```bash

# Bash implementation

JADX_VER=$(jadx --version | head -n1 | tr '\n' ' ' | sed 's/[[:space:]]*$//')

```

```powershell

# PowerShell implementation

$JadxVer = (& jadx --version) -join ' '

```

## Cross-Platform Output Differences

While the underlying data is identical, the rendered markdown tables differ by one column:

| Platform | Columns | Notable Difference |
|----------|---------|------------------|
| Windows | 8 | Adds "脚本引用" (script reference) column |
| Linux/macOS | 7 | Omits script reference column |

Both scripts emit [`skills/tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.md) with rows following this schema:

```markdown
| jadx | apk-reverse | APK Java/Kotlin decompiler | yes | /usr/local/bin/jadx | 1.2.0 | command | brew: brew install jadx |

```

## Installation Hint Mapping

The `install_hint` function (Bash) and `Install-Hint` function (PowerShell) map **platform + tool** pairs to contextual installation guidance:

- `apt: sudo apt install openjdk-17-jdk`
- `brew: brew install radare2`
- `pipx: pipx install frida-tools`

This enables actionable remediation when tools are missing.

## Capability Status Integration

Both scripts parse [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) to cross-reference MCP-registered capabilities. The implementation delegates to an inline Python block that:

1. Loads the manifest JSON
2. Reads the temporary tool-availability TSV
3. Checks TCP ports and MCP HTTP handshakes
4. Computes a combined *ready* flag
5. Emits a markdown table (`| 能力 | 工具可用 | Ready | … |`)

The Python logic is **identical** across platforms; only the heredoc invocation syntax differs (`python3 -` in both cases).

## JSON Export Format

The final output stage produces [`skills/tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/tool-index.json) with this structure:

```json
{
  "generated_at": "2026-08-18 12:34:56 +0000",
  "platform": "linux",
  "tools": [
    {
      "name": "jadx",
      "skill": "apk-reverse",
      "available": true,
      "path": "/usr/local/bin/jadx",
      "version": "1.2.0",
      "install_hint": "brew: brew install jadx"
    }
  ],
  "capabilities": [...]
}

```

This normalized format enables downstream automation regardless of source platform.

## Key Files in the Repository

| File | Purpose |
|------|---------|
| [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) | Bash implementation for Linux/macOS |
| `skills/scripts/refresh-tool-index.ps1` | PowerShell implementation for Windows |
| [`skills/scripts/bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-manifest.json) | MCP capability declarations |
| [`docs/platforms/linux.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) | Linux-specific installation guidance |
| [`docs/platforms/macos.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/macos.md) | macOS-specific installation guidance |

## Summary

- **Cross-platform tool index generation** in reverse-skill relies on parallel Bash and PowerShell scripts that implement identical logic with native shell syntax.
- **Platform detection** uses `uname -s` on POSIX systems and `$IsWindows` on PowerShell.
- **Tool probing** adapts detection commands (`command -v` vs `Get-Command`) while sharing the same static tool definition catalog.
- **Output formats** differ only in the Windows-specific "脚本引用" column; the JSON export and core data remain consistent.
- **Capability integration** delegates to shared Python code embedded in both scripts, ensuring MCP status reporting is uniform across platforms.

## Frequently Asked Questions

### What triggers the tool index refresh?

Both scripts are designed for **manual execution** when the environment changes—after installing new tools, updating versions, or migrating to a different machine. The repository does not include automatic triggers; users run the appropriate script for their platform.

### Why does Windows have an extra column in the markdown output?

The "脚本引用" (script reference) column exists only in `refresh-tool-index.ps1` to accommodate Windows-specific workflow conventions documented in the original project requirements. The JSON output remains identical, ensuring downstream parsers work uniformly.

### How does the script handle tools not in PATH?

When the command field in a tool definition is `none`, the script activates **path probe mode**. It iterates through semicolon-separated candidate locations, testing each with `[[ -e ... ]]` (Bash) or `Test-Path` (PowerShell) until a match is found or the list exhausts.

### Can the tool index be used without the MCP capability system?

Yes. The core tool index ([`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) and [`tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.json)) generates independently of MCP functionality. The capability-status section appends additional information when [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) is present, but removal of that file does not break basic index generation.