QA team skills

Nitpick v2.1 ships a qa-team skill bundle: 20 SKILL.md files that cover the full spectrum of QA work, from exploring a new feature to filing a production bug, writing a weekly report, or running a pre-release gate.

Each skill is a standalone instruction file the agent reads and follows. They work with any Nitpick provider (Anthropic, OpenAI, Claude Code) and any MCP-aware client.

The skill bundle

Skills are organized by the QA role they map to.

Head of QA

Skill	What it does
qa-scope	Decides test scope for a change or release: maps affected pages, proposes coverage strategy
qa-release-gate	Pre-release checkpoint: runs smoke + critical regressions, blocks or clears the release
qa-coverage-audit	Audits what’s tested vs what exists; surfaces coverage gaps
qa-weekly-report	Weekly QA health report: pass rates, flaky trends, open bugs, coverage delta
qa-roadmap	QA roadmap planning: prioritizes test coverage investments against product milestones

Senior QA

Skill	What it does
qa-kickoff	Runs a per-page kickoff meeting: presents the Derived UI Model, takes approvals
qa-prioritize	Prioritizes a backlog of pages/flows/bugs by risk and business impact
qa-triage	Triages test failures: classifies as real bug, flaky, selector drift, or environment issue
qa-investigate-flake	Deep investigation of a flaky test: timeline, root cause, fix recommendation
qa-classify-failure	Classifies a single failure with an escalating fix ladder

Junior QA

Skill	What it does
qa-explore	Explores a page or flow and builds the Derived UI Model
qa-write-tests	Generates Playwright tests from a Derived UI Model
qa-run	Runs tests, watches results, handles retries, surfaces failures
qa-resume	Resumes an interrupted or partially-complete test run
qa-careful	Extra-careful mode: slows down, adds evidence checks, reduces false passes

Specialty + Safety

Skill	What it does
qa-flow	Tests a multi-actor flow end to end with cross-actor assertions
qa-smoke	Fast smoke check on critical pages: no model-building, no test generation
qa-canary	Canary check on a single page or flow after a deploy
qa-file-bug	Formats and files a bug report with full reproduction steps
qa-fixtures	Manages test fixtures: creates, resets, tears down test data

How skills are loaded

Skills live in skills/qa-team/ in the nitpick repo. Each is a directory with a SKILL.md file:

skills/qa-team/
├── qa-scope/SKILL.md
├── qa-explore/SKILL.md
├── qa-flow/SKILL.md
└── … (20 total)

The agent runtime reads the skill file when a task is routed to that skill. For Claude Code, skills are symlinked into ~/.claude/skills/ so Claude Code picks them up as first-class skills in every session.

Skill format

Each SKILL.md follows the gstack-style format with full frontmatter:

---
name: qa-explore
version: "1.0"
description: Explore a page and build its Derived UI Model
allowed-tools: bash, read_file, write_file, list_files, ask_user, kb_get_page, kb_put_page
triggers:
  - "explore"
  - "build page model"
  - "what's on this page"
---

## Phase 1: Orientation
...

Key structural elements:

• Numbered phases with explicit precondition gates (phase N only runs if phase N-1 output exists)
• Decision-format AskUserQuestion blocks for HITL checkpoints
• KB context table — what to read from the KB at the start, what to write at the end
• Failure mode table — known failure patterns and their resolution paths
• Worked example — a complete run trace showing what the agent should produce

Using with Claude Code

After running ./scripts/install-skill.sh, skills appear in Claude Code’s skill picker. You can invoke them directly:

> use qa-explore on /tasks/new
> run qa-smoke on my critical pages
> qa-weekly-report for this week

Claude Code routes the request to the matching skill and has full access to the KB via the MCP server.

Using with the CLI

Skills are invoked automatically by the orchestrator based on task type. You don’t invoke them by name in normal CLI usage. The orchestrator routes:

• Page testing → qa-explore + qa-write-tests + qa-run
• Flow testing → qa-flow
• Smoke → qa-smoke
• Failure triage → qa-classify-failure
• Release check → qa-release-gate

You can also invoke a skill directly via the API for custom orchestration.

Custom skills

You can write your own skills following the same format. Place them in skills/my-skill/SKILL.md and reference them in your config. Custom skills work with all providers.