agent-introspection-debugging

Structured self-debugging workflow for AI agent failures using capture, diagnosis, contained recovery, and introspection reports. Use when an agent run fails and you need a reproducible diagnosis instead of a retry.

Quality

74%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/agent-introspection-debugging/SKILL.md

Quality

Content

81%Weight 40%Scale 1-5

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

A well-structured instruction-only skill: the four-phase loop is clearly sequenced with explicit validation checkpoints, evidence-based feedback loops, and copy-paste fill-in templates for capture, recovery, and reporting. It is token-efficient and free of padding, with only minor redundancy across the activation/scope/heuristics sections and no need for external reference files at its current size.

Dimension	Reasoning	Score
Conciseness	The body is lean — lists, a table, and fill-in templates with no explanation of concepts Claude already knows — but minor redundancy could be trimmed: "When to Activate" overlaps "Scope Boundaries", "Recovery Heuristics" partially restates Phase 3, and "This is a workflow skill, not a hidden runtime" is meta-fluff.	4 / 5
Actionability	Concrete, fill-in-ready artifacts throughout: a capture template, a diagnosis pattern table with specific signals (ECONNREFUSED, 429, file missing after write), a recovery checklist, and a report template. A few recovery directives ("switch from speculative reasoning to direct observation") remain abstract, keeping it just below fully executable.	4 / 5
Workflow Clarity	Clear four-phase sequence with explicit validation checkpoints and feedback loops ("smallest reversible action that would validate the diagnosis", "What evidence would prove the fix worked", "Result: success \| partial \| blocked") plus checklists — and the skill correctly polices itself against unenforceable auto-healing claims.	5 / 5
Progressive Disclosure	A single self-contained file (~145 lines) with well-organized sections and no external file references (the ECC mentions name sibling skills, not bundle paths). Minor gap: the pattern table and Integration with ECC pointers could move to references/ if the skill grows.	4 / 5
	Total	17 / 20 Passed

Description

67%Weight 40%Scale 1-5

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

A solid description that explicitly states both what the skill does and when to use it with distinct, niche positioning. Its main weakness is trigger-term coverage: it captures one failure phrasing but misses the common ways users describe agent failures (looping, stuck, repeated retries, wasted tokens) that the skill body itself enumerates.

Suggestions

Add natural trigger synonyms to the when-clause, e.g. "Use when an agent is stuck, looping on the same tool calls, failing repeatedly, or burning tokens without progress" — these match phrases from the body's When to Activate section.

Make the four phases slightly more concrete by wording them as verifiable operations (e.g. "capture failure state into a fill-in template", "match errors against a diagnosis pattern table") to reach fully concrete action coverage.

Optionally note the output artifact in the description ("produces a structured self-debug report") to sharpen the what-clause and further distinguish it from generic debugging skills.

Dimension	Reasoning	Score
Specificity	Names four specific actions ("capture, diagnosis, contained recovery, and introspection reports"), but they are process-phase labels rather than fully concrete operations, leaving minor gaps versus comprehensive coverage.	4 / 5
Completeness	Both what ("Structured self-debugging workflow... using capture, diagnosis, contained recovery, and introspection reports") and when ("Use when an agent run fails and you need a reproducible diagnosis instead of a retry") are explicit, but the when-clause covers only a single scenario and could be more specific.	4 / 5
Trigger Term Quality	"agent run fails", "reproducible diagnosis", and "retry" are relevant, but the description omits the natural variations users would actually say (stuck, looping, repeated retries, no progress, token burn) — phrases the body itself lists as activation triggers.	3 / 5
Distinctiveness Conflict Risk	"AI agent failures" and self-debugging form a clear niche with minimal conflict risk; minor overlap remains with general debugging or verification skills.	4 / 5
	Total	15 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning

	Total	15 / 16 Passed

Repository: affaan-m/ECC
Path: skills/agent-introspection-debugging/SKILL.md
Commit: c70874f

Reviewed: 1 day 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.