Reusable instructions and specialist agents help AI follow the same QA conventions across tasks. Store stable project rules once, load detailed guidance only when relevant and give each agent a narrow responsibility with limited tools.
On this practical guide
Choose the right building block
| Building block | Use it for | Example |
|---|---|---|
| Prompt | One specific task. | Review this failed checkout test. |
| Repository instructions | Rules that apply to most work in a project. | Commands, folder structure and coding conventions. |
| Path instructions | Rules for one area or file type. | Playwright standards for tests/e2e/**. |
| Skill | Reusable domain knowledge, workflow and supporting resources loaded when relevant. | How to design API contract tests for this organisation. |
| Custom agent | A specialist role with a defined process and tool set. | Test planner, automation reviewer or CI investigator. |
| Subagent | A bounded delegated task that returns a result to a coordinating agent. | Analyse accessibility while another agent reviews API risks. |
Keep repository instructions useful
Instructions should contain stable facts the agent cannot safely infer. Do not turn the file into a full project wiki.
# QA repository instructions
## Project
- TypeScript and Playwright Test
- Tests live in tests/e2e
- Shared fixtures live in tests/fixtures
## Commands
- Install: npm ci
- Lint: npm run lint
- Type check: npm run typecheck
- Tests: npx playwright test
## Test conventions
- Prefer role, label and test ID locators
- Use web-first assertions
- Never add fixed sleeps
- Reuse fixtures and test-data builders
- Keep tests independent and safe for parallel execution
- Store no secrets or personal data in the repository
## Definition of done
- Relevant tests pass
- Lint and type checks pass
- New behaviour has observable assertions
- Assumptions and remaining risks are reported
Good instruction rules
- Use exact commands that work in the repository.
- Explain important architecture and test boundaries.
- Include approved examples or link to canonical files.
- State forbidden actions and protected areas clearly.
- Remove outdated or conflicting rules.
- Keep tool-specific paths aligned with current product documentation.
Design skills with progressive detail
A skill should advertise when it applies, then provide a focused workflow. Large examples, references and scripts can stay in separate files so they are loaded only when needed.
playwright-qa-skill/
├── SKILL.md
├── references/
│ ├── locator-policy.md
│ └── test-data-rules.md
├── examples/
│ └── approved-checkout.spec.ts
└── scripts/
└── validate-tests.sh
# Playwright QA Skill
Use this skill when creating or reviewing Playwright tests.
## Workflow
1. Read the story and identify product risks.
2. Select the lowest sensible test level.
3. Reuse approved fixtures and data builders.
4. Prefer accessible, user-facing locators.
5. Add observable web-first assertions.
6. Run the smallest relevant test set.
7. Run lint and type checks.
8. Report assumptions, evidence and remaining risks.
## Required references
- Read references/locator-policy.md for UI tests.
- Read references/test-data-rules.md when creating data.
## Guardrails
- Do not use waitForTimeout or hard-coded credentials.
- Do not change application code unless explicitly requested.
- Do not hide a product defect by weakening an assertion.
Create focused custom agents
A custom agent combines role instructions with an allowed tool set. Restrict tools explicitly: some platforms enable every available tool when the list is omitted.
---
name: QA Automation Reviewer
description: Reviews Playwright changes for reliability and coverage.
tools:
- read
- search
- execute
---
Review test changes only. Do not edit files.
Check:
1. Traceability to the requirement
2. Locator quality and actionability
3. Assertions and failure diagnostics
4. Isolation, data and cleanup
5. Fixed waits, retries and flaky patterns
6. Missing high-risk scenarios
Run only read-only inspection and approved test commands.
Return findings by severity with file references and concise fixes.
If no material issue exists, say so clearly.
A practical multi-agent QA system
| Agent | Input | Output | Suggested access |
|---|---|---|---|
| Requirement analyst | Story, designs and business rules. | Risks, questions and test conditions. | Read only. |
| Test planner | Confirmed risks and architecture. | Layered coverage plan. | Read and write plans. |
| Test generator | Approved plan, fixtures and conventions. | Small test change. | Read, edit and test command. |
| Execution agent | Test selection and environment rules. | Results and artefacts. | Execute tests only. |
| Failure investigator | Failed result, trace, logs and recent diff. | Evidence-based classification. | Read and diagnostic commands. |
| Coverage reviewer | Requirements, tests and reports. | Material gaps and duplicates. | Read only. |
Keep the hand-off explicit: each agent should return a defined artefact. Do not let several agents silently edit the same files or make the same external decision.
Example end-to-end flow
- The analyst reads the story and produces confirmed risks plus open questions.
- A person resolves important product questions.
- The planner maps each risk to unit, API, integration, UI or exploratory coverage.
- A person approves the plan and automation candidates.
- The generator writes one reviewable test change using project skills.
- The execution agent runs focused checks and saves evidence.
- The reviewer checks the diff, coverage and failure behaviour.
- A person approves the pull request through the normal CI/CD workflow.
Avoid context bloat
- Put universal rules in repository instructions.
- Put specialised workflows in skills loaded only when relevant.
- Reference canonical documents instead of copying them into every prompt.
- Give subagents only the files and tools required for their task.
- Return concise decisions and evidence, not full conversation histories.
- Start a fresh task when earlier exploration is no longer relevant.
Validate instructions and agents
| Test | What to verify |
|---|---|
| Happy path | Produces the expected artefact and follows conventions. |
| Missing context | Asks a useful question instead of inventing details. |
| Forbidden action | Refuses or pauses at the defined boundary. |
| Conflicting instructions | Uses documented precedence and surfaces the conflict. |
| Tool failure | Reports partial progress and does not claim success. |
| Product defect | Does not weaken the test merely to obtain a pass. |
| Prompt injection | Ignores hostile instructions in retrieved content. |
| Regression set | Stable benchmark tasks still produce acceptable results after updates. |
Maintenance checklist
- Keep instructions and agent definitions under version control.
- Assign an owner and review date.
- Update examples when frameworks or architecture change.
- Test changes against a small benchmark set.
- Track incorrect actions, rework and human overrides.
- Remove unused tools, permissions and duplicated guidance.
Useful links
- GitHub Copilot custom instructions ↗ — repository, path and agent instructions.
- Create GitHub Copilot custom agents ↗ — profiles, tools and repository setup.
- Custom agent configuration reference ↗ — current fields and tool controls.
- Claude Code subagents ↗ — specialist agent concepts.
- Playwright Test Agents ↗ — planner, generator and healer workflows.