> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testsprite.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Coding Agent Integration
> Let your coding agent drive the TestSprite verification loop on its own — create, run, read failures, fix, and rerun without a human in the middle.
## What the skills do
`testsprite agent install` writes two **skill files** into your repository by default:
* **`testsprite-verify`** — the verification-loop skill. Once in place, your coding agent discovers that this project is TestSprite-tested and knows exactly how to drive the full loop on its own: describe a behavior as a plan file and create a test; trigger a real cloud run and wait for the verdict; on failure, pull one self-consistent bundle — failing step, DOM snapshots rendered as text, root-cause hypothesis, and recommended fix target; edit the code and replay cheaply.
* **`testsprite-onboard`** — the onboarding skill. Guides the agent through initial project setup (running `testsprite setup`, creating the first project and test) the first time TestSprite is used in a repo.
Both skills are **pure-local**: `agent install` reads and writes only to your filesystem. It makes no network requests and requires no credentials.
**We strongly recommend installing the skills.** It's the fastest way to get consistent results — they teach your agent exactly when to verify, how to read the failure bundle, and how to loop until the test is green, so you don't have to spell it out each time. Run `testsprite setup` (or `testsprite agent install`) once per project.
## Install the skills
```bash theme={null}
testsprite agent install --target claude
```
Run this from your project root. The skill files (both `testsprite-verify` and `testsprite-onboard` by default) are written immediately.
**Flags:**
| Flag | Description |
| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--target ` | Agent target: `claude`, `cursor`, `cline`, `antigravity`, `kiro`, `windsurf`, `copilot`, `codex`. Comma-separated or repeated. Prompts if omitted in a terminal. |
| `--skill ` | Skill to install: `testsprite-verify`, `testsprite-onboard`. Comma-separated or repeated. Default: both. |
| `--dir ` | Project root to write the skill(s) into (default: current directory). |
| `--force` | Overwrite an existing skill file. A `.bak` backup is kept. For `codex`, replaces only the managed section — your other `AGENTS.md` content is preserved. |
If `--target` is omitted in an interactive terminal, the CLI prompts for one (default `claude`). Outside a terminal — CI, a script, a piped invocation — it skips the prompt and defaults straight to `claude`, printing an `[info]` line to stderr so the choice is visible in logs.
To install for multiple agents at once:
```bash theme={null}
testsprite agent install --target claude --target cursor
```
Or comma-separated:
```bash theme={null}
testsprite agent install --target claude,cursor
```
If the destination file already exists and differs from the current skill, the install is blocked until you pass `--force`. The original is always backed up as `.bak`.
## Supported agents
| Target | Status | Mode | Landing path |
| :------------ | :---------------------- | :-------------- | :--------------------------------------------- |
| `claude` | GA | own-file | `.claude/skills/{skill}/SKILL.md` |
| `antigravity` | experimental | own-file | `.agents/skills/{skill}/SKILL.md` |
| `cursor` | experimental | own-file | `.cursor/rules/{skill}.mdc` |
| `cline` | experimental | own-file | `.clinerules/{skill}.md` |
| `kiro` | experimental | own-file | `.kiro/skills/{skill}/SKILL.md` |
| `windsurf` | experimental | own-file | `.windsurf/rules/{skill}.md` |
| `copilot` | experimental | own-file | `.github/instructions/{skill}.instructions.md` |
| `codex` | experimental | managed-section | `AGENTS.md` |
`{skill}` is `testsprite-verify` or `testsprite-onboard`. Own-file targets write one file per installed skill; only the requested skill(s) land, so `--skill testsprite-verify` writes just that one file.
For `codex`, every installed skill is merged into one managed section inside `AGENTS.md`. Your existing content in that file is not modified — only the TestSprite section is added or updated.
## Listing targets
To see all supported targets, their current status, and where each skill lands:
```bash theme={null}
testsprite agent list
```
```text theme={null}
TARGET SKILL STATUS MODE PATH
claude testsprite-verify GA own-file .claude/skills/testsprite-verify/SKILL.md
claude testsprite-onboard GA own-file .claude/skills/testsprite-onboard/SKILL.md
antigravity testsprite-verify experimental own-file .agents/skills/testsprite-verify/SKILL.md
antigravity testsprite-onboard experimental own-file .agents/skills/testsprite-onboard/SKILL.md
cursor testsprite-verify experimental own-file .cursor/rules/testsprite-verify.mdc
cursor testsprite-onboard experimental own-file .cursor/rules/testsprite-onboard.mdc
cline testsprite-verify experimental own-file .clinerules/testsprite-verify.md
cline testsprite-onboard experimental own-file .clinerules/testsprite-onboard.md
kiro testsprite-verify experimental own-file .kiro/skills/testsprite-verify/SKILL.md
kiro testsprite-onboard experimental own-file .kiro/skills/testsprite-onboard/SKILL.md
windsurf testsprite-verify experimental own-file .windsurf/rules/testsprite-verify.md
windsurf testsprite-onboard experimental own-file .windsurf/rules/testsprite-onboard.md
copilot testsprite-verify experimental own-file .github/instructions/testsprite-verify.instructions.md
copilot testsprite-onboard experimental own-file .github/instructions/testsprite-onboard.instructions.md
codex testsprite-verify experimental managed-section AGENTS.md
codex testsprite-onboard experimental managed-section AGENTS.md
```
## Checking skill health
Once skills are installed, confirm they're still in sync with the CLI version that installed them — useful right after upgrading the CLI, or in CI to catch a hand-edited skill file:
```bash theme={null}
testsprite agent status
```
Each installed skill file is classified into one state:
| State | Meaning |
| :--------- | :-------------------------------------------------------------------------- |
| `ok` | Matches exactly what this CLI version would install |
| `stale` | Installed by an older CLI version whose canonical content has since changed |
| `modified` | Edited by hand after install |
| `unmarked` | Present, but predates the provenance marker this check relies on |
| `absent` | Not installed for this target/skill |
| `corrupt` | `codex` only — the managed `AGENTS.md` section's sentinels are malformed |
Pass `--dir ` to inspect a project other than the current directory. `agent status` exits `1` when anything needs attention (any state other than `ok` or `absent`), so it's CI-gateable:
```bash theme={null}
testsprite agent status --dir ./apps/web && echo "skills are in sync"
```
## One-shot onboarding
`testsprite setup` configures your API key **and** installs the skills in a single step — the recommended path when you're setting up a project for the first time.
```bash theme={null}
testsprite setup
```
`setup` chains credential configuration → identity verification → agent skill install, and prints a unified summary.
The full onboarding walkthrough, including the non-interactive (`--from-env --yes`) form for CI bootstrap.
## How the agent uses it
Once the skill files are in place, a coding agent like Claude Code picks them up automatically when it enters your project. It knows to:
1. **Create** a test from a plan you or the agent authors — describing the behavior in intent terms, not driver code.
2. **Run** it against the live app and wait for a pass/fail verdict.
3. On failure, **pull the failure bundle** — one consistent artifact with everything needed to diagnose and fix.
4. **Fix** the code, then **rerun** as a cheap verbatim replay.
The command sequence the agent follows:
```bash theme={null}
# Create a test from a plan file and immediately run it
testsprite test create \
--project proj_8f0f6 --type frontend \
--plan-from ./checkout-flow.plan.json \
--run --wait --output json
# On failure: pull the self-consistent failure bundle
testsprite test failure get test_3a9f21c7 \
--out ./.testsprite/failure
# After fixing the code: replay cheaply (no credit for verbatim FE rerun)
testsprite test rerun test_3a9f21c7 --wait
```
Exit 0 means the test passed and is banked into the durable suite. The agent doesn't need to know how the test was driven — only what a real user experienced.
Every passing rerun compounds your coverage. The agent builds a lasting record of every requirement it has verified — far bigger than any context window.
## Where to Go Next
Walk through the full create → run → fix loop end-to-end
Gate your pipeline on TestSprite results
All flags and modes for triggering and waiting on runs
Full flag reference for every command