Skip to content
Get packs

Guide · Agent skill

How to use the Agent QA Test Authoring agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The agent-qa-authoring skill is a set of instructions that teaches an AI agent (such as Claude) how to write automated quality-assurance tests for the Agent QA testing tool. It is aimed at QA engineers and developers who already use Agent QA and want fewer schema errors. After this guide you will know what the skill does, how to install it, how to ask for work in plain language, and what to check before anything runs.

Agent QA Test Authoringsickn33/agentic-awesome-skills · MIT

Quick start

  1. 1Get the ZIP. Download the agent-qa-authoring skill as a ZIP from the page you are reading.
  2. 2Install the skill. Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
  3. 3Prepare Agent QA. Make sure Agent QA is installed and a workspace is configured, reachable through MCP or the CLI.
  4. 4Make a request. Describe the test, name the target and say whether to validate only or also run it.
  5. 5Review the output. Check the definition, the validation result and which surface (MCP, CLI or YAML) the agent used.
  6. 6Approve any run. Confirm the environment and give explicit approval before any run that could change external state.

What the skill makes the agent do

Agent QA tests, suites and hooks are definitions that describe automated checks. Without guidance, an AI agent may guess field names or invent identifiers, which breaks the definition. This skill tells the agent to look up exact field names and ID formats in a bundled reference file (references/agent-qa-contracts.json), generate every new ID with Agent QA's own tooling, and validate each definition before saving or running it.

The skill works through Agent QA's MCP tools when they are available and falls back to the CLI or YAML files when they are not. It also states that the agent should inspect the requested scope first and ask for explicit confirmation before deleting a definition or running a test that could change external application state.

  • Creates, edits, validates and runs tests, suites and hooks.
  • Generates IDs with official tooling instead of making them up.
  • Checks definitions against the schema before saving or running.
  • Asks for approval before deletes or potentially state-changing runs.

Install the agent-qa-authoring skill

Download the skill as a ZIP from the page you are reading. Then choose one of two install locations. For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

The skill folder contains two files: SKILL.md, which holds the instructions, and references/agent-qa-contracts.json, which holds the exact field and ID contracts the agent reads.

  • Personal: unzip into ~/.claude/skills/
  • Project: unzip into .claude/skills/ inside the project
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Set up Agent QA before you use the skill

The skill cannot do useful work without an installed Agent QA tool and a configured workspace. The workspace is reached either through an MCP server or through the CLI. Depending on your target you may also need browser, mobile or model-provider dependencies. Secrets must be handled through the workspace's own secret configuration, not written into test definitions.

The agent starts by discovering the local setup and reading the active configuration, so it helps to have the workspace ready and authorized before you ask for anything.

  • Agent QA installed and a configured workspace (MCP server or CLI)
  • Browser, mobile or model-provider dependencies for your chosen target
  • Secrets kept in the workspace's secret configuration, not in definitions

Trigger the skill with a natural request

You do not need special syntax. Describe the test you want, name the target, and say whether you want it run. Be explicit about stopping points, because the skill is written to stop before running when you ask it to.

The skill's own example shows the pattern. The agent discovers the workspace, inspects the staging target, generates the test ID, creates the smallest valid definition, validates it, and stops before enqueueing a run.

  • Name the target, for example staging.
  • Say what the test should cover, for example a checkout flow.
  • State whether to validate only, or to run as well.
User: Add an Agent QA checkout test for the staging target and validate it, but do not run it yet.

Check the skill's safety limits before running tests

The skill declares that it runs scripts and uses the network. Keep the scope narrow. Reconfirm the target and environment whenever a test might mutate real data or trigger external actions. The skill does not infer undocumented config keys, selectors, UI states, credentials or test data, so you need to supply those.

Validation proves that a definition matches the schema. It does not prove that the application or environment is safe to test. Do not point runs at production systems without careful scoping. The skill also says it only partly guards against side effects.

  • Work only in a workspace you have authorized.
  • Confirm the environment before any run that may change data.
  • Keep credentials out of definitions and output.
  • Do not expect validation to certify that an environment is safe.

Tips for better results

Give the agent the target name and the smallest scenario you need. Smaller definitions are easier to validate and review. Ask the agent to say which surface it used, MCP or CLI or YAML fallback, because MCP availability and permissions vary by workspace.

If the agent asks you to approve an installation, read it carefully. The skill says it should not fetch and run the package at runtime through npx or another moving package reference, and should instead ask for an exact installation.

  • Start with validate-only requests, then run once you are satisfied.
  • Ask which fallback (MCP, CLI or YAML) was used.
  • Keep test files inside the configured workspace patterns.

What people use it for

  • Drafting a browser test for a staging checkout flow and validating it before anyone runs it.
  • Adding a suite that groups existing tests, with validation before saving.
  • Updating an existing hook or suite while keeping its canonical IDs unchanged.
  • Checking existing test and suite IDs against the ID contracts with the validate command.
  • Looking up which Agent QA configuration fields apply to a given target.

Frequently asked questions

Is the agent-qa-authoring skill free to use?

The directory page lists the skill under an MIT licence. However, the SKILL.md file names FSL-1.1-ALv2 as its licence and links to the Agent QA LICENSE.md. Read the licence file before you rely on it, because the two statements differ.

What do I need before the skill works?

You need an installed Agent QA tool and a configured workspace reachable through an MCP server or the CLI. Depending on your target you may also need browser, mobile or model-provider dependencies. The skill cannot do anything useful without the workspace.

How do I install the agent-qa-authoring skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can upload the ZIP under Settings → Capabilities → Skills instead.

Does the skill run scripts or use the network?

Yes. The skill declares that it runs scripts and uses the network. Limit it to authorized workspaces and confirm the target before any run that could change real data.

Why won't the agent generate test IDs by hand?

The skill requires every new ID to come from Agent QA tooling, such as the agent_qa_generate_id MCP tool or the agent-qa ids generate CLI command. Hand-written IDs can break the canonical ID contracts that Agent QA expects.

What should I use instead if I need a general-purpose test framework?

This skill is only for Agent QA. If you need a general-purpose test framework outside Agent QA, pick a tool built for that purpose, because this skill does not cover it.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you already maintain Agent QA suites and want an agent to draft tests with fewer schema errors while you approve every run. Do not use it without a configured Agent QA workspace, or to run tests against production systems without careful scoping. Teams that need a general-purpose test framework should look elsewhere.

Download the skill