Guide · Agent skill
How to use the QA Test Plan Builder agent skill (qa-plan)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The qa-plan skill is an agent skill for Claude Code that writes a QA test plan for a sprint, a feature or a single story before implementation starts. It reads the story files and the design documents they reference, classifies each story as Logic, Integration, Visual/Feel or UI, and produces a markdown plan. After this guide you will know what the skill does, how to install it, how to ask for a plan in plain language and what it needs from your project.
QA Test Plan BuilderDonchitos/Claude-Code-Game-Studios · MIT Download the skill Quick start
- 1Get the skill folder. Download the ZIP from this page and unzip it so you have a qa-plan folder containing SKILL.md.
- 2Place it in the skills directory. Move the folder into ~/.claude/skills/ for personal use, or into your project's .claude/skills/ folder for a shared install.
- 3Check your project layout. Confirm you have production/sprints/, production/epics/ and the .claude/hooks and .claude/docs files the skill needs.
- 4Open Claude Code in the project. Start Claude Code from the repository root so the skill can find the story and configuration files.
- 5Run the skill with a scope. Invoke /qa-plan with sprint, feature: [system-name] or story: [path], or run it with no argument and choose from the prompt.
- 6Read the generated plan. Open production/qa/qa-plan-[sprint-slug]-[date].md and review the automated, manual and smoke sections.
What is an agent skill and what does qa-plan make the agent do?
An agent skill is a folder containing a SKILL.md file with instructions the agent loads when it is relevant or when you call it. The qa-plan skill tells the agent how to produce a QA plan from your existing story files.
When invoked, the agent reads the story files for the scope you give it, along with the design documents those stories reference. It classifies each story by test type: Logic, Integration, Visual/Feel or UI. It then writes a markdown QA plan that says what should be automated, what needs manual checking, the smoke-test scope and when to involve a playtester.
The plan is written to production/qa/qa-plan-[sprint-slug]-[date].md. The skill is meant to run before a sprint starts so testing work is known upfront.
- Reads story files for a sprint, a feature (system name) or a single story path
- Uses the Type field on a story when one is declared; infers it from acceptance criteria when it is missing and flags the gap
- Writes a plan covering automated tests, manual cases, smoke scope and playtester involvement
- Does not run any tests
Install the qa-plan skill
Download the ZIP from this page and unzip it. The skill is a folder named qa-plan containing SKILL.md. Put that folder in one of two places:
Personal install: unzip into ~/.claude/skills/ so the skill is available across your projects.
Project install: unzip into the .claude/skills/ folder of a specific project, so it is available only in that repository. Commit it if your team should share it.
In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.
- Personal location: ~/.claude/skills/qa-plan/
- Project location: <your-project>/.claude/skills/qa-plan/
- Claude apps: Settings → Capabilities → Skills → upload
Know the requirements before you run it
The skill is written for Claude Code with these tools available to it: Read, Glob, Grep, Write, Edit and AskUserQuestion. It also uses a bash step to resolve project configuration, so it needs a bash shell.
The skill expects the repository's supporting files: .claude/hooks/yaml-helper.sh, the configuration documents under .claude/docs/, and a production/ folder layout with sprint and epic story files. If those are missing, the skill cannot find stories.
- Claude Code with the skill's allowed tools (Read, Glob, Grep, Write, Edit, AskUserQuestion)
- Repository files: .claude/hooks/yaml-helper.sh and .claude/docs/ configuration files
- A production/ folder layout (production/sprints/ and production/epics/)
- A bash shell for the configuration-resolution step
Trigger the skill with a natural request
The skill accepts a scope argument with three forms: sprint, feature: [system-name] or story: [path]. If you call it with no argument, the agent asks you what scope to use, with the options Current sprint, Specific feature, Specific story or Full epic.
You can also ask in plain language, such as asking for a QA plan for the current sprint or for the combat system stories. Naming the scope explicitly avoids a question back to you.
- sprint: uses the most recent file in production/sprints/
- feature: [system-name]: matches stories under production/epics/ whose path or title contains the name
- story: [path]: loads one story file
/qa-plan sprintReview the output and what it flags
After resolving scope the agent reports how many stories it is planning for. A missing story file is marked MISSING and the rest of the plan continues.
If the scope contains zero stories, the skill stops and reports NOT ASSESSED with the reason, instead of producing an empty plan. Stories with no Type field get an inferred type and are flagged so the lead can declare it before implementation.
Check the plan's smoke-test scope and playtester recommendations before the sprint starts, and treat the plan as a document to act on rather than a record of tests already run.
- Look for MISSING and NOT ASSESSED notices in the report
- Check any inferred story types and declare them in the story headers
- Use the smoke scope as the minimum check after each build
What people use it for
- Planning test work for the current sprint before developers start implementation
- Producing a QA plan for one game system, such as combat or inventory, from its epic stories
- Checking a single story's acceptance criteria and deciding which parts need automated tests and which need manual checks
- Deciding when a playtester should look at a feature with visual or feel requirements
Frequently asked questions
Is the qa-plan skill free to use?
The source gives the licence as MIT for the repository that contains the skill. It does not state any pricing, so check the repository for the licence terms before you use or redistribute it.
What do I need to install qa-plan?
You need Claude Code with the skill's allowed tools, the repository's .claude/hooks/yaml-helper.sh and .claude/docs/ files, a production/ folder layout and a bash shell. The skill is installed by placing the qa-plan folder in ~/.claude/skills/ or a project's .claude/skills/ folder.
Why does qa-plan say NOT ASSESSED?
It means the scope you gave contains zero stories, so there was nothing to plan. The report names the scope searched and the empty path, and suggests a next step such as running /sprint-plan new or /create-stories.
Does qa-plan run my tests?
No. The skill plans tests and writes a document describing what to automate, what to check manually, the smoke scope and when to involve a playtester. It does not execute a test suite.
Can I use qa-plan for non-game software?
The source says it is not a good match for non-game software, because the Visual/Feel and playtester categories do not apply and the output may fit poorly. It is designed for projects that use the Claude Code Game Studios production/ structure.
Does qa-plan use the network or run scripts?
The source says the skill runs scripts and does not use the network. Its configuration step runs a bash script, so you should review the script in .claude/hooks/ before installing.
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-plan if you work in a Claude Code Game Studios style repository and want a consistent, acceptance-criteria-based test plan written before a sprint starts. Pick something else if your project lacks the production/ story structure, if it is not a game, or if you need the skill to execute tests rather than plan them.
Download the skill