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

Platform detection in README_AI.md uses PowerShell runtime flags to identify the host OS, then looks up the corresponding documentation path in skills/config/routing.json to route users to Windows, Linux, or macOS guides.

The 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".

# 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.

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

{
    "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:

# 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 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 with the platform identifier and documentation path
• Create the corresponding markdown file under docs/platforms/

No modifications to 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	AI-focused entry point; performs platform detection and orchestrates routing
skills/config/routing.json	Central configuration mapping platform strings to documentation paths
docs/platforms/linux.md	Linux-specific installation and usage instructions
docs/platforms/macos.md	macOS-specific installation and usage instructions
docs/platforms/windows.md	Windows-specific installation and usage instructions
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 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 with a new key-value pair and creating the corresponding documentation file. The detection logic in 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 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.

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