# How reverse-skill Handles Missing Tools During Skill Workflow Execution

> Discover how reverse-skill handles missing tools during workflow execution. Learn about its fail-fast validation pipeline for immediate error reporting.

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

---

**reverse-skill implements a fail-fast validation pipeline that checks for required binaries and scripts during the bootstrap phase, aborting execution immediately with explicit error messages if any dependencies are missing.**

The zhaoxuya520/reverse-skill repository employs a defensive architecture to handle missing tools during the execution of a skill workflow. Rather than allowing partial executions or runtime crashes, the system validates every declared dependency before invoking any skill logic. This approach ensures that workflow failures occur early with clear diagnostic output, preventing ambiguous errors deep in the execution chain.

## The Three-Layer Validation Architecture

The reverse-skill framework validates tool availability through three coordinated checkpoints that gate workflow progression.

### Bootstrap Manifest Declaration

At the core of the detection system lies [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json), which declares every external utility and script required by the platform. Each entry maps a capability name (such as `__test_missing__`) to a specific file system path. During initialization, the bootstrap scripts—[`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) for Linux environments and `skills/scripts/bootstrap-reverse.ps1` for Windows—load this manifest and iterate over each declared capability.

### Pre-Execution Smoke Testing

After bootstrap completes, the system executes platform-specific smoke tests located in [`skills/scripts/smoke.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/smoke.sh) and `skills/scripts/smoke.ps1`. These scripts perform explicit sanity checks for critical routing components such as `verify-routing-coherence.ps1` and `master-route.ps1`. When a required script is absent, the smoke test invokes a `Bad` reporting function that prints a specific error message like `Bad 'verify-routing-coherence.ps1 missing'` and terminates with a non-zero exit code.

### Runtime Routing Guards

Finally, the master routing scripts—[`skills/scripts/master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/master-route.sh) or the Python equivalent—validate the existence of the primary skill binary immediately before dispatch. If the target skill file is missing, the router emits an error such as `Bad "PRIMARY skill missing: $skill_path"` and aborts execution before any skill code runs.

## Platform-Specific Implementation Details

The detection mechanisms leverage native shell capabilities to verify file existence and executability.

### Bash Tool Verification in bootstrap-reverse.sh

In [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh), the validation logic uses bash conditional operators to check for executable files:

```bash
for cap in "${CAPABILITIES[@]}"; do
    tool_path=$(jq -r ".${cap}" "$MANIFEST")
    if [[ ! -x "$tool_path" ]]; then
        echo "ERROR: missing $cap ($tool_path)" >&2
        exit 1
    fi
done

```

This loop extracts each tool path from the JSON manifest using `jq`, then verifies executability with `[[ -x "$tool_path" ]]`. The script redirects error messages to standard error and exits immediately upon the first missing dependency.

### PowerShell Validation in bootstrap-reverse.ps1

The PowerShell implementation in `skills/scripts/bootstrap-reverse.ps1` utilizes the `Test-Path` cmdlet for filesystem validation:

```powershell
if (-not (Test-Path $verifyRoutingPath)) {
    Bad 'verify-routing-coherence.ps1 missing'
}

```

The `Test-Path` check returns a boolean indicating file existence, allowing the script to invoke the `Bad` function with a descriptive message before terminating.

## Error Handling and Abort Mechanisms

Every validation layer in reverse-skill follows a strict fail-fast policy. When [`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh) detects a missing capability, it prints `ERROR: missing $cap` to standard error and returns exit code 1. Similarly, the smoke tests emit structured failure messages through the `Bad` function, ensuring that missing tools during the execution of a skill workflow trigger immediate, visible failures rather than silent degradation or runtime exceptions.

## Summary

- **Manifest-based declaration**: [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) centralizes tool requirements with capability-to-path mappings that drive the validation process.
- **Multi-stage validation**: Checks occur during bootstrap ([`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh)), smoke testing ([`smoke.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/smoke.sh)), and pre-dispatch routing ([`master-route.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/master-route.sh)).
- **Platform-native detection**: Bash uses `[[ -x ]]` while PowerShell uses `Test-Path` for filesystem validation.
- **Immediate abort**: All detection points exit with non-zero status codes and descriptive error messages via `Bad` functions or `ERROR` logs.

## Frequently Asked Questions

### What happens if a tool is deleted after bootstrap but before skill execution?

If a required binary or script is removed after the initial bootstrap phase but before the skill runs, the smoke test scripts ([`skills/scripts/smoke.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/smoke.sh) or `smoke.ps1`) or the master routing script will detect the absence during their pre-execution checks. The system prints a `Bad` error message and aborts with a non-zero exit code.

### How does reverse-skill locate the tools listed in bootstrap-manifest.json?

The bootstrap scripts read [`bootstrap-manifest.json`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-manifest.json) using JSON parsing tools like `jq` in bash, mapping capability keys to absolute file system paths. Each path is then validated independently using platform-specific file existence checks against the declared capabilities.

### Can the bootstrap process skip missing tools and continue execution?

No, the architecture intentionally prevents skipping. The bootstrap scripts exit immediately upon encountering the first missing tool, as implemented in the `exit 1` logic within [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) and corresponding PowerShell error handling.

### Where are the error messages defined when tools are missing?

Error messages are generated inline within the validation scripts. The bash bootstrap script outputs `ERROR: missing $cap ($tool_path)` to stderr, while PowerShell scripts utilize a dedicated `Bad` function to emit messages like `'verify-routing-coherence.ps1 missing'` in `skills/scripts/smoke.ps1`.