---
title: Skills
description: Practical guide to packaged agent-qa skills and the CLI command that lists them for AI agents.
---



agent-qa packages reusable agent instructions for authoring, debugging, and result triage. List them from the [CLI](/docs/agent-qa/cli):

<CommandSnippet command="agent-qa skills" />

For machine-readable output:

<CommandSnippet command="agent-qa skills --json" />

The JSON output returns the resolved skills directory. When you inspect or manually audit installed files, review whole skill directories, not only `SKILL.md`, because packaged skills can include references and client-specific agent metadata.

## Skill directory resolution [#skill-directory-resolution]

The `agent-qa skills` command resolves skills in this order:

1. `package`: the package root has a `skills` directory with skill subdirectories containing `SKILL.md`.
2. `source`: source checkout fallback at `../../skills` from the package root.
3. `missing`: no usable packaged or source skills directory was found.

When skills are missing, non-JSON output writes an error like `agent-qa skills not found at ...` and sets exit code 1. JSON output prints a payload with `path`, `source`, and empty `skills`, then also sets exit code 1.

## Install skills into agent clients [#install-skills-into-agent-clients]

Use the cross-agent Skills CLI to install the packaged agent-qa skills from the public repository:

<CommandSnippet command="npx skills add vostride/agent-qa --skill agent-qa-authoring --skill agent-qa-debug-fix --skill agent-qa-result-triage" />

To install every packaged agent-qa skill:

<CommandSnippet command="npx skills add vostride/agent-qa --skill '*'" />

The package currently includes `agent-qa-authoring`, `agent-qa-debug-fix`, and `agent-qa-result-triage`. Run `agent-qa skills --json` when you want to inspect the packaged skills that shipped with your installed `agent-qa` version; use `npx skills add` when you want the client install step handled for you.

### Agent-specific installs [#agent-specific-installs]

Install for one or more detected agents:

```bash
npx skills add vostride/agent-qa --skill '*' --agent codex
npx skills add vostride/agent-qa --skill '*' --agent claude-code
npx skills add vostride/agent-qa --skill '*' --agent opencode
npx skills add vostride/agent-qa --skill '*' --agent codex --agent claude-code --agent opencode
```

Use `--global` for a user-wide install, or omit it for a project install:

```bash
npx skills add vostride/agent-qa --skill '*' --agent codex --global
npx skills add vostride/agent-qa --skill '*' --agent claude-code --global
npx skills add vostride/agent-qa --skill '*' --agent opencode --global
```

Use `--copy` if your environment should copy skill files instead of symlinking them, and `--yes` for non-interactive setup:

```bash
npx skills add vostride/agent-qa --skill '*' --agent codex --global --copy --yes
```

Codex global skills still load from `$CODEX_HOME/skills`, which is usually `~/.codex/skills`; project installs use `.agents/skills/`. Claude Code uses `.claude/skills` for project installs and `~/.claude/skills` globally. OpenCode can use `.agents/skills`, `.opencode/skills`, or `~/.config/opencode/skills` depending on scope and client configuration.

Claude Code can invoke skills automatically from the description, or directly with `/agent-qa-authoring`, `/agent-qa-debug-fix`, and `/agent-qa-result-triage`. Codex and OpenCode can invoke them by name, such as `$agent-qa-authoring` or `$agent-qa-result-triage`, once their client has loaded installed skills.

To keep skill use explicit in OpenCode, allow the skill tool in `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "skill": {
      "agent-qa-*": "allow"
    }
  }
}
```

### Cross-client project install [#cross-client-project-install]

Use `.agents/skills` when a repository is shared by Codex, OpenCode, and other clients that support the neutral agent-compatible location. Use `.claude/skills` when a repository is primarily shared by Claude Code users. The `npx skills add` installer can target those agents directly, so prefer it over hand-copying directories.

## `agent-qa-authoring` [#agent-qa-authoring]

Use `agent-qa-authoring` when creating, editing, validating, or running tests, suites, or hooks.

The skill prefers [MCP tools](/docs/agent-qa/mcp) before CLI or YAML fallback:

* Discover the local surface with `agent_qa_discover`.
* Inspect config with `agent_qa_get_config`.
* Generate IDs with `agent_qa_generate_id` or fallback to `agent-qa ids generate <type>`.
* Validate definitions with `agent_qa_validate_definition`, `agent_qa_validate_test`, or `agent_qa_validate_suite`.
* Prefer `agent_qa_create_test`, `agent_qa_update_test`, `agent_qa_create_suite`, `agent_qa_update_suite`, and hook mutation tools before editing files directly.

Use CLI/YAML fallback only when MCP tools are unavailable, and keep files inside configured workspace patterns.

## `agent-qa-debug-fix` [#agent-qa-debug-fix]

Use `agent-qa-debug-fix` after a failed run when a code, YAML, hook, infrastructure, or product issue needs a patch.

The workflow starts from evidence:

* `agent_qa_get_run`
* `agent_qa_get_run_steps`
* `agent_qa_get_run_artifact`
* `agent_qa_get_run_logs`
* `agent_qa_get_run_execution_logs`
* `agent_qa_classify_failure`

Treat the classifier result as a hypothesis, inspect local files directly, apply the smallest change that explains the evidence, validate edited YAML, and rerun the narrowest affected test, suite, hook, or unit test.

## `agent-qa-result-triage` [#agent-qa-result-triage]

Use `agent-qa-result-triage` when the goal is evidence-backed classification rather than an immediate patch.

The skill gathers run detail, steps, artifacts, logs, and execution logs, then calls `agent_qa_classify_failure`. It returns category, confidence, evidence, likely fix area, and next action. If code changes are needed, hand off to `agent-qa-debug-fix` after triage is complete.

Fixed categories include `timeout`, `appium_startup`, `browser_disconnect`, `element_not_found`, `assertion_failure`, `hook_failure`, `infrastructure`, and `unknown_failure`.

## Use with MCP and CLI [#use-with-mcp-and-cli]

Prefer MCP tools for live project state and dashboard-backed authoring. Use CLI fallback for simple local checks such as `agent-qa validate`, `agent-qa ids validate <type> <id> --json`, or `agent-qa skills --json` when MCP is unavailable.

## Updating installed skills [#updating-installed-skills]

After upgrading `agent-qa`, run `npx skills update` or rerun the matching `npx skills add vostride/agent-qa ...` command. Replace or update the old directories as a unit so `SKILL.md`, `references/`, and `agents/` stay in sync.

Review the files before enabling auto-approval in any agent client. Skills are instructions plus optional supporting files, and they should be treated as part of your local automation surface.