> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qawolf.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom skills
> Write your team's conventions into SKILL.md files so QA Wolf's agent applies them in every session.
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](/qawolf-mcp).
## Write a skill
A skill is a Markdown file with frontmatter that names and describes it, and a body holding the knowledge.
```markdown theme={null}
---
name: acme-conventions
description: How to sign in to Acme and what our domain terms mean — SSO-only login, seeded test users, and the difference between quotes, members, and subscribers. Read this before creating or editing any Acme flow, or when a sign-in step fails with "invalid credentials."
---
# Logging in
Always sign in through the SSO tile. The email and password form is
deprecated and fails for most test users.
# Domain terms
- A "quote" is a rate quote, not a chat message.
- "Members" and "subscribers" are the same object in the UI.
# Conventions
- Structure every flow header around Arrange, Act, Assert.
- Prefer unique generated values over hardcoded ones for new records.
```
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:
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."
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."
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.
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:
| Description | What the agent can do with it |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `Notes about our app` | Nothing — no subject, no trigger, no terms to match against |
| `Domain terms and test conventions for the Acme app` | Knows the topic, but not when it matters or which terms are inside |
| `How to sign in to Acme and what our domain terms mean — SSO-only login, seeded test users, and the difference between quotes, members, and subscribers. Read this before creating or editing any Acme flow, or when a sign-in step fails with "invalid credentials." Not for billing flows, which have their own skill.` | Reads it before writing any Acme flow, uses SSO instead of the dead password form, and targets the right objects |
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 AAA](/test-automation#structure-the-flow-header-around-arrange-act-assert)
* 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.
## Where skills live
A `SKILL.md` file works anywhere in your workspace. Giving each one its own folder keeps them easy to find:
```text theme={null}
your-workspace/
├── skills/
│ ├── acme-conventions/
│ │ └── SKILL.md
│ └── payments-testing/
│ └── SKILL.md
├── src/
│ ├── flows/
│ └── pages/
├── package.json
└── tsconfig.json
```
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.
## 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.
### My skill isn't showing up at all.
Check the frontmatter. A file missing `name` or `description`, or with malformed frontmatter, is skipped silently rather than reported. 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.