Agent skill

Agentiqa's chat experience is the agent proposes, you curate: it explores your app, drafts a test plan, and you approve it before anything is saved or run. The agent skill brings that same loop to the command line, with your coding agent (Claude Code and compatible agents) acting as the coordinator. You stay the QA lead — you review the draft in chat and decide when it gets saved and run.

This is the authoring side of the CLI. Once a plan is saved, gating it in a pipeline is the CI lane's job: the plan you author here is exactly what agentiqa run --plan-id replays and gates in CI.

What it is (and what it isn't)

The skill is a compact instruction set — a SKILL.md plus bundled reference files — that teaches an AI coding agent how to drive Agentiqa: which surface to pick, the agentiqa CLI verbs, the plan-authoring loop, the GitHub Action, the JSON envelope, and the exit-code contract. It uses progressive disclosure and delegates to this site's /llms-full.txt for anything not bundled.

It ships as part of the Agentiqa plugin (Agentiqa/agentiqa-plugin), which contains two skills:

• agentiqa-test — runs Agentiqa against your app from inside the coding agent (explore, report bugs with reproduction steps and media);
• agentiqa (this skill) — how to drive Agentiqa: the CLI verbs and selectors, the plan-authoring loop (explore → review → save → run → read → revise), the GitHub Action, service keys, the JSON envelope, and exit codes.

It is not:

• an MCP server — it exposes no tools and runs no process;
• the Agentiqa product — the skill contains only instructions. The actual testing is done by the tools it points at: the agentiqa CLI (published on npm) and the agentiqa/qa-action GitHub Action.

Install

Claude Code:

/plugin marketplace add Agentiqa/agentiqa-plugin
/plugin install agentiqa@agentiqa

Cursor: /add-plugin https://github.com/Agentiqa/agentiqa-plugin · Codex CLI: codex plugin marketplace add Agentiqa/agentiqa-plugin

The agent loads the skill on demand when you ask it to test an app with Agentiqa, author or run a test plan, or parse an Agentiqa result. No configuration is required.

Authentication

The authoring loop runs against your account, so it needs auth. Two options:

• agentiqa login (interactive) — enough for every verb, run included. Pick the project with agentiqa project use <id|name>, --project, or AGENTIQA_PROJECT_ID; see Choosing a project. This is the route to use for a project a teammate shared with your organization, because only a project's owner can mint a service key for it.
• A project-scoped service key (unattended / CI) — create one in the web or desktop app (Project Settings → CLI Service Keys), then expose it to your coding agent's shell as AGENTIQA_SERVICE_KEY — never inline it on the command line or paste it into chat. See CLI Service Keys.

One honest limit: a service key is scoped to a single project. Every plan list / get / save and every run under that key reads and writes that one project's plans, and --project cannot override it. To work across projects under one login, use agentiqa project use / --project instead of a key.

On a shared project

A project shared with your organization works here like any other: after agentiqa login, the plans you save and the runs you start are the team's, and each carries your name in the project's history — the app shows who ran what and who last edited each plan. Plans that sign in use your own credential when you have one, and otherwise a shared account the team's admin provisioned.

Environments

By default the CLI and skill target Agentiqa production (agentiqa.com) — no configuration needed. If your organization runs a non-default or self-hosted Agentiqa, set AGENTIQA_API_URL to that environment's base URL; the hosted engine is derived from it automatically, so you never pass --engine unless you self-host the engine itself.

The loop

Your coding agent runs the same curation loop the chat coordinator does — it just uses the CLI verbs to do it:

1. Explore — the agent runs agentiqa explore against your target. The engine proposes a draft plan (the --json envelope's testPlan).
2. Review — the agent presents the draft to you in chat: the title, and each numbered step with its type and criteria. Nothing is saved yet.
3. Approve — you approve the exact plan shown. The agent treats only your explicit approval as consent to save — never the original request, silence, or --auto-approve (that flag only clears exploration's runtime checkpoints).
4. Save — on approval the agent pipes the plan JSON to agentiqa plan save, which mints a tp_… id (or edits in place when the JSON already carries one).
5. Run — the agent runs the saved plan by id and reports the verdict, summary, and run link.
6. Read & revise — agentiqa runs get reads the verdict history; to change the plan the agent starts from agentiqa plan get, edits the prose and structure, and loops back to review.

A realistic session:

you    > Explore the checkout flow on the app and draft a plan.

agent  > $ agentiqa explore "Test the checkout flow" \
             --url https://example.com --auto-approve --json
         Draft plan "Checkout flow" — 4 steps:
           1. [action]    Add an item to the cart
           2. [assertion] Cart badge shows 1 item
           3. [action]    Complete checkout with a test card
           4. [assertion] Confirmation page shows an order number
         Save this plan? (I won't save until you say so.)

you    > Yes, save it.

agent  > $ agentiqa plan save --file - --json     # approved plan JSON on stdin
         Saved plan tp_9f3c… "Checkout flow" (0 lint warnings)
         $ agentiqa run --plan-id tp_9f3c… --json
         PASSED · Checkout flow · 42s
         run: https://web.agentiqa.com/projects/proj_…/test-plans-v2/tp_9f3c…/history/run_…

you    > Show the last few runs.

agent  > $ agentiqa runs get tp_9f3c… --limit 5 --json
         tp_9f3c… "Checkout flow" — 3 runs: passed, passed, failed

Criteria stay engine-authored. The engine writes each step's machine-checkable criteria — the expected value, match type, and grounding. You and the agent curate the prose and structure (title, labels, step wording, ordering) but never hand-write those typed fields. When a criterion's meaning needs to change, the agent re-explores rather than editing the assertion by hand.

The plan id is the shared handle

Plans are shared account state, not a per-surface artifact. The tp_… id your agent saves opens in the web app immediately, and a plan authored in the web app is agentiqa plan get-able by id from your agent. Hand an id in either direction — you never copy a whole plan between surfaces.

Labels

Labels group a project's plans so CI can run a subset: agentiqa run --label-ids a,b runs every plan carrying any of the given labels. Labels are opaque lbl_… ids — your agent discovers them with agentiqa labels list (and can mint one with agentiqa labels create <name> when none fits), then attaches one by including it in a plan's labels array when it saves. A freshly created plan has no labels, so it runs fine by id but is skipped by a label-selected CI run until you attach the right label. An unknown id comes back as an UNKNOWN_LABEL_IDS warning on save — a failed attach to fix and re-save. See Labels for the full picture.

Handoff to CI

The plan you author here is the same plan a pipeline gates on. Once it is saved, wire it in with agentiqa run --plan-id tp_… (or a label selector) and gate on the exit code — see CI Integration for the exit-code contract and JSON envelope, and the GitHub Action for the turnkey wrapper. Authoring is interactive and curated; CI is headless and deterministic — same plans, same engine.

Consuming the docs directly

Any agent (with or without the skill) can read these docs as plain text:

• /llms.txt — a machine-readable index of every page.
• /llms-full.txt — the entire docs corpus as one document.
• Append .md to any docs URL for that page as markdown (e.g. /docs/ci.md).

Because the CLI and Action references are generated from the code and the prose is audited nightly, the skill delegates to /llms-full.txt for freshness — when the bundled references and the live docs disagree, the live docs win.