# How reverse-skill Automates Tool Selection for AI Agents in Security Tasks

> Discover how reverse-skill automates AI agent tool selection for security tasks by inspecting environments and building tool manifests for efficient capability invocation.

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

---

**reverse-skill acts as a skill router that inspects the environment, builds a tool-availability manifest, and selects the appropriate tool-MCP capability for an AI agent to invoke.**

AI agents in security workflows need reliable access to specialized tools like `nmap`, `ffuf`, and `hashcat`—but only if those tools are installed, properly registered, and ready to execute. According to the `zhaoxuya520/reverse-skill` source code, this open-source framework solves the tool-selection problem through a three-stage pipeline: environment discovery, MCP capability validation, and JSON-based routing decisions.

## The Three-Stage Automation Pipeline

### Stage 1: Discovery and Indexing

The automation begins with [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) (and its PowerShell equivalent), which performs comprehensive host scanning to detect:

- **Core runtimes**: Node.js, Python, Java
- **Common security binaries**: `nmap`, `ffuf`, `hashcat`, `gobuster`, `burpsuite`
- **MCP-enabled utilities**: `jshookmcp`, `reqable-mcp`, `xquik-mcp`

This script populates [`tool-index.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.json) and [`tool-index.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/tool-index.md) with each tool's presence status, version string, and fallback installation paths.

```bash

# Generate the tool manifest (Linux/macOS)

bash skills/scripts/refresh-tool-index.sh

```

The generated JSON serves as the ground-truth manifest that downstream components reference before making routing decisions.

### Stage 2: MCP Registration and Capability Evaluation

Once the tool index exists, [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) evaluates **MCP readiness** by:

1. Reading `~/.claude/mcp.json` (or equivalent client configs)
2. Verifying HTTP handshakes with registered servers
3. Computing three-state capability flags: **available**, **registered**, **ready**

Lines 260-330 of this script implement the **capability matrix** logic, where `tool_available` AND `registered` yields `ready: true`. The script also generates a formatted table (near line 350) displaying the current capability state for operator review.

```bash

# Register MCP servers for Claude

bash skills/scripts/bootstrap-reverse.sh --mcp-host=claude

# Skip re-indexing if tool-index.json is current

bash skills/scripts/bootstrap-reverse.sh --skip-refresh

```

### Stage 3: Routing Decision

The [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) file provides the single source of truth for task-to-skill mapping. When an AI agent submits a request like this:

```json
{
  "task": "run a network scan",
  "keywords": ["nmap", "port scanning"]
}

```

The router executes the following matching logic:

1. Identifies the `"pentest-tools"` skill from keyword matching
2. Queries the manifest for `nmap` capabilities
3. Validates `tool_available: true` and `registered: true`
4. Returns the executable command or wrapped MCP call for agent invocation

This ensures agents **never attempt to call unavailable tools**, eliminating runtime failures and hallucinated tool usage.

## Core Mechanisms Enabling Automation

| Mechanism | Purpose | Source File |
|-----------|---------|-------------|
| **Tool-discovery scripts** | Detect binaries, runtime versions, and MCP-specific packages | [`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) |
| **MCP configuration handling** | Read/write MCP server definitions; verify HTTP handshakes | [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) |
| **Capability matrix** | Compute `ready` flag from detection + registration states | [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) (lines 260-330) |
| **Routing JSON** | Map task domains to required capabilities; select first matching ready tool | [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) |
| **Kali-specific discovery** | Extended detection for `metasploitmcp`, `hexstrike-ai`, and other Kali-native tools | [`kali/scripts/lib/tool-discovery.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/lib/tool-discovery.sh) |

## Kali Linux Environment Support

For penetration testing workflows, [`kali/scripts/lib/tool-discovery.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/lib/tool-discovery.sh) extends the base discovery logic with Kali-specific MCP tools. This variant exposes additional capabilities like `metasploitmcp` for Metasploit integration and `hexstrike-ai` for binary analysis, maintaining identical JSON output formats for seamless router compatibility.

## Key Implementation Files

| File | Role in Automation |
|------|------------------|
| [[`skills/scripts/refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/refresh-tool-index.sh) | Ground-truth tool detection and manifest generation |
| [[`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) | MCP registration, capability validation, routing orchestration |
| [[`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json)](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) | Central routing matrix mapping task categories to tool capabilities |
| [[`kali/scripts/lib/tool-discovery.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/lib/tool-discovery.sh)](https://github.com/zhaoxuya520/reverse-skill/blob/main/kali/scripts/lib/tool-discovery.sh) | Kali-optimized discovery with extended MCP tool support |
| [[`docs/ARCHITECTURE.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md)](https://github.com/zhaoxuya520/reverse-skill/blob/main/docs/ARCHITECTURE.md) | System architecture documentation for integration planning |

## Summary

- **Environment-aware indexing**: [`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) builds a complete inventory of installed security tools and runtimes
- **MCP capability validation**: [`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh) ensures tools are both installed AND properly registered before routing
- **JSON-driven routing**: [`routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/routing.json) provides declarative task-to-skill mappings that the router evaluates at runtime
- **Fail-safe execution**: Agents receive only validated, ready-to-execute tool commands—no hallucinated or unavailable tool calls

## Frequently Asked Questions

### How does reverse-skill prevent AI agents from calling missing tools?

The framework computes a **three-state capability flag** (`available`, `registered`, `ready`) for every detected tool. Only tools where both `tool_available: true` AND `registered: true` receive `ready: true`. The router in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json) exclusively selects from ready-capable tools, blocking any request that would invoke an unverified binary or unregistered MCP server.

### What security tools does the discovery script detect?

[`refresh-tool-index.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) detects network scanners (`nmap`, `masscan`), web fuzzers (`ffuf`, `gobuster`), password crackers (`hashcat`, `john`), reverse-engineering frameworks (`ghidra`, `binary-ninja`), and MCP-enabled utilities (`jshookmcp`, `reqable-mcp`, `xquik-mcp`). The Kali-specific variant adds `metasploitmcp` and `hexstrike-ai` for specialized penetration testing workflows.

### Can reverse-skill work with multiple MCP clients simultaneously?

Yes. The [`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh) script accepts a `--mcp-host` parameter supporting `claude`, `codex`, and `kali` values. It reads and writes the appropriate configuration file for each client (e.g., `~/.claude/mcp.json`), enabling parallel registration across different AI agent environments while maintaining a unified capability evaluation logic.

### Where is the routing logic configured?

The declarative routing matrix lives in [`skills/config/routing.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/config/routing.json). This JSON file maps task domains (reverse-engineering, pentesting, mobile analysis, etc.) to required capability sets. The bootstrap script evaluates this configuration against the live capability matrix to determine which specific tool or MCP endpoint fulfills each incoming agent request.