cli-agent-diagnose

Name: cli-agent-diagnose
Availability: InStock
Author: cli-agent-spec

Classify failed AI-agent CLI calls into CLI Agent Spec failure modes with workarounds.

5|Updated Mar 14, 2026

Search Tags:#cli #tooling #diagnosis #ai-agents #failure-modes #workaround #trace-classification

Ready to run

npx skills add https://github.com/cli-agent-spec/cli-agent-spec --skill cli-agent-diagnose

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: cli-agent-diagnose
Source: https://github.com/cli-agent-spec/cli-agent-spec/tree/main/skills/cli-agent-diagnose
Command: npx skills add https://github.com/cli-agent-spec/cli-agent-spec --skill cli-agent-diagnose

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

It turns opaque, failed CLI tool calls by AI agents into a classified CLI Agent Spec failure mode with a concrete workaround and guidance to prevent the same recurrence.

Core Features & Use Cases

Failure classification from a structured trace including command, stdout, stderr, and exit code.
Deterministic diagnosis with optional LLM-based classification for ambiguous cases.
Inline operational guidance: actionable workaround, limitation, and memory/skill patch output after successful matches.
Optional proactive interception via a Claude Code PreToolUse hook to warn before risky Bash calls.

Quick Start

Diagnose a failed CLI invocation by providing a trace JSON (command, stdout, stderr, exit_code) and running the classifier.

Frequently Asked Questions about cli-agent-diagnose

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I diagnose CLI tool call failures from AI agent traces?▼

To diagnose AI agent CLI failures, you provide a structured trace JSON with command, stdout, stderr, and exit code, then run the classifier to identify the matching failure mode. This process returns an actionable workaround for the specific command error.

What is the best way to classify AI agent error modes from command output?▼

The best way to classify AI agent error modes is using a taxonomy-based diagnostic tool that parses command output signals and optionally applies LLM classification for ambiguous cases. This yields a specific failure mode and a skill patch to prevent recurrence.

How do I prevent recurring CLI failures when using AI agents?▼

You prevent recurring CLI failures by running a diagnostic classifier on failed traces to emit a memory update and a reusable skill patch. This workflow patches the agent's behavior to avoid repeating the same command execution mistake.

Can I intercept and warn against risky Bash calls before an AI agent executes them?▼

Yes, you can proactively intercept risky Bash calls using an optional Claude Code PreToolUse hook. This hook warns the agent before executing potentially risky commands, preventing failures before they happen.

Does the CLI failure classifier require an LLM to diagnose ambiguous agent errors?▼

No, the CLI failure classifier uses deterministic matching for clear command output signals and only optionally uses an Anthropic LLM classifier for ambiguous cases. This dual approach ensures accurate diagnosis without always requiring LLM overhead.

What are the limitations of using deterministic trace classification for AI agent failures?▼

Deterministic trace classification is limited when command output signals are ambiguous or do not match known failure taxonomy entries. In these cases, the optional LLM-based classifier is required to infer the correct failure mode and workaround.