# Why Does `tool-index.md` Require Complete Absolute Paths Instead of Relative or Abbreviated Tool Names?

> Discover why tool-index.md requires absolute paths for reliable tool discovery across diverse environments. Ensure deterministic execution and eliminate path ambiguity.

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

---

**[`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) mandates complete absolute paths because it serves as the single source of truth for tool discovery across heterogeneous environments, eliminating path resolution ambiguity and ensuring deterministic execution on any host.**

The [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) file in the *reverse-skill* repository (`zhaoxuya520/reverse-skill`) functions as a definitive registry that tells scripts, CLI clients, and AI agents exactly where every security tool resides on the current machine. Because the repository runs on Windows, macOS, Linux, and Kali systems with tools installed in unpredictable locations, only full absolute paths provide reliable cross-platform tool location.

## Design Rationale in RULES.md

The core requirement originates in **[`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)**, the repository's governing specification file:

> "When writing [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) entries, *paths MUST be complete absolute paths*… include full path, version number, install method, and verification command." — [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md), lines 111-114

The English translation reinforces this:

> "Never guess tool paths – read [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) first, it contains the exact installed path for each tool." — [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md), lines 105-106

These rules establish [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) as an authoritative, parseable index rather than a casual reference document.

## How the Template Enforces Absolute Paths

The **`skills/tool-index.md.template`** file documents the expected structure:

> "The real [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) is auto-generated … the generated table contains the *Path* column with the actual location of each tool." — `tool-index.md.template`, lines 24-31

This template-driven approach ensures that every generated entry contains a concrete, fully-qualified path discovered at scan-time.

## Five Reasons Absolute Paths Are Mandatory

| Reason | Explanation |
|--------|-------------|
| **Unambiguous lookup** | Scripts invoke tools directly without relying on `$PATH` or working directory resolution |
| **Cross-platform consistency** | Windows batch, PowerShell, and Bash scripts all consume the same format |
| **Reproducibility** | [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) and `refresh-tool-index.ps1` record exact locations for CI parity |
| **Safety** | Prevents accidental execution of wrong binaries or malicious wrappers elsewhere on the system |
| **Bootstrap awareness** | Missing tools trigger explicit platform-specific installation workflows |

## Practical Code Examples

These snippets demonstrate how downstream automation depends on guaranteed absolute paths:

### PowerShell (Windows)

Read `r2` (Radare2) location from [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md):

```powershell

# Load the index

$index = Get-Content -Path "$PSScriptRoot\..\tool-index.md"

# Find the line that starts with the tool name

$line = $index | Where-Object { $_ -match '^r2\s+\|' }

# Extract the Path column (5th column)

$path = ($line -split '\|')[5].Trim()
Write-Host "Radare2 executable is at: $path"

```

### Bash (Linux/macOS/Kali)

Fetch `adb` absolute path:

```bash
#!/usr/bin/env bash

# Locate the adb entry in tool-index.md

tool_path=$(grep '^adb' skills/tool-index.md | awk -F'|' '{gsub(/^ +| +$/,"",$5); print $5}')
echo "adb is installed at: $tool_path"

```

Both examples assume the *Path* column contains a complete absolute path (e.g., `/opt/adb/adb` or `C:\Program Files\Android\platform-tools\adb.exe`), enabling direct invocation without additional resolution logic.

## Key Implementation Files

| File | Role |
|------|------|
| [`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md) | Defines the absolute path mandate (lines 105-106, 111-114) |
| `skills/tool-index.md.template` | Specifies the generated format including the *Path* column |
| [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) | Discovers tools and writes absolute paths on Unix systems |
| `skills/scripts/refresh-tool-index.ps1` | Windows counterpart for tool discovery |
| [`skills/ida-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/ida-reverse/SKILL.md) | Example downstream skill reading [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) for verification |

## Summary

- **Complete absolute paths** in [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) eliminate path resolution ambiguity across Windows, macOS, Linux, and Kali
- **[`RULES.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/RULES.md)** codifies this requirement as a mandatory rule, not a suggestion
- **Template and refresh scripts** enforce the structure automatically at generation time
- **Downstream scripts** depend on guaranteed absolute paths for direct, safe tool invocation
- **Cross-platform reproducibility** depends on deterministic tool discovery without environment variable dependencies

## Frequently Asked Questions

### What happens if a tool path changes after [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) is generated?

Run the appropriate refresh script—[`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) on Unix or `skills/scripts/refresh-tool-index.ps1` on Windows—to rescan the system and regenerate the index with current absolute paths. The repository treats stale paths as missing tools and triggers the bootstrap workflow.

### Why not use environment variables like `$PATH` instead?

Environment variables are mutable, platform-specific, and vary between user sessions. Absolute paths in [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) provide immutable, versioned records that persist across shells, users, and CI environments without configuration drift.

### Can relative paths work if the repository structure is consistent?

Even with consistent cloning, tool installations reside in system-dependent locations outside the repository (e.g., `C:\Program Files\`, `/usr/local/bin/`, `$HOME/.local/bin/`). Relative paths cannot reach these external locations reliably.

### How does the system handle tools installed in multiple locations?

The refresh scripts select the first discovered instance or apply version-priority logic, then record that specific absolute path. Downstream code uses exactly what was written, avoiding ambiguous selection at runtime.