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

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 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, the repository's governing specification file:

"When writing tool-index.md entries, paths MUST be complete absolute paths… include full path, version number, install method, and verification command." — RULES.md, lines 111-114

The English translation reinforces this:

"Never guess tool paths – read tool-index.md first, it contains the exact installed path for each tool." — RULES.md, lines 105-106

These rules establish 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 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 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:

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

#!/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	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	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	Example downstream skill reading tool-index.md for verification

Summary

• Complete absolute paths in tool-index.md eliminate path resolution ambiguity across Windows, macOS, Linux, and Kali
• 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 is generated?

Run the appropriate refresh script—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 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.

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