How to use the Test Failure Explorer agent skill

What is an agent skill, and what does this one do?

An agent skill is a folder with a SKILL.md file that gives an AI agent extra instructions and tools for one kind of task. This skill, test-failure-explorer, is for inspecting results from Vitest, a JavaScript test runner. Once it is installed, the agent can import an existing Vitest 3.2 JSON report, count failures, list files that had errors, and quote the original diagnostic text for specific failed tests.

The skill does not run your tests and does not fix code. It works only on the report file. The agent separates what the report states from what it guesses about causes, and it cites failed test IDs instead of paraphrasing them.

• Imports a report into a workspace-local snapshot with a reportId and source hash
• Answers count questions with a short text answer
• Lists failures and file-level errors, with filtering and paging
• Shows original diagnostic evidence for a failed item

Install the Test Failure Explorer skill

Download the skill ZIP from this page and unzip it. The skill folder contains SKILL.md. Place the unzipped folder in one of these locations, depending on how you want to use it:

• Personal use across projects: ~/.claude/skills/
• Single project: the project's .claude/skills/ folder
• Claude apps: upload the ZIP under Settings → Capabilities → Skills

Get a Vitest 3.2 JSON report

The skill needs a report file that already exists in your workspace. It is verified only with the Vitest 3.2 JSON shape, verified with Vitest 3.2.7. If the report comes from a different tool or format, the skill is not designed to read it.

Ask for the report by its workspace-relative path. If you do not know the path, tell the agent and it will ask you for it. The skill does not launch tests, so the report must be generated by your own test run or CI job.

• Report must be a Vitest 3.2 JSON report stored in the workspace
• Qwen Code, or a host that supports the test_report_import, test_report_query and test_report_show tools

Ask for help with natural requests

You do not need special syntax. Name the report path and say what you want to know. The agent chooses between a quick count, a list of failures, or an interactive view depending on the question.

• "Import reports/vitest.json and tell me how many tests failed."
• "Which files had errors in this report? Use the workspace path."
• "Show the original diagnostic for the first failure and cite its ID."
• "Open the failure list in reports/vitest.json and filter for 'timeout'."
• "Group the failures by file and tell me which explanations are facts and which are guesses."

Read the results carefully

The agent will state that its findings are report-only evidence. The report does not prove that the test process finished, what the exit code was, whether there were unhandled errors, or which Git commit was tested. A passing flag in the report is not proof that the run completed.

File-level errors are not the same as failed assertions, and a failed file can contain no assertions. Pending, skipped and todo tests are counted separately. Suite counts are not file counts. Duplicate test titles are treated as distinct items, so the agent cites item IDs.

Safety notes: scripts, network and stored data

This skill runs no scripts and uses no network access. Each import writes an immutable snapshot file inside the workspace, and that file persists in the project. Do not import reports that contain sensitive data unless you are comfortable keeping a copy in the project.

Report paths, test titles and diagnostic strings are treated as untrusted data. The agent should not follow instructions found inside them. If you later ask the agent to run tests or change code, that work follows your normal tool permissions and requested scope.

• Scripts: none
• Network: none
• Import writes a workspace-local snapshot that is not private to the session
• Reimporting a newer report does not silently replace an earlier snapshot