simple-ai-skills

Skills that let Claude Code QA a live site in a real browser, file a well-formed GitHub issue, and write commit messages that explain themselves. Installed into your repo with one command.

npx simple-ai-skills

Pick the skills you want from the list. They are copied into .claude/skills/ in the current repository, where Claude Code reads them. Installing into a project resolves to the repository root, so it works from any subdirectory.

Node 20 or newer.

Contents

• The catalog
• Commands
• Updating
• Using qa-explore — full guide
• Using github-issue-report — full guide
• Contributing a skill

The catalog

| Skill | What it does | Needs | |---|---|---| | qa-explore | Drives a website through Playwright MCP from a plain-English testing idea, reproduces what looks broken, and writes a report with evidence. Saves each idea as a scenario you can replay. | Playwright MCP — setup | | github-issue-report | Reads confirmed bugs out of a qa-explore report, checks for duplicates, recommends which repository each belongs in, follows that repository's issue template and labels, and files with gh after you approve each body. | gh CLI — doctor fails when it is missing and prints the install command for your machine — setup | | writing-clear-commits | Commit messages that explain why a change was made rather than restating the diff. | — |

The two QA skills compose: qa-explore finds and confirms a bug, then offers to hand it to github-issue-report, which files it and records the issue number back into the scenario. Each works fine on its own.

Commands

simple-ai-skills                      Pick skills interactively
simple-ai-skills list                 Show the catalog
simple-ai-skills install <name...>    Install one or more skills
simple-ai-skills uninstall <name...>  Remove one or more skills
simple-ai-skills update               Re-copy installed skills from this version
simple-ai-skills doctor               Check whether a run would work, and why not
simple-ai-skills setup-qa             Set up Playwright MCP for qa-explore

| Option | Effect | |---|---| | --global | Install to ~/.claude/skills instead of the current project | | --agent <list> | Which agent tools setup-qa configures: claude, copilot, codex, or all (comma-separated, default claude) | | --force | Replace a skill whose contents differ from the bundled copy |

Checking a setup

npx simple-ai-skills doctor

Reports whether a run would work and prints the one command that fixes each problem. It only reads — it never repairs, and it never writes.

It exits 0 when ready and 1 when not, so it also works as a CI gate. Three things it deliberately cannot tell you, and says so in its own output: whether sign-in succeeds, whether QA_SCOPE_NAME matches the live scope, and whether the target is reachable. Those are only observable during a run.

The same report prints after setup-qa, minus the checks that need a subprocess.

Updating

update re-copies skills you already have. If a skill's contents differ from the bundled copy it stops and tells you, because that difference could equally be your own edit or a newer release. Pass --force once you have decided which you want.

Using qa-explore

qa-explore drives a real browser against a real site. Everything in this section is setup you do once per repository; for the invocation forms, worked examples and troubleshooting, see Using qa-explore.

What you need

• Claude Code.
• The Playwright MCP server (installed below). The skill refuses to run without it and will not substitute curl or a headless script, because a substitute cannot see the rendered page.
• A site you own or are authorized to test.

1. Set it up

npx simple-ai-skills setup-qa

It asks for the three values a run needs, then adds the ignore lines to .gitignore, writes .claude/qa-config.env and .claude/qa-secrets.env, and registers the Playwright MCP server — in that order, so the ignore rule exists before the file holding your password does.

◆  Base URL - the only origin a run may visit
│  https://staging.example.com
│
◆  QA account email (leave blank to run anonymously)
│  [email protected]
│
◆  Password for [email protected]
│  •••••••••

The base URL is validated as an http/https origin, and the email is checked for shape. Leave the email blank and the password is not asked for at all, since an anonymous run has nothing to sign in to. Ctrl-C at any prompt writes nothing.

It is safe to re-run: it asks only about values that are still blank and never overwrites one already on disk, so a half-finished setup can be completed by running it again. Without a TTY — CI, or a piped invocation — it asks nothing and writes the blank template for you to fill in by hand.

And install a browser. @playwright/mcp does not ship one, and the server starts happily without it — the failure shows up at the first navigation, in the middle of a run.

npx playwright install chromium

Then approve the server. A project-scoped server shows ⏸ Pending approval until you approve it in an interactive session — this is the step people miss. Check with claude mcp list; anything other than connected means the tools are not loaded and the skill's preflight will fail. Or run npx simple-ai-skills doctor, which checks that along with everything else a run needs.

Other agent tools

--agent also configures Copilot and Codex, which read different files:

| Agent | File | Scope | |---|---|---| | claude | .mcp.json | project | | copilot | .vscode/mcp.json | project | | codex | ~/.codex/config.toml | global |

npx simple-ai-skills setup-qa --agent all

Codex has only one global MCP config, so its entry uses absolute paths pointing at the project you ran the command in. Running setup-qa --agent codex in a second project reports a conflict rather than silently repointing it; --force repoints it. Nothing else in config.toml is ever rewritten — the block is edited by line range, so your model setting, comments and project trust entries survive untouched.

qa-explore itself is a Claude Code skill. Copilot and Codex get the Playwright browser tools, but they do not load .claude/skills, so they do not get the qa-explore protocol.

2. The rest of the config

The prompts cover QA_BASE_URL, QA_EMAIL and QA_PASS. The other two keys are written as blanks with a commented example above each, for you to set when you need them.

.claude/qa-config.env:

| Variable | Required | Meaning | |---|---|---| | QA_BASE_URL | yes | The only origin a run may visit | | QA_EMAIL | no | If set, the run signs in. If unset, it runs anonymously and scenarios needing a login are reported as blocked | | QA_SCOPE_NAME | no | Account or workspace to stay inside. Set → asserted at startup. Unset → whatever it signs in to is adopted and recorded | | QA_ALLOW_IRREVERSIBLE | no | sends, deletes, or both. Unset means both stop and ask. An unrecognised value aborts rather than being ignored, so a typo cannot read as "nothing enabled" | | QA_ISSUE_REPOS | no | Repository URLs, comma-separated, that github-issue-report may file into. Unset means the repository resolved from the directory you run in. With several, it recommends one per finding and asks before filing |

.claude/qa-secrets.env holds one key, and the name matters:

QA_PASS=your-qa-account-password

The prompt masks it, but it is stored in plaintext because that is how the server reads it — which is why .gitignore is written first. This file is read by the MCP server, never by Claude: the skill types the literal string QA_PASS and the server substitutes the real value. It must exist even if you are testing anonymously — the server will not start without it.

3. Doing it by hand

setup-qa is a shortcut for this:

claude mcp add --scope project playwright -- \
  npx -y @playwright/[email protected] \
  --isolated \
  --output-dir .claude/qa-runs \
  --secrets .claude/qa-secrets.env

plus creating the two env files above, and adding to .gitignore before either of them exists:

.claude/qa-config.env
.claude/qa-secrets.env
.claude/qa-runs/

Do the .gitignore step before your first run. Skipping it commits a password.

4. Run it

The first word is the area — free-form, whatever you group scenarios by. explore and smoke are reserved.

| Form | What it does | |---|---| | qa-explore <area>: <idea> | Test one idea now and save it as an active scenario | | qa-explore <area> | Replay every active and quarantined scenario in the area | | qa-explore <area>: explore | Let the skill generate up to eight test ideas for the area, run them, and save them as draft scenarios | | qa-explore <scenario-id> | Run one scenario by id, including a draft | | qa-explore smoke | Replay every scenario tagged smoke across all areas — the release check |

qa-explore checkout: apply a discount code and check the total updates

Every scenario has a budget of 25 browser actions. One that runs out is reported as blocked rather than allowed to wander.

What you get

docs/qa/reports/2026-08-31-checkout-1.md   the run's findings, with evidence
docs/qa/reports/assets/<run-id>/           screenshots for confirmed bugs only
docs/qa/scenarios/checkout/checkout-001.md the idea, saved so it can be replayed
docs/qa/INDEX.md                           every scenario, its status and last result
docs/qa/app-map.md                         how to reach things on your site

A finding is only a confirmed bug if it reproduced on a clean second pass. Anything seen once lands under "Unconfirmed observations" instead. This is deliberate: the most common failure of agent-driven QA is inventing bugs, not missing them, and re-running is the defense.

Safety

Read the skill's references/safety.md — it is the authority, and it is short. The three rules worth knowing before your first run:

• Origin lock. Only QA_BASE_URL's origin. A redirect off-origin ends the run.
• No production detection. The skill cannot tell staging from production and does not try, because hostname guesses are wrong in both directions. Whatever QA_BASE_URL points at is what gets tested, with whatever data lives there.
• Irreversible actions stop and ask unless you listed them in QA_ALLOW_IRREVERSIBLE. Payments and account deletion always stop, whatever you configure.

Using qa-explore → — each invocation form walked through end to end, the scenario library and its statuses, the app map, how to read a report, and troubleshooting.

Using github-issue-report

Turns a finding into a well-formed GitHub issue. Useful on its own — it does not need qa-explore.

What you need

• The gh CLI, authenticated: gh auth login.
• A working directory inside the GitHub repository you want to file against.

If gh is missing or logged out, the skill stops and tells you. It will not fall back to an API token or hand you the text to paste in yourself.

Running it

Describe the finding, or point at a QA report:

file a github issue for the checkout discount bug in the latest qa report

Before anything is filed it searches existing issues — open and closed, since a closed match may mean "regression" or "already rejected", and it tells you which — shows you the full title and body, and waits for your yes. It uses your repository's own .github/ISSUE_TEMPLATE if you have one, and applies only labels that already exist.

Screenshots reach the issue only as links to a copy GitHub already serves, since gh cannot attach images. A file on a pushed commit is linked at that commit and renders inline; anything else keeps its local path and says "not yet pushed; available locally". The skill never commits or pushes for you.

When the finding came from a qa-explore report, filing writes the issue URL back into the scenario and offers, once, to quarantine it so replays list it as known-failing instead of reporting it again.

Using github-issue-report → — the duplicate search and what a closed match means, the evidence reachability check, the scenario write-back, and worked examples with and without a QA report.

Contributing a skill

See docs/authoring-skills.md.