Guide · Agent skill
How to use the QA Acceptance agent skill: plans and pass/fail
Updated · written with AI from the project's own documentation and checked against our catalogue data
The qa-acceptance skill is a bundled agent skill from the paperclipai/paperclip project, licensed MIT, that tells an AI agent how to write a manual validation plan for a user-facing feature change. Its output is written so a reviewer can run the criteria against the running app and decide pass or fail without asking the author. This guide explains what the skill does, how to install it, how to trigger it, and where it fits and does not fit.
QA Acceptance Planspaperclipai/paperclip · MIT Download the skill Quick start
- 1Download the ZIP. Get the qa-acceptance skill as a ZIP from this page.
- 2Unzip into a skills folder. Place the skill folder in ~/.claude/skills/ for personal use, or in .claude/skills/ inside your project.
- 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.
- 4Describe the feature change. Ask the agent in plain language for acceptance criteria or a validation plan for a specific change.
- 5Review the criteria. Check that each criterion is a single Given/When/Then statement and that the eight required areas are covered or marked N/A with a reason.
- 6Run and collect evidence. Run each criterion in the running app and record a screenshot, console or network output, log snippet, or timing for each pass.
- 7Report Pass, Fail or Blocked. Hand back results in the three required sections, with reproductions for failures and reasons for blocked items.
What is an agent skill, and what does this one make the agent do?
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent loads when a task matches the skill's description. The qa-acceptance skill covers feature-level QA: it produces acceptance criteria and a manual validation plan for a change, along with explicit pass/fail evidence requirements.
Each criterion is a single Given/When/Then statement. The skill says the plan must cover eight areas: golden path, empty and minimum states, boundary inputs, error states, concurrency and ordering, performance envelope, backward compatibility, and telemetry and audit. Any section that does not apply must be marked 'N/A' with a reason rather than left out.
The skill also requires evidence for each pass: screenshots or short clips for UI behaviour, copied console or network output for API behaviour, log snippets or activity rows for telemetry, and timing measurements for performance criteria. Results are reported as Pass, Fail, or Blocked.
How do you install the qa-acceptance skill?
Download the skill as a ZIP from the skill's page in this directory. Then choose one of the options below.
For a personal install, unzip the file into ~/.claude/skills/ so the skill folder sits there with its SKILL.md. For a project-only install, unzip it into the .claude/skills/ folder inside your project.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal: unzip into ~/.claude/skills/
- Project only: unzip into .claude/skills/ in your repository
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
How do you trigger the skill with a natural request?
You do not need a special command. The agent reads the skill's description and uses it when your request matches the kind of work it covers. Ask for what you need in plain language, and name the feature and the change.
The skill's own 'when to use' list gives good cues: a feature change heading to QA, a reviewer checking a pull request that touches user-visible behaviour, a regression check after an incident, or a pre-cut smoke pass for a release candidate.
- Write acceptance criteria and a manual validation plan for the CSV export change in this PR.
- Create a QA validation plan for the new invite flow, with pass/fail evidence for each criterion.
- Build a pre-release smoke checklist for the release candidate that includes the billing page changes.
What does a good output look like?
The skill sets a fixed format for each criterion. Here is the example it gives for a CSV export with no rows:
Every criterion should be one statement with one action and one observable result. If a request would produce a criterion with several whens or thens, the skill tells the agent to split it.
- **Given** a CSV export with 0 rows, **when** the user clicks Export, **then** the file downloads with only the header row and the UI shows "Exported 0 rows".What should you do with the results?
The skill ends with a handoff to the author in three parts: Pass, with one-line evidence summaries; Fail, with the exact reproduction; and Blocked, with the reason each criterion could not run. The skill says a failing criterion blocks acceptance unless the owner waives it with a tracked follow-up issue, and that 'known issue' with no linked follow-up is not a waiver.
If a new criterion is added during a pass, the skill says to restart the pass, because partial coverage can hide regressions.
- Mark must-pass criteria separately from nice-to-have ones, since the skill warns against long unprioritised checklists.
- Keep criteria observable; do not check selectors or query plans.
What do you need, and what are the safety notes?
The skill lists no required tools or prerequisites. It does not run scripts and does not use the network, according to its listing. It is a set of written instructions the agent follows, so the main thing to review is the plan it produces before a reviewer relies on it.
Because the skill itself does not run anything, any commands the agent suggests while testing your app are still your responsibility to check. The skill's own guidance is to observe behaviour in the running app rather than inspect implementation details.
- Required tools: none listed
- Runs scripts: no
- Uses network: no
What people use it for
- Writing a Given/When/Then validation plan for a user-facing pull request before a reviewer signs off.
- Creating a pre-release smoke checklist for a release candidate, with must-pass items marked.
- Producing a regression check after an incident, before the fix is reopened or closed.
- Giving a QA engineer a structured set of edge cases for empty inputs, maximum-length text and permission errors.
Frequently asked questions
Is the qa-acceptance skill free to use?
The skill is listed under the MIT licence in the paperclipai/paperclip repository. This page does not state pricing for any other product, so check the licence file in the source repository for the terms.
What do I need to install qa-acceptance?
The skill lists no required tools. You download the ZIP, unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
Does qa-acceptance write automated tests?
No. The skill focuses on manual, feature-level validation and says that tests are how you check acceptance criteria. It also says not to use it for API contract testing, which needs contract testing instead.
When should I not use this skill?
Skip it for changes that are only unit-tested, such as internal refactors or renames. The skill itself says acceptance criteria are unnecessary churn for those changes.
Why does the skill require screenshots and timings?
The skill says a reviewer cannot audit a 'passed' result without evidence, and that 'looks good to me' is not a pass. Each pass needs a screenshot or clip, console or network output, a log snippet, or a timing, depending on the criterion.
What if a criterion fails but we want to ship anyway?
The skill says a failing criterion blocks acceptance unless the owner explicitly waives it with a tracked follow-up issue. A known issue without a linked follow-up does not count as a waiver.
Who is this skill best for?
It suits QA engineers who need a written, reviewable test plan, engineers preparing a change for manual verification, and product or release owners who want a consistent pre-release smoke checklist.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use qa-acceptance if you need a written, reviewable manual test plan for a user-facing change, with a clear pass/fail/blocked report that a reviewer can audit. Pick something else if your change is only unit-tested, or if you need automated test code or API contract tests, since the skill deliberately does not write those.
Download the skill