qa

Overview of qa skill

The qa skill turns a loose bug-report conversation into durable GitHub issues. Instead of asking users to write polished tickets up front, it guides an agent to listen briefly, gather only the missing details, inspect the codebase in the background for product context, and then file issues in the project’s own language.

What the qa skill is for

This qa skill is best for teams that want better issue quality without forcing reporters to know the codebase. The real job-to-be-done is not “debug the bug” or “fix the code.” It is to capture a user-reported problem clearly enough that engineering can triage it later.

Who should install qa

Install qa if you:

• collect bugs through chat or assistant workflows
• want GitHub issues written from conversational reports
• need reports framed in user-facing language, not internal implementation detail
• want the agent to split one messy complaint into multiple issues when needed

It is especially useful for qa for Issue Tracking, where the output quality of the issue matters more than immediate diagnosis.

What makes qa different from a generic prompt

A normal prompt might ask an assistant to “write a bug report.” The qa skill adds operating rules that improve consistency:

• ask only a few clarifying questions
• explore the relevant code area in the background
• learn domain language before writing
• avoid leaking file names, line numbers, or speculative internals into the issue
• decide whether the report is one issue or several

That combination is the main reason to use qa instead of a one-off prompt.

What users usually care about first

Most adopters evaluating qa install care about four things:

1. Will it reduce back-and-forth with bug reporters?
2. Will it produce issues that engineers can triage?
3. Will it avoid overfitting to guessed root causes?
4. Will it fit an existing GitHub issue workflow?

For those goals, qa is a strong fit. It is lightweight, opinionated, and focused on issue quality rather than debugging depth.

Important limits before you adopt

The qa skill does not promise root-cause analysis or a fix. Its background exploration is there to understand product behavior and terminology, not to produce implementation advice. If you want failure analysis, reproduction automation, or patch generation, you will need other skills or a separate workflow.

How to Use qa skill

Install context for qa skill

The repository exposes qa as a skill inside mattpocock/skills. If your environment supports skill installation from that collection, use your normal skill manager flow to add the qa skill from that repo. In many skill-enabled setups, that looks like:

npx skills add mattpocock/skills --skill qa

If your agent platform handles skills differently, the key point is simpler: make the qa skill available so the agent can follow its issue-reporting workflow, not just paraphrase the bug report.

When to trigger qa in practice

Use qa usage when a person says things like:

• “I found a bug”
• “Can you file an issue for this?”
• “Let’s do a QA session”
• “This flow behaves strangely”
• “I’m not sure if this is one problem or several”

Trigger it early, before the conversation turns into ad hoc debugging. The skill is strongest when the user is still describing symptoms and expected behavior.

What input qa needs from the user

The qa skill can work from rough input, but it performs best when it gets:

• what the user expected
• what actually happened
• rough reproduction steps
• whether the problem is consistent or intermittent
• any visible error messages or screenshots, if available

It does not need a polished issue template. The whole point is to transform informal reporting into a useful issue.

How to turn a rough report into a strong qa prompt

A weak start:

• “Something is broken in checkout.”

A stronger prompt for qa:

• “Run a QA session for checkout. When I apply a discount code and go back a step, the total sometimes resets. I expected the discount to persist. It happens about half the time in Chrome.”

That stronger version helps the skill decide what to clarify and what code area to inspect, without forcing the user to write the final issue themselves.

The ideal qa workflow

A practical qa guide looks like this:

1. Let the user explain the problem in their own words.
2. Ask no more than 2–3 short clarifying questions.
3. Explore the relevant area of the codebase in the background.
4. Learn the product’s domain language and behavior boundary.
5. Decide whether the report is one issue or multiple issues.
6. File GitHub issue(s) in user-centered language.

That order matters. If you jump into root-cause guessing too early, the issue quality often gets worse.

How much clarification is enough

One of the best parts of qa is that it prevents over-interviewing. The skill explicitly pushes for light clarification only. In practice, stop once you know:

• expected vs actual behavior
• basic reproduction path
• stability of the problem

If the report is already clear, file it. Too many questions make the reporting flow slower and usually do not improve the resulting issue.

Why background code exploration matters

The background exploration step is easy to underrate. It is not there to find a fix. It is there to:

• understand what the feature is supposed to do
• pick the right product terms
• avoid writing an issue that misunderstands the feature boundary

This is where qa for Issue Tracking becomes more valuable than a generic issue writer. The issue can sound like it belongs in the repository, not like it came from an outsider guessing at the product.

What not to include in the final issue

The skill is opinionated here: the issue should not expose internal implementation details like:

• specific file paths
• line numbers
• speculative root causes
• private architecture assumptions

That makes the issue more durable. Engineers can investigate internals later; the issue should preserve the user-facing problem clearly first.

How qa handles one complaint with multiple problems

A common real-world case is a user describing a “single bug” that actually contains separate failures. qa is designed to assess scope before filing. If the symptoms have different reproduction paths, user impacts, or behavior boundaries, split them into separate issues.

This matters because combined issues are harder to triage, harder to assign, and harder to close cleanly.

Best file to read before customizing qa

Start with SKILL.md. In this repo, that file contains the real operating logic for the qa skill: clarification limits, background exploration goals, and issue-writing boundaries. There are no supporting rules or helper resources in the folder, so most of your decision should come from that single file.

Practical prompt pattern for higher-quality qa usage

Use a prompt shape like this:

• “Use the qa skill. I’m reporting a bug in [feature]. Expected: [X]. Actual: [Y]. Repro steps: [1, 2, 3]. Frequency: [always/sometimes]. If this sounds like multiple issues, split them before filing.”

This prompt works well because it matches the skill’s actual decision points instead of asking for a vague “bug report.”

qa skill FAQ

Is qa only for formal testers?

No. The qa skill is beginner-friendly on the reporting side because it assumes the user may only know symptoms. It is more about structured issue capture than formal QA methodology.

Is qa good for issue filing on GitHub?

Yes. This is the clearest use case. qa for Issue Tracking is where the skill has the most obvious value because it turns conversational reports into issues that are easier to triage and less tied to shaky technical guesses.

How is qa different from telling an AI to write a GitHub issue?

Plain prompting can produce a decent ticket, but qa adds guardrails that improve repeatability: minimal clarifying questions, codebase context gathering, domain-language alignment, and explicit scope splitting. Those rules are what make the qa skill worth installing.

When is qa a poor fit?

Skip qa when:

• you already have a complete, high-quality issue written
• you need deep debugging, not issue capture
• the problem is a feature request rather than a bug report
• your workflow requires implementation-level incident analysis in the initial ticket

In those cases, qa may feel too narrow.

Does qa require deep repository knowledge from the reporter?

No. That is one reason to adopt it. The reporter can stay focused on user-visible behavior while the agent explores the codebase for vocabulary and context in the background.

Will qa find the fix?

Not necessarily, and that is not the goal. The skill is optimized for producing durable issues, not solving them. If you expect diagnosis or patch suggestions, pair qa with a separate debugging workflow.

How to Improve qa skill

Give qa sharper symptom descriptions

The fastest way to improve qa results is to provide cleaner symptom statements. Good inputs usually include:

• trigger
• expected behavior
• actual behavior
• frequency
• user impact

For example:

• “On the billing page, changing plan tiers updates the price only after a refresh. I expected the price to update immediately. This happens every time.”

That is much stronger than “pricing seems wrong.”

Include behavior boundaries, not root-cause guesses

Better:

• “Search results disappear after applying a filter and then removing it.”

Worse:

• “The cache invalidation logic is broken.”

The qa skill writes better issues when you describe the observable boundary. Root-cause guesses often mislead the background exploration step and can produce brittle issue wording.

Improve qa output by separating distinct symptoms early

If the user reports:

• “The modal flickers, the submit button disables forever, and the success toast never appears”

ask whether those are one flow failure or three separate problems. Even a quick scope check can dramatically improve the final issue set. This is one of the highest-leverage ways to improve qa usage.

Keep clarifying questions short and targeted

A common failure mode is turning the qa skill into a long interview. Stick to the skill’s intended pattern:

• expected vs actual
• reproduction
• consistency

If you ask more than that, the issue often becomes slower to produce without becoming more actionable.

Use the codebase exploration step to learn terminology

When qa outputs weak issues, the problem is often language mismatch. The user says one thing, but the product calls it something else. Even brief exploration of the relevant area can fix this by revealing:

• feature names
• user-facing concepts
• intended behavior boundaries

That produces issues engineers can route faster.

Do not let qa leak implementation detail into the ticket

Another common failure mode is writing issues that sound like code review notes. Keep the final issue centered on:

• user-visible behavior
• reproduction
• impact
• acceptance boundary

Avoid file references and internal speculation unless your team explicitly wants that in a separate engineering note.

Iterate after the first issue draft

If the first qa output is too vague, do not restart from zero. Improve it by asking for one focused revision:

• tighten repro steps
• split into multiple issues
• rewrite using product terminology
• remove internal assumptions
• add a clearer expected/actual contrast

Small targeted revisions usually work better than a full rewrite prompt.

Standardize your qa input format across the team

If multiple people use qa, create a lightweight reporting pattern such as:

• feature
• expected
• actual
• steps
• frequency
• impact

You do not need a rigid template, but consistent input structure makes qa install more valuable at team scale because issue quality becomes more predictable.

Know when to hand off from qa to another workflow

Once the issue is filed, stop using qa for diagnosis. Hand off to debugging, reproduction, or implementation workflows. Teams get better results when they let qa own issue capture and avoid stretching it into tasks it was not designed to do.