How to use the Agent QA Debug Fix agent skill

What the agent skill makes the agent do

When an automated end-to-end test run fails, the skill directs the agent to work like a careful QA engineer. It pulls the run's recorded steps, artifacts and logs through Agent QA's tools, and treats the automatic failure classification as a hypothesis rather than a verdict.

It then reads the relevant local test and application code, makes the smallest change that accounts for the evidence, validates any edited test definition, and reruns only the narrowest affected test. The skill is written to avoid weakening a test just to hide a real product bug.

• Collect evidence: run details, steps, artifacts, logs and execution logs.
• Check the classifier's category against the evidence.
• Identify the failing surface: test definition, hook, application under test, runtime infrastructure or agent behaviour.
• Apply the smallest code or YAML change and validate it before rerunning.
• Report the root cause, changed files, verification step, result and remaining risk.

Install the skill in Claude

Download the ZIP for this skill from this page. The skill is distributed as a file named SKILL.md inside the skills folder of the agentic-awesome-skills repository. Unzip it so the agent-qa-debug-fix folder sits in one of the locations below.

For a personal install across projects, place it in ~/.claude/skills/. For a single project, place it in the project's .claude/skills/ folder. Alternatively, if you use the Claude apps, you can upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/agent-qa-debug-fix/
• Project install: .claude/skills/agent-qa-debug-fix/ inside your repository
• Claude apps: Settings → Capabilities → Skills, then upload the skill

Confirm you have what the skill needs

The skill depends on three things. Without them the agent would be guessing, so check these first.

Agent QA platform access is needed for its MCP tools, such as agent_qa_get_run, agent_qa_classify_failure and the validate and run actions. If MCP is unavailable, the skill can fall back to dashboard REST APIs, and it is instructed to say that MCP evidence was unavailable.

• Agent QA platform access with its MCP tools, or dashboard REST APIs as a fallback
• Access to the local repository and any .agent-qa artifacts
• Ability to run the narrowest test or unit test in the approved environment

Trigger the skill with a natural request

You do not need special syntax. Describe the failed run and the outcome you want, and name the environment and the boundaries. The skill's own example shows the pattern: say which run failed, what must not be touched, and that you want a rerun.

Be specific about scope. The skill asks the agent to confirm the repository, workspace, target environment and files it may modify before it changes anything.

• Fix the failed staging checkout run, but do not touch production.
• Debug the failed run from yesterday's suite and patch only the evidenced cause.
• Self-heal the stale Agent QA definition for the login test from its run evidence, then rerun that single test.

Example workflow

Take the request to fix a failed staging checkout run without touching production. The agent collects the failed run evidence, classifies it, and inspects the implicated local definition and application code. It patches only the cause the evidence supports, validates the edited definition, and reruns the single staging test.

The final report should list the changed files, the verification step and any uncertainty that remains. Read that report before accepting the change.

Safety notes: scripts and network access

This skill runs scripts and uses the network, because it talks to Agent QA's tools and APIs and can rerun tests. Before running it, check which environment the rerun targets and what external side effects the test has.

The skill requires explicit confirmation for production-facing, destructive or irreversible actions. It also says not to expose credentials or sensitive data from artifacts and logs, and not to install dependencies or refactor beyond your approved scope. A careless approval can still allow something risky, so review each confirmation request carefully.

• Keep reruns in a staging or approved environment unless you have confirmed otherwise.
• Do not paste credentials into the request; the skill is told not to expose them from logs.
• Review changed files and the test's side effects before approving a rerun.

Tips for better repairs

Give the agent a precise run to work from and make sure it can reach the local source. Evidence without the code is not enough to establish a root cause. Expect intermittent browser, device, network or provider failures to need more than one successful rerun before you trust them.

A passing narrow rerun is not a replacement for your repository's full test suite or a human review.

• Name the exact failed run so evidence collection starts in the right place.
• Keep the request scoped to one failure rather than a whole suite.
• If the agent says the evidence cannot distinguish two fixes, answer with the missing detail instead of forcing a choice.