Skip to main content
Prompts teach the agent about your app one session at a time. A custom skill makes that knowledge permanent. You write a SKILL.md file into your workspace describing a convention — how sign-in works, what your domain terms mean, how your team writes flows — and the agent reads it whenever it takes on work that convention covers. Skills are additive. The agent keeps doing what it normally does and applies your conventions on top, preferring yours wherever they differ from its defaults. The payoff is tests that match how your app actually behaves — the right sign-in path, the right terms for the right elements, your team’s conventions — without anyone re-explaining it each time.
These are skills stored in your QA Wolf workspace, for QA Wolf’s own agent. To connect an external coding agent like Claude Code or Codex, see the QA Wolf MCP guide.

Write a skill

A skill is a Markdown file with frontmatter that names and describes it, and a body holding the knowledge.
Give every skill a name and a description. Both are required, and each name should be unique — two skills sharing a name leaves only one of them active.

Describe when your skill applies

A skill only improves a test if the agent has it in hand at the moment it’s writing that test. The description is what decides that — the agent matches the task against it to choose which skills to read. Four moves make one specific enough to land:
1

Say what the skill covers

Open with the subject in plain terms — “How to sign in to Acme,” “Knowledge base for our billing API,” “Checklist for reviewing a checkout flow.”
2

Name the specifics

List the actual topics inside, using the words your team uses. “SSO-only login, seeded test users, and the difference between quotes, members, and subscribers” gives the agent far more to match against than “domain terms.”
3

Say when to read it

Name the work it should shape: “Read this before creating or editing any Acme flow.” Include the symptoms, too — an error message like invalid credentials or mail is not defined is often how the agent first meets the problem your skill solves.
4

Say when not to, if something's nearby

When another skill covers adjacent ground, draw the line: “Not for billing flows, which have their own skill.” This keeps each skill from being pulled into work it doesn’t cover.
Descriptions get sharper as they get more specific: A long description is fine. It’s an index entry the agent scans, not prose anyone reads start to finish.

What belongs in the body

Anything you would otherwise repeat across many prompts:
  • Domain vocabulary and what each term maps to in the UI
  • Environment quirks, such as which login method works and which test users are seeded
  • Team conventions, such as structuring flow headers around Arrange-Act-Assert (AAA)
  • Links to deeper documentation the agent should fetch when it becomes relevant
Keep each skill to one topic. The agent opens the whole file once it selects a skill, so a file covering several unrelated subjects spends context on the parts that don’t apply. Knowledge that matters to a single flow belongs in that flow’s prompt or header instead.

Point the agent at a skill

To make sure the agent uses a particular skill, type / in the chat and pick it from the list, or type / followed by the skill’s name. The agent reads that skill before it works on your message.

Where skills live

A SKILL.md file works anywhere in your workspace. Giving each one its own folder keeps them easy to find:
Skills take effect as soon as you save — there’s no restart or reindex step. They’re ordinary files in your workspace, so they’re versioned alongside your flows and travel with your branches.

Add a skill through Git

1

Clone the workspace

Clone your workspace with Git and select the branch that your environment or investigation uses.
2

Create the skill file

Create skills/checkout-investigation/SKILL.md in your clone. Use the investigation example below, or write your own skill with a unique name and a description.
3

Commit and push the file

Review and publish the skill:
4

Verify the skill in QA Wolf

Wait for the pushed file to appear on the same branch in QA Wolf. Ask the agent to list the workspace skills and confirm your skill’s name.
Saving a file in your local clone does not update QA Wolf until you push it. Skills apply on branches that contain the file. Merge or copy the skill into other branches where you need it.

Guide investigations with a skill

A skill can describe expected behavior, environment setup, and bug report requirements for investigations. Include investigation tasks and failure symptoms in its description so the agent can select it. Example:
Replace the example’s app details with verified behavior from your own application. Keep credentials in environment variables. Put context for one investigation in its chat; put reusable conventions in a skill. Example prompt after publishing the skill:
The agent does not automatically save every investigation detail as a skill. If you want it to save reusable guidance, explicitly ask it to create or update a SKILL.md file.

FAQ

The agent isn’t following a convention I documented.

The agent names the skill it read as it works, so check whether yours came up. If it didn’t, revise the description: name the work it should shape and the specific terms your team uses. Selection happens on the description alone, so that’s where it’s decided. To use the skill for one message regardless, point the agent at it.

My skill isn’t showing up at all.

Check the frontmatter. A skill needs a non-empty name and a description. Files with missing or invalid frontmatter do not enter the skill index. Also confirm no other skill shares the same name.

How long should a skill be?

Long enough to state the convention completely, short enough to stay accurate as your app changes. Splitting by topic beats one large file, since the agent loads everything in a skill it selects.

Do skills apply to flows my team writes by hand?

No. Skills shape what the agent does. Code you write yourself is unaffected — though a skill is a reasonable place to document conventions your team follows too.
Last modified on October 29, 2026