A QA skill for Claude Code

Two pieces. A connection, so Claude Code can see the testing board, and a skill file, so it works the board the same way every time instead of improvising.

1. Connect the runbook

Sign in to qarunbook, open Connect your AI, copy your token, and run this. The token is per person, so anything Claude records carries your name.

claude mcp add qa-runbook --transport http https://qarunbook.com/api/mcp \
  --header "Authorization: Bearer qarb_your_token_here"

Check it took with /mcp inside Claude Code. You should see fourteen tools — five that read, five that add, four that change something.

2. Add the skill

Save this as .claude/skills/qa-triage/SKILL.md in your repo. The description line is what decides whether Claude reaches for it, so it names the phrases people actually type.

---
name: qa-triage
description: Work the QA runbook - read what testers found, fix it, send it back for retest. Use when asked to triage QA, clear the testing backlog, fix reported issues, or check whether a release is safe.
---

# Working the runbook

The runbook is the source of truth for what has been tested. Read it before
you claim anything about a release.

## Start here, every time

1. `list_apps` to get the app name.
2. `list_issues` for what testers actually wrote. Their words matter more
   than the check title - the title says what was meant to happen, the issue
   says what did.
3. `list_checks` with filter "failing" for the shape of the damage.

## Fixing

Fix one issue at a time, in the repo, and only mark it fixed once the change
is committed. Call `resolve_issue` with a short note saying what changed.

The check does NOT go back to passing. It goes to "needs retest", because a
human has to confirm it on the platform it broke on. Never call
`set_result` to pass a check you fixed yourself - that is marking your own
homework, and it is how bugs ship.

## Reporting

When asked whether a release is safe, call `progress` and answer with the
numbers: what passes, what fails, what nobody has looked at. Untested is not
the same as working, and say so.

## Raising

If you find a bug while working - in your own testing, or in code review -
raise it with `add_issue` against the check it belongs to, in plain words a
tester would recognise. If no check covers it, `add_check` first.

The rules in it exist because of how assistants fail at this job. Left alone, a model will fix something, mark the check passed, and report the release clean. The skill forbids exactly that: a fix resolves the issue and the check returns for a retest, which is what the runbook does for humans too.

What it looks like in use

“Triage QA for Smart Invites” becomes: read the nine open issues, group them by which are in this repo, fix the four that are, resolve those four with a note each, and report the rest as needing someone else. Then progress, so the answer to “can we ship?” is a set of numbers rather than a feeling.

The prompts that work are plain:

• “What did testers find on Android since Friday?”
• “Clear the QA backlog for the ones that are in this codebase.”
• “Is this release safe? Use the runbook, not your judgement.”
• “Turn this markdown test plan into a runbook and tell me what it misses.”

Subagent, skill, or neither

A skill is the right shape here because the work is a procedure, not a specialism: read, fix, resolve, report. A subagent is worth it only when you want the triage to run in its own context so a long backlog does not crowd out the code you are working on — point it at the same tools and the same rules. And if you only ever ask one question, skip both and ask it directly; the MCP connection alone is enough.

The honest limit

None of this tests anything. It reads results humans produced and writes back what was fixed. The confirming pass is still a person on a real device, which is the point: the runbook is for the manual testing that decides releases, and the skill just stops the loop leaking between the two.