test-automation-skills-agents

Test Automation AI Agents & Skills (Tool-Agnostic) 🚀

A practical library of agents, instructions, and skills designed specifically for QA Automation Engineers, focusing on production-oriented solutions.

This repository is tool-agnostic by design: the concepts and content can be used with GitHub Copilot, Claude, Cursor, OpenCode, Windsurf, and similar AI assistants.

---

Key Features

This repository is designed to be copied/embedded into real testing projects so your AI assistant can actively assist with:

• UI, API, E2E, smoke, and regression testing
• Accessibility testing (WCAG 2.2 AA)
• Flaky test investigation and stabilization
• Test planning (ISTQB-aligned) and documentation
• Framework patterns (Playwright TypeScript, Selenium Java)

Important: This repository is a documentation/knowledge base — no build or test system. The only validation is a dependency-free structural linter: node scripts/lint-skills.mjs (0 errors required; runs in CI on PRs touching skills/, agents/, or instructions/).

What you get

• Agents (in agents/): persona + responsibilities + boundaries for specialized AI behavior
• Instructions (in instructions/): lean, scoped essentials (locator priority, no-hard-waits rules) — deep content lives in skills
• Skills (in skills/): reusable workflows + references + scripts/templates (progressively loaded by supporting tools; otherwise used as playbooks)

Repository structure

agents/           # Custom agent definitions (*.agent.md)
instructions/     # Lean, scoped coding essentials (*.instructions.md)
skills/           # Reusable capabilities (skills/*/SKILL.md + resources)
docs/             # Setup guides, standards, and documentation
├── references/   # Authoring guides and examples
├── enhancements/ # Enhancement plans (CE audit, deferred decisions)
└── archive/      # Completed/stale planning logs (kept for history)
references/       # Shared reference material (anti-patterns, patterns)
scripts/          # Structural linter (lint-skills.mjs — the repo's only validation)
.claude-plugin/   # Claude Code plugin/marketplace metadata
AGENTS.md         # House style, file standards, frontmatter rules
CLAUDE.md         # Claude Code entry point + architecture notes
CHANGELOG.md      # Release history (Keep a Changelog)

Quick start (recommended workflow)

This repo is a catalog. Choose the integration style for your tool.

Integration choices

• GitHub Copilot (customizations): use .github/agents, .github/instructions, and .github/skills.
• Claude/Cursor/OpenCode/Windsurf/etc.: copy the same content into the tool's repo/workspace rules system, keeping the same structure and naming so your team shares a consistent vocabulary.

Setup guides

Tool	Setup Guide
Claude Code	docs/claude-code-setup.md
Cursor	docs/cursor-setup.md
GitHub Copilot	docs/copilot-setup.md
Antigravity CLI	docs/antigravity-setup.md
Windsurf	docs/windsurf-setup.md

Option A - Copy into your target repository (most reliable)

1. Copy agents:

   • From: agents/
   • To: .github/agents/

2. Copy instructions:

   • From: instructions/
   • To: .github/instructions/

3. Copy skills:

   • From: skills/<skill-name>/
   • To: .github/skills/<skill-name>/

4. Commit the files to your target repo.

Verify Copilot can see the assets

In your target repository:

1. Confirm files exist at the expected paths:

   • .github/agents/*.agent.md
   • .github/instructions/*.instructions.md
   • .github/skills/<skill-name>/SKILL.md

2. In VS Code, reload the window (or restart VS Code) to refresh Copilot customizations.

3. Open Copilot Chat:

   • Ensure your agents appear in the agent selector dropdown.
   • If a skill does not seem to trigger automatically, explicitly mention it by name in your prompt.

Verify other AI tools can use the content

If you are using Claude/Cursor/OpenCode/Windsurf (or another assistant), verification is typically:

1. Ensure the files are present in the tool's configured rules/prompts scope (repo-level or workspace-level).
2. Start a new chat session so the tool reloads instructions.
3. Ask for a response that should clearly follow a rule (e.g., "avoid Thread.sleep(); use explicit waits").

Option B - Git submodule (centralized updates)

Add this repo as a submodule, then copy/sync assets into .github/* as part of your internal workflow.

Option C - Install via Claude Code Plugin Marketplace

Subscribe to this repository as a plugin marketplace directly from Claude Code:

/plugin marketplace add fugazi/test-automation-skills-agents

Then install the plugin:

/plugin install test-automation-skills-agents@fugazi-test-automation

This will make all 7 specialized QA agents and 10 reusable skills available in your Claude Code session.

Local / development:

git clone https://github.com/fugazi/test-automation-skills-agents.git
claude --plugin-dir /path/to/test-automation-skills-agents

Option D - Install skills via skills.sh

You can install skills directly from this repository using skills.sh:

• Browse the skills list for this repo: https://skills.sh/?q=fugazi/test-automation-skills-agents

Copy/paste any of these commands:

npx skills add https://github.com/fugazi/test-automation-skills-agents --skill playwright-e2e-testing

npx skills add https://github.com/fugazi/test-automation-skills-agents --skill a11y-playwright-testing

npx skills add https://github.com/fugazi/test-automation-skills-agents --skill webapp-selenium-testing

npx skills add https://github.com/fugazi/test-automation-skills-agents --skill qa-manual-istqb

npx skills add https://github.com/fugazi/test-automation-skills-agents --skill accessibility-selenium-testing

npx skills add https://github.com/fugazi/test-automation-skills-agents --skill playwright-regression-testing

npx skills add https://github.com/fugazi/test-automation-skills-agents --skill playwright-cli

npx skills add https://github.com/fugazi/test-automation-skills-agents --skill api-testing

npx skills add https://github.com/fugazi/test-automation-skills-agents --skill grill-me-qa

npx skills add https://github.com/fugazi/test-automation-skills-agents --skill qa-investigation

---

Note: Copilot's discovery typically looks at canonical locations like .github/agents and .github/skills. Keeping this repo as a submodule is fine, but you will generally still want a sync step into .github/*.

---

Core concepts

1) Agents: "who does the work and how"

Agents define:

• Identity and specialization (e.g., Playwright Test Healer)
• Scope boundaries (what the agent will / will not do)
• Tool access (least-privilege when possible)
• Workflow expectations and output format

Agents live in files named like:

• lowercase-with-hyphens.agent.md

Each file includes YAML frontmatter within this repo. See AGENTS.md for local standards.

Tool-agnostic mapping:

• Copilot: custom agent file under .github/agents/
• Other tools: use the agent body as a dedicated system prompt / mode / persona, and keep the same boundaries

2) Instructions: "the operating system"

Instructions are cross-cutting rules that keep outputs consistent:

• Playwright coding standards, locator strategy, POM patterns
• Selenium Java standards, explicit waits, AssertJ, Allure
• Accessibility expectations (WCAG 2.2 AA)
• CI/CD test pipeline configuration (GitHub Actions, test tiers, parallel execution)
• Single-tag test classification: exactly one tag per test (@smoke, @sanity, @regression, @e2e, @api, @destructive) — never on describe()/class level, never combined; @destructive runs sequentially, excluded from parallel runs
• Agent authoring guidelines (frontmatter, handoffs, tool selection)

In practice:

• Use instructions when you want consistent conventions across teams/repos.
• Treat instructions as non-negotiable constraints for day-to-day work.

Tool-agnostic mapping:

• Put the instruction content into your tool's repo-level rules (often a single "rules" file), or keep them split by domain (Playwright, Selenium, a11y) like this repo does.
• If your tool supports file globs/scopes, mirror the intent (e.g., Playwright rules apply to **/*.spec.ts).

Compatibility notes (VS Code vs GitHub)

Customizations can behave slightly differently depending on where you run Copilot.

• VS Code
  • Supports agent model and handoffs (depending on version).
  • Great for interactive workflows (planning → generate → debug → heal).
• GitHub (Copilot Coding Agent)
  • Commonly expects agents under .github/agents/.
  • Some frontmatter fields may be ignored depending on the environment.

When in doubt, keep the frontmatter minimal and portable:

• Agents: description (required), plus optional name, tools, target, infer, handoffs
• Skills: name + description (required), optional license
• Do not pin model in agent or skill frontmatter — let the tool harness choose

Tool-agnostic usage (Claude/Cursor/OpenCode/Windsurf)

Use this repo as a shared "QA automation brain" for your team:

1. Keep this repository as the source of truth.
2. Sync/copy its content into whichever format your AI tool supports.
3. Keep the same names so prompts remain consistent across tools:
   • "Use the Playwright Test Healer agent."
   • "Follow the Playwright TypeScript instructions."
   • "Apply the playwright-e2e-testing skill playbook."

Copilot-specific parts are mainly:

• The .github/* discovery paths
• Some frontmatter fields that other tools ignore

The testing guidance itself (locator strategies, waits, POM patterns, a11y workflows, ISTQB artifacts) is portable.

3) Skills: "reusable playbooks + resources"

Skills are folder-based capabilities that Copilot can load on-demand.

Key characteristics (by design):

• Progressive loading

  • Level 1: Copilot reads only name + description to decide relevance
  • Level 2: Copilot loads the body of SKILL.md when relevant
  • Level 3: Copilot loads references/scripts/templates only when linked/needed

• Resource bundling

  • references/: docs loaded into context when referenced
  • scripts/: executable helpers (deterministic behavior)
  • templates/: starter code that AI may modify
  • assets/: static files used as-is

How to use agents (day-to-day)

Agents are activated the same way across tools — by referencing the agent in a prompt (its description drives selection). The exact UI differs per assistant; the prompts below work everywhere. The flows below are GitHub Copilot-specific examples — for Claude Code, Cursor, Windsurf, and OpenCode see the matching setup guide.

In VS Code (Copilot Chat)

1. Open Copilot Chat.
2. Select the agent from the agent dropdown (Custom Agents).
3. Give a task prompt.

Prompt examples:

• "Use Playwright Test Healer: investigate why checkout.spec.ts fails intermittently in CI and propose fixes."
• "As API Tester Specialist: create negative tests for /v1/orders covering auth failures and schema validation."
• "As Selenium Test Specialist: generate POM + JUnit 5 tests for login + forgot password."

In GitHub (Copilot Coding Agent)