shell-error-debug-workflow

Systematic workflow for diagnosing and resolving unknown errors from run_shell commands

Quality

53%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

High

Do not use without reviewing

Fix and improve this skill with Tessl

tessl review fix ./benchmarks/gdpval/skills/shell-error-debug-workflow/SKILL.md

Quality

Content

57%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a well-organized, actionable debugging workflow with clear sequencing and good section navigation, but it is held back by redundancy across the step-by-step, diagnostic-sequence, and example sections plus implicit decision checkpoints between steps.

Suggestions

Collapse the "Complete Diagnostic Sequence" and "Example" sections into the numbered steps to remove restated content, or move one into a reference file.

Add explicit decision checkpoints, e.g. after each step: "If stderr now reveals the error, fix it; otherwise continue to Step N."

Trim over-explanations of basic shell behavior (the 2>&1 rationale, env-var dependence) since Claude already knows these.

Dimension	Reasoning	Score
Conciseness	Mostly concrete commands, but it explains basics Claude already knows (e.g. "This ensures error messages are captured rather than being lost", "Some commands depend on specific environment variables") and the "Complete Diagnostic Sequence" and "Example" sections restate the numbered steps, adding redundancy.	2 / 3
Actionability	Diagnostic commands (pwd, ls -la, which, env, 2>&1) are concrete and executable, but the target commands use placeholders ("some-command", "your-command", "/full/path/to/your-command") that must be substituted, so it is not fully copy-paste ready.	2 / 3
Workflow Clarity	Steps 1-6 are clearly sequenced with a recovery table and escalation section, but the decision checkpoints between steps (when to stop and move on, what result indicates the issue is solved) are implicit rather than explicit.	2 / 3
Progressive Disclosure	No bundle files exist and none are needed; the single self-contained file is organized into clearly headed sections (When to Use, Steps, Diagnostic Sequence, Causes table, Example, Best Practices, Escalation) with easy navigation.	3 / 3
	Total	9 / 12 Passed

Description

50%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description identifies a clear domain and a couple of actions but reads at a mid-level specificity throughout, with no explicit "Use when..." trigger clause to fully answer when to invoke it. It is distinguishable yet not sharply niche enough to avoid overlap with broader debugging skills.

Suggestions

Add an explicit trigger clause, e.g. "Use when run_shell returns an 'unknown error' or a command fails with no clear output."

Replace the abstract "diagnosing and resolving" with concrete actions, e.g. "capture stderr, verify working directory, check command availability, and test with absolute paths."

Include natural variations users might say ("shell command failed", "command not found in PATH", "debug shell error") to broaden trigger coverage.

Dimension	Reasoning	Score
Specificity	Names the domain ("run_shell commands") and two actions ("diagnosing and resolving unknown errors"), but stops short of listing multiple concrete, specific actions the way the top anchor does.	2 / 3
Completeness	It clearly states what the skill does, but the "when" is only implied; per the rubric, a missing "Use when..." clause caps completeness at 2.	2 / 3
Trigger Term Quality	Includes relevant keywords ("run_shell", "unknown error") an agent user might say, but lacks common variations ("shell command failed", "command not found", "debug shell error") and carries no explicit trigger phrasing.	2 / 3
Distinctiveness Conflict Risk	Tied to a specific tool and failure mode, but the generic "diagnosing and resolving" framing and absence of explicit triggers means it could still overlap with general debugging/troubleshooting skills.	2 / 3
	Total	8 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: HKUDS/OpenSpace
Path: benchmarks/gdpval/skills/shell-error-debug-workflow/SKILL.md
Commit: c5a9c4b

Reviewed: 2 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.