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

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 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): Uses uname -s to discriminate between Darwin (macOS), Linux, and unknown.

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.

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 implementation

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

# 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 with rows following this schema:

| 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 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 with this structure:

{
  "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	Bash implementation for Linux/macOS
skills/scripts/refresh-tool-index.ps1	PowerShell implementation for Windows
skills/scripts/bootstrap-manifest.json	MCP capability declarations
docs/platforms/linux.md	Linux-specific installation guidance
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 and tool-index.json) generates independently of MCP functionality. The capability-status section appends additional information when bootstrap-manifest.json is present, but removal of that file does not break basic index generation.

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