OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add petrkindlmann/qa-skills --skill qa-project-bootstrap
Onboard a new QA engineer to an existing codebase, or audit an existing test architecture. Produces a 30-day ramp plan: codebase orientation, framework walkthrough, test architecture audit, mentorship pairing, and first-test guidance. Use when: "QA onboarding," "new tester," "ramp up," "test architecture audit," "first 30 days," "QA mentorship," "joining QA team." Not for: setting up QA on a brand-new project from scratch — use `qa-start`. Related: qa-start, qa-project-context, shift-left-testing, ai-qa-review.
npx skills add petrkindlmann/qa-skills --skill qa-project-bootstrap
Before starting: Check for .agents/qa-project-context.md in the project root. If it exists, it answers most discovery questions and provides the technical context for onboarding. If it does not, creating it is the first action item.
This skill serves three distinct jobs. Identify yours, jump to the section, skip the rest.
| Situation | Jump to | Output |
|---|---|---|
| Onboarding a new person to an existing team | First 30 Days Checklist → Mentorship Patterns | A 30-day ramp plan with owners and dates |
| Inherited an existing suite with no onboarding/docs | Test Architecture Audit (scope by team_maturity) | A 1-2 page findings doc, five dimensions |
| Need the reference doc for anyone writing tests | Framework Walkthrough Template | A project-specific walkthrough.md |
A real onboarding usually needs all three; a quick health check needs only the audit.
New QA engineer or developer contributing to tests? QA engineers need test strategy context and codebase orientation. Developers contributing tests need framework patterns and conventions. The ramp-up path differs significantly.
Experience level with the test framework? First time with Playwright/Cypress/pytest? Experienced but new to this codebase? Advanced and just needs conventions? This determines how much framework walkthrough to include.
Solo QA or joining an existing QA team? Solo QA needs to establish conventions from scratch. Joining a team means learning existing patterns and contributing within established norms.
Is there an existing test framework? If yes: how healthy is it? If no: framework selection is step one (see test-strategy skill).
Does the project have a .agents/qa-project-context.md? If not, creating one is a high-priority onboarding task -- it forces the new person to document what they learn, which benefits the entire team.
Is local environment setup documented? Can a new person run the full stack and execute tests within the first day? If setup takes more than 2 hours, the process needs fixing before onboarding.
The single most important measure of onboarding success is how quickly the new person gets a real test merged into the main branch. Not a tutorial exercise, not a local-only experiment -- a real test that runs in CI and validates real product behavior. Target: within the first two weeks.
Start simple, increase difficulty gradually. First test: a smoke test or page-load verification. Second test: a form interaction. Third test: a multi-step user flow. By week three, the new person is writing tests for sprint stories. Throwing someone into the deep end with a complex multi-service flow on day one creates anxiety and bad habits.
Every time a new person asks a question that is not answered in documentation, that is tribal knowledge escaping. The onboarding process should capture these answers in permanent form -- ideally in .agents/qa-project-context.md, the framework walkthrough doc, or code comments. The new person is the best person to write this documentation because they know exactly what was missing.
The first 3 tests should be written in a pair -- the new person driving, an experienced team member navigating. Pairing transfers tacit knowledge (why we do things this way, not just how) and builds confidence faster than reading documentation alone.
If the correct way to write a test is harder than the wrong way, people will write tests the wrong way. Ensure that test utilities, fixtures, page objects, and data factories make the recommended patterns the path of least resistance. If a new person has to fight the framework to follow conventions, fix the framework.
Calibrate to your team maturity (set
team_maturityin.agents/qa-project-context.md):
- startup — Focus on days 1–10: get one test framework running and one critical path covered. Skip process ceremony until you have a working baseline.
- growing — Full 30-day plan: framework selection, CI integration, coverage baseline, team conventions documented.
- established — 30-day plan plus: audit existing suite for anti-patterns, propose tooling upgrades, establish metrics baseline, schedule recurring quality reviews.
Day 1-2: Setup
.env.local, test credentials)Day 3-4: Orientation
.agents/qa-project-context.md (or create it if it does not exist).agents/qa-project-context.md, CLAUDE.md, AGENTS.md), which prompts/skills are house style, and which tasks the team explicitly does NOT delegate to AI. Produce a short "AI assistants we use, what they're good at, what to never let them do" doc as a Day 4 deliverable. If the team automates Playwright via an agent, note that agent-driven Playwright now has its own @playwright/cli (daemon architecture, playwright-cli commands, token-efficient) — distinct from the npx playwright test runner the framework walkthrough documents.Day 5: First Small Win
shift-left-testing).agents/qa-project-context.md with new learningsWhen joining an existing project, assess the health of the test suite before writing new tests. This audit takes 2-4 hours and produces a clear picture of the current state.
Scope the audit by team_maturity (from .agents/qa-project-context.md) — a one-size-fits-all audit wastes a startup's time and underserves an established team:
Assess five dimensions, each with a fill-in worksheet:
waitForTimeout/force: true usage, hardcoded data, assertionless tests, deprecated APIs, stale AI-generated tests, stale feature flags.See references/audit-worksheets.md for the copy-and-fill worksheets covering all five dimensions.
Produce a short document (1-2 pages) summarizing findings, categorized as:
Create this document for your project. It is the primary reference for anyone writing tests. It has six sections:
See references/framework-walkthrough.md for the full template with all code blocks, directory trees, and command lists to copy and adapt.
Walk through these areas with the new person in a 60-90 minute session.
Walk through the actual directory tree, explaining:
| Utility | Location | Purpose | Example |
|---|---|---|---|
| Auth fixture | fixtures/auth.fixture.ts | Provides authenticated sessions | { adminPage, userPage } |
| Data factory | helpers/factories.ts | Creates test data via API | createTestUser({ role: 'editor' }) |
| API client | helpers/api-client.ts | Direct API calls for setup/teardown | apiClient.delete('/users/' + id) |
| Accessibility helper | helpers/a11y.ts | axe-core wrapper | checkAccessibility(page, testInfo) |
| Assertions | helpers/assertions.ts | Custom matchers | toHaveToast('Saved') |
Show the existing page objects and explain:
path, waitForReady)checkout.page.ts for /checkout)Open the CI configuration and trace through:
The experienced team member sits with the new person for their first three tests:
Every PR from the new person gets a thorough, supportive review for the first two weeks. Not just "LGTM" -- specific feedback on:
After two weeks, reduce to standard review depth.
Assign a testing buddy -- a specific person the new team member can ask any question without hesitation. The buddy:
Giving a new person repository access, pointing them at the README, and expecting them to figure it out. This produces weeks of wasted time, bad habits learned from trial and error, and early attrition. Structured onboarding with pairing pays for itself in the first sprint.
Spending two weeks on framework tutorials and toy exercises before touching the real codebase. Tutorials teach syntax; they do not teach project conventions, domain knowledge, or team workflow. Minimize tutorials (1-2 hours max) and move to real tests quickly.
When the answer to every question is "ask Sarah," the team has a bus factor of one and onboarding depends entirely on Sarah's availability. Document conventions in .agents/qa-project-context.md and the framework walkthrough. If something is important enough to explain verbally, it is important enough to write down.
Expecting the new person's first test to be perfect. The first test should be functional and following basic conventions. Code quality improves with each PR review cycle. Blocking a first PR on style nits or advanced patterns destroys confidence and delays the first win.
Not soliciting feedback from the person being onboarded. They experienced the process firsthand and know exactly what was missing, confusing, or wasted time. Conduct a 15-minute feedback session at the end of week 2 and week 4. Use their feedback to improve onboarding for the next person.
The new person copies an existing test, changes the locators and URL, and calls it done. The test works but they do not understand why. Pairing and code review should focus on the "why" behind each pattern. If someone cannot explain why a fixture is structured a certain way, they will misuse it when the context differs.
Prove the artifacts hold before declaring onboarding complete. Cheapest check first.
npx playwright test <new-test> --repeat-each=3 exits 0 (3 consecutive passes locally)team_maturity) records that decision instead..agents/qa-project-context.md exists and carries framework, critical paths, team structure, and risk areas — not a high-level placeholder.--repeat-each=3 exits 0) — proves the local and pipeline setup end-to-end.team_maturity, the doc records the explicit decision to scope it out..agents/qa-project-context.md exists and is populated with framework, critical paths, team structure, and risk areas (not a placeholder).references/)