Fix Your Silent Slash Command Failures with Explicit Tool Calls

The Silent Failure Pattern

A developer's custom Claude Code slash commands (/blog-startaitools, /blog-single-startai) were creating blog posts, building Hugo sites, and reporting successful deployments. Yet, the new posts never appeared online. The site showed HTTP 200, content rendered, and Netlify reported deployment—everything seemed "working perfectly." The root cause? Uncommitted files. The slash command created the markdown file and ran the Hugo build but skipped the Git commit and push, leaving the new post stranded locally. The site appeared live because old content was still deployed.

Root Cause: Markdown Text vs. Tool Invocation

The broken command contained steps written as plain markdown instructions:

5. **Publish (After Approval)**
   - Create file: `/home/jeremy/projects/blog/startaitools/content/posts/[slug].md`
   - Run: `cd /home/jeremy/projects/blog/startaitools && hugo --gc --minify --cleanDestinationDir`
   - Verify build succeeds
   - Git commit with message: "feat: add blog post - [title]"
   - Git push to trigger Netlify deployment
   - Confirm deployment initiated

Claude Code interpreted this as documentation, not a series of actions to execute. It would perform explicit tool calls (like Write for the file and Bash for Hugo) found earlier in the prompt but treat subsequent Git instructions as descriptive text to be acknowledged, not acted upon.

The Fix: Demand Explicit Tool Calls

The solution is to structure slash commands with unambiguous tool invocation. Here's the corrected pattern:

5. **Publish (After Approval)**
   - Create file using Write tool: `/home/jeremy/projects/blog/startaitools/content/posts/[slug].md`
   - Build production using Bash tool:
     ```bash
     cd /home/jeremy/projects/blog/startaitools && hugo --gc --minify --cleanDestinationDir
     ```
   - Verify build output shows no errors
   - **CRITICAL: Execute git workflow using Bash tool:**
     ```bash
     cd /home/jeremy/projects/blog/startaitools
     git add content/posts/[slug].md
     git commit -m "feat: add blog post - [title]"
     git push origin main
     ```
   - Verify git push output shows "main -> main" (deployment trigger)
   - Netlify auto-deploys on successful git push

Key changes:

1. Explicit Tool References: Phrases like "using Write tool" and "using Bash tool" force Claude Code to treat the instruction as a tool call.
2. CRITICAL Marker: Adding **CRITICAL:** before a step emphasizes its necessity, reducing the chance the AI skips it.
3. Verification Steps: Instructions to check command output (e.g., for "main -> main") create a feedback loop to confirm execution.
4. Concrete Code Blocks: Placing commands inside ```bash blocks clearly delineates executable code from descriptive text.

Audit Your Commands with a Validation Script

To prevent this issue, create a validation script to scan your ~/.claude/commands/ directory. This script checks for Git-related instructions and ensures they are paired with explicit tool call markers.

#!/bin/bash
# ~/.claude/commands/validate-git-workflows.sh

for cmd in ~/.claude/commands/blog*.md; do
    git_refs=$(grep -c "git.*commit\|git.*push" "$cmd" || echo "0")

    if [ "$git_refs" -gt 0 ]; then
        critical=$(grep -c "CRITICAL.*Bash tool" "$cmd" || echo "0")

        if [ "$critical" -gt 0 ]; then
            echo "✅ $(basename $cmd) - PASS"
        else
            echo "⚠️  $(basename $cmd) - Missing CRITICAL markers"
        fi
    fi
done

Run this script after creating or modifying any slash command to catch potential silent failures.

Proactive Debugging: Ask the Right Question

The initial debugging mistake was asking Claude Code, "Is the site working?" The AI correctly verified the live site was up. The correct question was, "Why aren't my NEW posts appearing?" This shifts the verification target from general health to specific, expected outcomes. When debugging automated workflows, always craft verification steps that check for the new state you expect the command to create, not just the existing system status.