# How Platform Detection in README_AI.md Routes to OS-Specific Documentation

> Discover how platform detection in README_AI.md uses PowerShell to find your OS and route you to the correct Windows, Linux, or macOS documentation.

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

---

**Platform detection in [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md) uses PowerShell runtime flags to identify the host OS, then looks up the corresponding documentation path in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) to route users to Windows, Linux, or macOS guides.**

The [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md) file serves as the AI-focused entry point for the *reverse-skill* repository. It implements an automated routing system that detects the operating system at runtime and directs users to platform-appropriate documentation without manual intervention.

## How Platform Detection Works

The detection logic relies on PowerShell's built-in automatic variables that expose the runtime environment. These variables are available in PowerShell 6.0+ and provide reliable cross-platform OS identification.

The script evaluates three boolean flags in order of priority:

- **`$IsWindows`** — true when running on Windows
- **`$IsLinux`** — true when running on Linux
- **`$IsMacOS`** — true when running on macOS

If none match, the platform falls back to `"unknown"`.

```powershell

# Detect the current OS

if ($IsWindows) {
    $platform = "windows"
} elseif ($IsLinux) {
    $platform = "linux"
} elseif ($IsMacOS) {
    $platform = "macos"
} else {
    $platform = "unknown"
}
Write-Host "Detected platform: $platform"

```

## The Routing Table in routing.json

Once the platform identifier is determined, the script resolves the documentation path using a static JSON configuration file located at [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json).

This file maintains a simple key-value mapping where each platform string maps to a relative path under `docs/platforms/`:

```json
{
    "windows": "docs/platforms/windows.md",
    "linux":   "docs/platforms/linux.md",
    "macos":   "docs/platforms/macos.md"
}

```

The routing lookup loads this configuration and retrieves the matching documentation path:

```powershell

# Load the routing map

$routing = Get-Content -Raw -Path "$PSScriptRoot/skills/config/routing.json" |
           ConvertFrom-Json

# Resolve the documentation file for the detected platform

$docPath = $routing.$platform
Write-Host "Routing to documentation: $docPath"

# Display the platform-specific documentation

Get-Content -Path $docPath | Write-Host

```

## Complete Routing Flow

The platform detection and routing mechanism follows this execution path:

```

README_AI.md → PowerShell platform detection → routing.json lookup → docs/platforms/<os>.md

```

The flow executes in three stages:

1. **Runtime detection** — PowerShell variables identify the host OS
2. **Configuration lookup** — [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) provides the documentation path
3. **Content delivery** — The matching markdown file is loaded and displayed

## Extending Platform Support

Adding a new platform requires only two changes according to the repository structure:

- Add a new key-value pair to [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) with the platform identifier and documentation path
- Create the corresponding markdown file under `docs/platforms/`

No modifications to [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md) are necessary since the detection logic handles unknown platforms gracefully via the fallback case.

## Key Files and Their Roles

The routing system spans several files across the repository:

| File | Purpose |
|------|---------|
| [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md) | AI-focused entry point; performs platform detection and orchestrates routing |
| [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Central configuration mapping platform strings to documentation paths |
| [`docs/platforms/linux.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/linux.md) | Linux-specific installation and usage instructions |
| [`docs/platforms/macos.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/macos.md) | macOS-specific installation and usage instructions |
| [`docs/platforms/windows.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/platforms/windows.md) | Windows-specific installation and usage instructions |
| [`skills/MASTER-ROUTING.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/MASTER-ROUTING.md) | High-level architectural documentation for the routing system |

## Summary

- **Platform detection** uses PowerShell automatic variables `$IsWindows`, `$IsLinux`, and `$IsMacOS`
- **Routing configuration** lives in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) as a static key-value map
- **Documentation paths** follow the convention `docs/platforms/<platform>.md`
- **Extensibility** requires only JSON and markdown additions with no script changes
- **Fallback handling** ensures graceful degradation when platforms cannot be identified

## Frequently Asked Questions

### What PowerShell version is required for the platform detection?

PowerShell 6.0 or later. The automatic variables `$IsWindows`, `$IsLinux`, and `$IsMacOS` were introduced with PowerShell Core 6.0 to enable cross-platform scripting. Earlier Windows PowerShell versions (5.1 and below) do not expose these variables.

### Can the routing system be modified to support additional platforms?

Yes. Adding support for platforms like FreeBSD or WSL only requires updating [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) with a new key-value pair and creating the corresponding documentation file. The detection logic in [`README_AI.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/README_AI.md) will automatically pick up new entries through the dynamic property access `$routing.$platform`.

### Where does the routing configuration file live?

The routing configuration is stored at [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) relative to the repository root. The detection script constructs this path using `$PSScriptRoot` to ensure correct resolution regardless of the working directory.

### What happens if the detected platform has no routing entry?

The script attempts to access `$routing.$platform` which returns `$null` for missing keys. The subsequent `Get-Content` call would fail gracefully or the implementation may include additional error handling to alert the user that platform-specific documentation is unavailable for their system.