AI & Agent Enablement

How AI coding agents and evaluation teams can consume these docs directly, build a CertiQA skill, and connect to the CertiQA MCP server to author projects, suites, cases, and steps in the recommended format.

Why This Page Exists

Teams evaluating CertiQA increasingly do it with an AI agent first: pointed at the docs, asked to summarize what the platform does, or asked to actually wire up a test project. This page is CertiQA’s answer to that – three things, in order: machine-readable docs an agent can fetch without running JavaScript, a ready-made “skill” an agent framework can load, and the MCP server that lets an agent create real projects, suites, cases, and steps in your CertiQA instance.

🤖 Built for AI Agents

• Machine-readable docs: /llms.txt and /llms-full.txt, following the llms.txt convention (llmstxt.org).
• A working example skill: /skills/certiqa-test-authoring/SKILL.md.
• A CertiQA MCP server with 36 tools for projects, suites, cases, CertiBlocks, runs, schedules, failure triage, artifacts, and event queues.

1. Machine-Readable Docs (llms.txt)

This docs site is a single-page app, so a plain HTTP fetch of a page URL returns an empty shell – fine for a browser, useless for an agent that doesn’t execute JavaScript. To fix that, every build of this site also publishes two plain-text files at its root, generated directly from the same content that drives these guides (so they can’t drift out of sync with what you’re reading now):

File	Purpose
/llms.txt	A short index, per the llmstxt.org convention: what CertiQA is, links to the full docs dump, the example skill, and the standalone deployment guides.
/llms-full.txt	The complete docs corpus as plain text – every guide across all 9 surfaces, the functional REST API reference, and the full MCP server & tools reference.

Point an agent at /llms.txt first; it will follow the link to llms-full.txt for the complete picture. Internal engineering and sales-only documents are deliberately excluded from both files – this is the same customer-facing content already in these guides, just in a form an agent can read directly.

# Quick check from a shell
curl -s https://docs.certiqa.app/llms.txt
curl -s https://docs.certiqa.app/llms-full.txt | head -100

2. Building a CertiQA Skill

A “skill” is a packaged, reusable set of instructions an agent framework (Claude, or any framework that supports the same convention) loads before doing a particular kind of task. CertiQA ships a real, working one – not a template – at:

/skills/certiqa-test-authoring/SKILL.md

It teaches an agent the project -> suite -> case -> steps hierarchy, when to reach for a CertiBlock instead of duplicating steps, and – most importantly – how to write steps in CertiQA’s recommended IR format rather than the bare minimum one (see Section 4 below). Fetch it directly, or point your agent’s skill-loading mechanism at that URL; it needs no modification to work against your own CertiQA instance beyond the MCP connection in Section 3.

Writing your own skill

• Reuse the MCP connection snippet from Section 3 verbatim – don’t re-derive it.
• Reference the certiqa://schema/ir MCP resource for the canonical step schema instead of hardcoding field lists that can drift.
• Link back to /llms-full.txt for anything domain-specific your skill doesn’t need to restate (assertions reference, CI/CD gates).

3. Connecting to the CertiQA MCP Server

The CertiQA MCP server (@certiqa/mcp-server) exposes 36 tools over stdio/SSE – any MCP-capable client (Claude Desktop, Cursor, or an autonomous triage agent using the MCP SDK) can launch it as a child process. Add this to your client’s MCP config:

{
  "mcpServers": {
    "certiqa": {
      "command": "npx",
      "args": ["-y", "@certiqa/mcp-server"],
      "env": {
        "CERTIQA_BASE_URL": "https://api.certiqa.app",
        "CERTIQA_API_TOKEN": "agt_cust_your_scoped_token"
      }
    }
  }
}

CERTIQA_BASE_URL (also accepted as CERTIQA_API_URL) points at your tenant’s API; CERTIQA_API_TOKEN (also accepted as CERTIQA_MCP_TOKEN) is a scoped token from Settings -> API Tokens. See the MCP Server & Tools reference (in llms-full.txt) for the full tool list, or the Functional API Reference for the underlying REST endpoints each tool wraps.

4. Building in the Recommended Format

The bare-minimum way to author a step – a single CSS selector – works, but it is the most brittle possible input and the first thing to break when the UI changes. The recommended format instead uses locatorCandidates (a ranked list of resilient locators) plus generatedBy and confidence, so CertiQA’s self-healing and review tooling can tell an AI-authored step apart from a human one and treat low-confidence steps accordingly. The full schema is published as the certiqa://schema/ir MCP resource – validate against it before calling create_case.

{
  "action": "CLICK",
  "locatorCandidates": [
    { "strategy": "TESTID", "value": "checkout-submit", "score": 0.95 },
    { "strategy": "ROLE", "role": "button", "name": "Submit order", "score": 0.85 },
    { "strategy": "TEXT", "value": "Submit order", "exact": true, "score": 0.6 }
  ],
  "generatedBy": "AI",
  "confidence": 0.9,
  "needsGrounding": false
}

Order candidates most-resilient-first: TESTID and ROLE survive UI restyles far better than a raw CSS or XPath selector, which belongs last as a fallback, not first. The full worked example – create_project -> create_suite -> create_case (with recommended-format steps) -> add_case_to_suite -> trigger_run – is in the example skill above and in the MCP reference section of llms-full.txt.

Validate before you build

• An unsupported action or match enum value is the most common create_case failure – check the certiqa://schema/ir resource, not just the tool description, before retrying.
• create_agent_case (AI-agent conversational tests) uses a different step vocabulary than create_case (web UI tests) – they are not interchangeable.

• 🤖 Composing Agent Tests Visually — The human-driven equivalent of Section 4’s worked example, in the visual step canvas.
• 🌐 No-Code UI Step Builder — How the same steps look when built by hand in the UI, for comparison.