How reverse-skill Handles Missing Tools During Skill Workflow Execution

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, 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 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 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 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, the validation logic uses bash conditional operators to check for executable files:

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:

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 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 centralizes tool requirements with capability-to-path mappings that drive the validation process.
• Multi-stage validation: Checks occur during bootstrap (bootstrap-reverse.sh), smoke testing (smoke.sh), and pre-dispatch routing (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 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 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 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.

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