Skill Masterclass for QA: from prompt to reusable skill

A prompt is an instruction you type; the model answers. It works, and then it evaporates.

Ask yourself the question from the masterclass: what prompt did you use a week ago? Almost nobody can answer. And even if the history is still there, running it again rarely gives the same output, because the model predicts rather than replays.

So a good prompt gets you a good answer and zero leverage. The instruction dies with the chat window. Nothing is versioned. Nothing is reviewable. A teammate who needs the same output tomorrow starts from nothing.

There is a second reason, and it is the one that shows up in code review. A tester who generates a change with an agent and cannot explain how it was produced has no answer when asked. A skill file is that answer: it is the written, reviewable record of how the work gets done.

Skills are markdown files, and the reason is almost accidental.

Every repository already had a README.md. Agents learned to read it first to understand a project, which quietly made markdown the entry point format for AI agents. Three properties kept it there:

• Agents parse it reliably. Headings and lists give structure without a schema.
• It is lightweight. Fewer tokens than the equivalent document format, and skills cost tokens every time they load.
• Humans can read it. The same file is documentation and instruction.

A single file is a skill. A folder is also a skill. Neither is wrong.

Asked which is better, the answer from class was deliberately unhelpful and correct: it depends on the job, the same way the better pizza depends on who is eating. Start with one file. Grow into a folder when the file starts wanting attachments.

Each coding agent reads skills from its own dot-folder in your project.

Cursor, Windsurf, Kiro, OpenCode, Codex, Gemini CLI and the rest follow the same pattern in their own dot-folder. Rather than trusting a list that ages, use the trick from class: ask the agent itself where it loads skills from. It knows, it is right for the version you have installed, and it takes one question.

If you do not know the objective, you will build something nobody wants.

The selection rule is one sentence: find a job you do manually, more than once. That is the entire qualification. For a tester the list is long and already familiar, because it is the software testing lifecycle:

• Requirement analysis from a ticket
• Test planning
• Test design and case development
• Execution, defect management, closure

Around that sit the recurring specialities: root cause analysis, bug triage, flaky test hunting, accessibility passes, API contract checks. Every one of them is a candidate. The masterclass target was the second phase, test planning, because it is repetitive, template-driven, and every company's template is different.

The published skill is real and readable. This is its shape, and why each part exists.

The file opens with frontmatter. description is the most load-bearing line in the whole skill, because it is what the agent matches against when deciding whether this skill applies to what you just asked.

---
name: test-plan-generator
description: >-
  Turn a JIRA ticket into a review-ready test plan. Use when a tester or QA lead
  says "write a test plan for JIRA-1234", "plan testing for this story", "what
  should we test here", or pastes an acceptance-criteria / user-story ticket.
  Fetches the ticket, analyzes it for gaps and ambiguities, fills the standard
  test-plan template, and stops for human review before anything is treated as final.
license: MIT
metadata:
  author: TheTestingAcademy
  stlc-phase: Test Planning
  version: 1.0.0
---

Notice the description is written as trigger phrases, not as a summary. "Write a test plan for JIRA-1234" is what a human actually types, so that is what belongs there. A description that says "generates test plans" gives the agent nothing to match on.

Then the body, in the order the agent will follow:

1. When to use. The conditions in plain English. A Jira key was given, or someone asked what the risks and edge cases are.
2. Workflow, numbered. Fetch the ticket, analyze it against the checklist, draft the plan from the template, stop for review. Numbered steps, because the agent follows order.
3. Output shape. The literal section list the plan must have. Without it, every run produces a differently organised document, which defeats the point of standardising.
4. Guardrails. The things it must never do.
5. References. Pointers to the other files, so the agent knows the template and checklist exist and when to open them.

The supporting files carry the parts that are specific to you. The checklist is the one worth copying first, because it encodes what an experienced tester notices and a generic model does not:

## Non-functional (often missing)
- [ ] Performance / load expectations
- [ ] Security / authorization (which roles can/can't)
- [ ] Accessibility (a11y) expectations
- [ ] Internationalization / localization
- [ ] Audit / logging / observability

## Clarity
- [ ] No ambiguous wording ("should", "etc.", "handle gracefully")
- [ ] Terms defined consistently
- [ ] Mockups / designs linked and match the text

Each row is scored present, ambiguous, or missing, and every ambiguous or missing row becomes a question for the ticket author. That section of the output was called the most valuable part of the whole plan, and the reasoning is hard to argue with: a tester's leverage is asking the question before the bug ships.

The agent cannot read your ticket tracker unless you tell it how. There are two connectors, and the skill should name both in preference order.

The skill states the preference in one instruction, so the agent picks the right one at runtime:

- If a JIRA key is given (e.g. `VOC-1234`), fetch it. Prefer an available JIRA MCP
  tool. If none, run `scripts/fetch_jira.sh VOC-1234` (needs `JIRA_BASE_URL`,
  `JIRA_EMAIL`, `JIRA_TOKEN` env vars). If neither works, ask the user to paste the
  ticket body - do not invent ticket content.

That last clause is the important one. Given no ticket, a model will happily write a plausible one. Telling it to ask instead is the difference between a draft and a fabrication.

The script itself is small on purpose, curl and jq, no SDK:

curl -sS -u "${JIRA_EMAIL}:${JIRA_TOKEN}" \
  -H "Accept: application/json" \
  "${JIRA_BASE_URL}/rest/api/3/issue/${KEY}?fields=summary,description,..." \
| jq '{ key: .key, summary: .fields.summary }'

Credentials go in a .env file that stays on your machine. It is referenced by the skill and read by the agent, and it is never committed. Your teammate runs the same skill with their own token, which is exactly why the token does not belong in the skill.

This is the section that separates a senior QA's skill from a junior one.

The skill is instructed to produce a draft and then stop. Not a finished artifact, not a silently completed document: a draft, with its assumptions declared and its open questions listed, waiting for a person to approve it.

### 4. STOP for human review (mandatory)
End with a **Human Review Gate**:

- Summarize what you assumed and what you could not confirm.
- List the open questions from step 2 that block sign-off.
- Ask the tester to confirm/edit before the plan is considered approved.
- Do **not** proceed to write test cases or automation until a human approves.

Two rules make the gate real rather than decorative:

• Never mark the plan final. A human owns sign-off, so the document stays labelled DRAFT.
• A missing acceptance criterion is a finding, not a blank to fill. The model must not invent the criteria it wishes the ticket had.

The second rule is the anti-hallucination clause in practical clothing. It converts the model's biggest failure mode into the skill's most useful output.

Guardrails are the restrictions on what the skill may produce, and they are short.

• No credentials in the output. The skill reads your token to fetch a ticket; it must never print it into a test plan that gets shared.
• No personal data. Names, emails and anything identifying stay out of the generated document.
• No fabrication. Gaps get reported, not filled.
• Traceability. Every scenario maps back to an acceptance criterion or a gap, so a reviewer can check the reasoning rather than trust it.

These sit in their own section of the file so a reviewer can read the constraints without reading the workflow.

Ask in plain language. The description does the matching.

1. Check the connector. Ask the agent whether the Jira MCP is connected. If it is, the script never runs; if it is not, the fallback does.
2. Ask for the plan. "Create a test plan for VOC-49." Point at the skill folder if you want to be explicit, by dragging it in or tagging the file, but a well-written description usually makes that unnecessary.
3. Read the gaps first. The interesting output is the questions section, not the scenario table.
4. Approve or edit. The agent waits at the gate. Answering its questions is the part that turns the draft into a plan.

In the live run the agent picked the MCP route, read the ticket, filled the template, produced the draft, listed its open questions, and stopped. The skill's job is that shape, repeated identically next week and on a colleague's machine.

The cautionary tale from the masterclass, and the reason it is worth repeating.

A development team shipped a test designer skill for QA to use. The output was poor. Reading the actual instruction file explained why: it never mentioned boundary value analysis, equivalence partitioning, state transition or pairwise techniques. The person who wrote it was a senior architect who did not know how test cases are designed, and the model filled the gap with something plausible.

The same argument runs the other way, and it is the reason the masterclass exists. If skills encode expertise, then testers should be writing the testing skills, not inheriting them from whoever got there first.

Starting from a published skill is fine, and encouraged. The published suite is MIT licensed precisely so it can be taken, modified and used without credit. What is not fine is shipping it unread.

• A vague description. The agent matches on it. "Generates test plans" will not trigger; the phrases a human actually types will.
• PDFs in the skill folder. Convert to markdown. The agent converts anyway, and you pay tokens for the privilege.
• Committing .env. The skill is shared, the credentials are not.
• A skill with no stop. Without a review gate, an agent that misreads a ticket writes test cases and automation on top of the mistake.
• Filling gaps instead of reporting them. If a missing acceptance criterion becomes an invented one, the skill has hidden the very problem it was built to surface.
• One giant skill. One repeated job per skill. A new job is a new folder.

The obvious next question is how you know a skill is any good, which is a testing problem and therefore squarely a tester's problem. Skill benchmarking and evaluation are the subject of part two of the masterclass.