Your agent says "the app works". This makes it prove it in a browser.
browser-qa is an agent skill for real browser QA. It checks the app like a user would: services are up, pages render, login works, navigation is clickable, modals fit on mobile, console errors are visible, failed requests are investigated, and backend logs are part of the story.
Works with local dev servers, Docker Compose stacks, deployed URLs, React/Vite/Next apps, admin dashboards, and most browser-based products.
Global install:
npx skills add tchivs/browser-qa-skill --skill browser-qa -gProject install:
npx skills add tchivs/browser-qa-skill --skill browser-qaFor OpenCode, the easiest manual install is to ask your agent to install it for you.
Global OpenCode prompt:
Install the browser-qa skill globally for OpenCode from this GitHub repository:
https://github.com/tchivs/browser-qa-skill
Use browser-qa/SKILL.md as the source file and install it to:
~/.config/opencode/skills/browser-qa/SKILL.md
Also copy browser-qa/evals/ if supported. Do not modify the skill content.
Project OpenCode prompt:
Install the browser-qa skill for this project from this GitHub repository:
https://github.com/tchivs/browser-qa-skill
Use browser-qa/SKILL.md as the source file and install it to:
.opencode/skills/browser-qa/SKILL.md
Also copy browser-qa/evals/ if supported. Do not modify the skill content.
Shell fallback, global:
git clone https://github.com/tchivs/browser-qa-skill.git
mkdir -p ~/.config/opencode/skills/browser-qa
cp browser-qa-skill/browser-qa/SKILL.md ~/.config/opencode/skills/browser-qa/SKILL.md
cp -R browser-qa-skill/browser-qa/evals ~/.config/opencode/skills/browser-qa/evalsShell fallback, project:
git clone https://github.com/tchivs/browser-qa-skill.git /tmp/browser-qa-skill
mkdir -p .opencode/skills/browser-qa
cp /tmp/browser-qa-skill/browser-qa/SKILL.md .opencode/skills/browser-qa/SKILL.md
cp -R /tmp/browser-qa-skill/browser-qa/evals .opencode/skills/browser-qa/evalsAsk your coding agent:
Run a browser QA pass on this dev deployment. Check login, navigation, console errors, and failed API requests.
Docker says all services are up, but the page is blank. Find out whether it is a frontend, API, or backend problem.
The admin page works on desktop, but the mobile drawer and modal feel broken. Verify the mobile flow and report issues.
The skill will guide the agent to discover the app, open it in a real browser, inspect rendered UI, check network/console failures, correlate logs, and return a concise QA report.
- Blank pages hidden behind "healthy" containers
- Broken login redirects and missing tokens
- Wrong API base URLs and
/api/api/...style mistakes - UI flows that silently fail without a visible error
- Mobile dialogs clipped by the viewport or keyboard
- Sidebars, drawers, and overlays with broken z-index behavior
- Tables and tab bars that overflow on small screens
- Buttons, links, and inputs without accessible names or labels
- Backend 500s that never surface clearly in the UI
Most QA skills waste time rediscovering the same app every run. browser-qa uses a project-local profile instead.
On first run, it infers the app from files such as:
README.mdpackage.jsonpnpm-workspace.yamldocker-compose.yml.env.examplevite.config.*,next.config.*,nx.json
Then it saves non-secret facts to:
.browser-qa/profile.json
The profile stores URLs, health checks, service names, login paths, smoke paths, and credential environment variable names. It must not store passwords, tokens, cookies, or production secrets.
Future runs load the profile first and only refresh discovery when files changed, URLs are stale, or the user explicitly asks to rediscover the app.
The bundled scripts are dependency-free Node.js utilities for deterministic checks. They do not run browser automation and do not install global packages.
Create a profile template:
node browser-qa/scripts/create-profile-template.mjs --mode docker-composeValidate a project profile:
node browser-qa/scripts/validate-profile.mjs --profile .browser-qa/profile.jsonCheck this skill repository before publishing:
node browser-qa/scripts/doctor.mjsdiscover project → create/reuse QA profile → health check services
→ open browser → click critical flows → inspect console/network
→ correlate logs → report what passed, failed, and remains risky
The skill prefers agent-browser for browser interaction, but it should not assume the CLI is already installed or silently install global packages.
The agent should check first:
command -v agent-browserIf it is installed, the agent should load the live CLI guide before browser actions:
agent-browser skills get coreIf it is missing, install it only when the user explicitly asks to set up browser QA tooling, or fall back to an existing project Playwright workflow when available. Playwright is also the better path when the user asks to create durable E2E tests.
browser-qa is the orchestrator. It should hand off when the task becomes specialized:
These companion skills are optional. You do not need to install them before using browser-qa; the skill should still run generic browser QA without them.
| Need | Better follow-up skill |
|---|---|
| Write durable Playwright tests | playwright-best-practices |
| Design an E2E test strategy | e2e-testing-patterns |
| Run a full a11y/responsive/performance audit | audit |
| Check React code health after fixes | react-doctor |
| Fix React rendering or bundle performance | react-performance-optimization |
| Fix Tailwind v4 or shadcn/ui issues | tailwind-v4-shadcn, shadcn-ui |
| Repair responsive layout | adapt |
| Harden edge cases, overflow, i18n, errors | harden |
| Polish visual details | polish |
browser-qa-skill/
├── browser-qa/
│ ├── SKILL.md
│ ├── evals/
│ │ └── evals.json
│ └── scripts/
│ ├── create-profile-template.mjs
│ ├── doctor.mjs
│ └── validate-profile.mjs
├── README.md
├── README.zh-CN.md
├── LICENSE
└── .gitignore
The skill lives in browser-qa/SKILL.md so the directory name matches name: browser-qa, which keeps strict skill importers happy.
For skill.sh-style discovery, a public GitHub repo plus installs through the skills CLI may be enough. When users run:
npx skills add tchivs/browser-qa-skill --skill browser-qathe skills ecosystem may use anonymous install telemetry to discover the skill and rank it by installation count. In that model, there is no separate manual upload step: keep the repo public, make the skill installable, share the install command, and installs drive visibility.
If a registry also supports Add Skills / Import Repository, paste this repo URL as an optional extra step:
https://github.com/tchivs/browser-qa-skill
Issues and PRs are welcome. Good improvements include:
- better browser QA heuristics
- more realistic eval prompts
- clearer report templates
- additional project profile fields that do not store secrets
- compatibility notes for more agent runtimes
MIT