Skills

agent-qa packages reusable agent instructions for authoring, debugging, and result triage. List them from the CLI:

>agent-qa skills

For machine-readable output:

>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

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

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

>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:

>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

Install for one or more detected agents:

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:

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:

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:

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

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

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

The skill prefers MCP tools 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

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

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

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

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.