> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Orq Skills for code assistants

> Install Orq Skills and slash commands in Claude Code, Cursor, Codex, and other AI assistants to run agent, evaluation, and trace workflows.

## Overview

**Orq Skills** are pre-built, reusable workflows from the [orq-ai/assistant-plugins](https://github.com/orq-ai/assistant-plugins) repository. They come in two forms:

* **Skills**: multi-step workflows that require reasoning, such as building an agent, running an experiment, or analyzing trace failures.
* **Commands**: quick slash-command actions for immediate results, such as listing traces or showing analytics.

Both are built on the [Agent Skills](https://agentskills.io) standard format, which means they work with any compatible assistant: [Claude Code](/ai-studio/integrations/code-assistants/claude-code), [Cursor](/ai-studio/integrations/code-assistants/cursor), Gemini CLI, and others. Each skill encodes best practices from prompt engineering, agent design, evaluation methodology, and experimentation into a repeatable, triggered workflow.

## Prerequisites

* An active **Orq.ai** account
* An [API key](/ai-studio/organization/api-keys)
* The **Orq MCP** server connected to the assistant (see [MCP Quickstart](/ai-studio/integrations/code-assistants/orq-mcp))

## Installation

Choose the option that matches the assistant used:

<CodeGroup>
  ```bash Claude Code plugin theme={"theme":{"light":"github-light","dark":"github-dark"}}
  # Installs skills, commands, agents, and the MCP server in one step
  claude plugin marketplace add orq-ai/assistant-plugins
  claude plugin install orq-skills@orq-claude-plugin
  ```

  ```bash Codex theme={"theme":{"light":"github-light","dark":"github-dark"}}
  # Skills (writes to ~/.agents/skills/, which Codex scans by default)
  npx skills add orq-ai/assistant-plugins --agent codex -g -y

  # orq.ai MCP server (writes [mcp_servers.orq-workspace] to ~/.codex/config.toml)
  codex mcp add orq-workspace \
    --url https://my.orq.ai/v2/mcp \
    --bearer-token-env-var ORQ_API_KEY
  ```

  ```bash npx skills CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  # Installs skills only: works with Cursor, Gemini CLI, and other compatible assistants
  npx skills add orq-ai/assistant-plugins
  ```
</CodeGroup>

<Note>
  Use **one path only**. The Claude Code plugin install includes the MCP server. Running the Claude Code plugin path alongside any other path will install the MCP server twice. Commands (`/orq:quickstart`, `/orq:workspace`, and others) and agents are only available with the Claude Code plugin.
</Note>

## Verify

**Claude Code:** Run the interactive onboarding command to confirm everything is working:

```
/orq:quickstart
```

**Cursor, Gemini CLI, and others:** Describe a task (e.g., "list my Orq.ai agents") and confirm the skill responds correctly.

## Commands

Quick-action slash commands available in [Claude Code](/ai-studio/integrations/code-assistants/claude-code). Use `/orq:<command>` to trigger them.

| Command | Description | Usage |
| - | - | - |
| **quickstart** | Interactive onboarding: credentials, MCP setup, skills tour | `/orq:quickstart` |
| **workspace** | Workspace overview: [Agents](/ai-studio/ai-engineering/build-agents), [Deployments](/ai-studio/ai-engineering/deployments), [Prompts](/ai-studio/prompts/prompts), [Datasets](/ai-studio/optimize/datasets), [Experiments](/ai-studio/optimize/experiments) | `/orq:workspace [section]` |
| **traces** | Query and summarize [Traces](/ai-studio/observability/traces) with filters | `/orq:traces [--deployment name] [--status error] [--last 24h]` |
| **models** | List available AI models by provider | `/orq:models [search-term]` |
| **analytics** | Usage [Analytics](/ai-studio/observability/quickstart): requests, cost, tokens, errors | `/orq:analytics [--last 24h] [--group-by model]` |
| **orq-manage-skills** | Manage **Orq.ai** [Skills](/ai-studio/ai-engineering/skills) (platform entities): list, get, create, update, retire, delete | `/orq:orq-manage-skills [list\|get\|create\|update\|retire\|delete] [name-or-id]` |

## Skills

Skills are triggered by describing what is needed. The assistant picks the right skill automatically.

| Skill | Description | Source |
| - | - | - |
| **build-agent** | Design, create, and configure an **Orq.ai** [Agent](/ai-studio/ai-engineering/build-agents) with tools, instructions, [Knowledge Bases](/ai-gateway/features/knowledge-bases), and [Memory](/ai-studio/ai-engineering/memory-stores#manage-memories-and-documents) | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-build-agent/SKILL.md) |
| **build-evaluator** | Create validated LLM-as-a-Judge [Evaluators](/ai-studio/marketplace#evaluators) following evaluation best practices | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-build-evaluator/SKILL.md) |
| **recommend-evaluators** | Recommend the [Evaluators](/ai-studio/marketplace#evaluators) an agent is missing, from its traces or, with no traffic, from its instructions and config; skips the ones already attached and creates each only after approval | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-recommend-evaluators/SKILL.md) |
| **evaluator-alignment** | Align an existing LLM judge (boolean, categorical, or numeric) to human judgment: measure how often it changes its mind, group the least reliable cases, rewrite the judge prompt, and recreate the [Evaluator](/ai-studio/marketplace#evaluators) after approval | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-evaluator-alignment/SKILL.md) |
| **analyze-traces** | Read production [Traces](/ai-studio/observability/traces), identify what is failing, build failure taxonomies, and categorize issues | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-analyze-traces/SKILL.md) |
| **improve-agent** | Improve an underperforming **Orq.ai** [Agent](/ai-studio/ai-engineering/build-agents) or [Deployment](/ai-studio/ai-engineering/deployments): rewrite its instructions against a prompting framework, or move a configuration knob, grounded in the error-analysis file `analyze-traces` writes | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-improve-agent/SKILL.md) |
| **run-experiment** | Create and run **Orq.ai** [Experiments](/ai-studio/optimize/experiments): compare configurations with specialized agent, conversation, and RAG evaluation | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-run-experiment/SKILL.md) |
| **generate-synthetic-dataset** | Generate and curate evaluation [Datasets](/ai-studio/optimize/datasets): structured generation, quick from description, expansion, and dataset maintenance | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-generate-synthetic-dataset/SKILL.md) |
| **invoke-deployment** | Invoke **Orq.ai** [Deployments](/ai-studio/ai-engineering/deployments), [Agents](/ai-studio/ai-engineering/build-agents), and models via the Python SDK or HTTP API, with correct variable substitution, streaming, and identity tracking | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-invoke-deployment/SKILL.md) |
| **setup-observability** | Instrument LLM applications with Orq.ai tracing. Covers AI Gateway (zero-code traces) and OpenTelemetry/OpenInference. Guides from framework detection through baseline verification to trace enrichment | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-setup-observability/SKILL.md) |
| **compare-agents** | Run cross-framework agent comparisons: compare any combination of Orq.ai, LangGraph, CrewAI, OpenAI Agents SDK, or Vercel AI SDK agents head-to-head on the same dataset using `evaluatorq` | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-compare-agents/SKILL.md) |
| **red-team** | Run adversarial attacks against deployed agents or static datasets with the `evaluatorq` red team CLI. Covers OWASP-ASI (agentic: goal hijacking, tool misuse) and OWASP-LLM (model-level: prompt injection, system prompt leakage) | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-red-team/SKILL.md) |
| **evaluatorq** | Write and run `evaluatorq` evaluation scripts (Python or TypeScript) for a single agent or deployment. Supports custom scorers, dataset-driven runs, and LLM-as-a-Judge [Evaluators](/ai-studio/marketplace#evaluators) | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/evaluatorq/SKILL.md) |
| **simulate-agent** | Run multi-turn simulations with `evaluatorq` primitives (`simulate()`, `generate_and_simulate()`, `wrap_simulation_agent()`): drive an agent under test with a simulated user and score each turn with a built-in judge | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-simulate-agent/SKILL.md) |
| **manage-skills** | List, inspect, create, update, retire, and delete **Orq.ai** [Skills](/ai-studio/ai-engineering/skills) (platform entities). Handles naming rules, template integration (`{{skill.key}}`), reference scanning, and safe deletion | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-manage-skills/SKILL.md) |
| **create-skill** | Build or update an agent skill from an API, CLI, or MCP surface: probe the surface, verify each claim, write a tested contract, and register it | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/create-skill/SKILL.md) |
| **shared** | Reference bundle the other skills read: the verified `orq` CLI trace query contract and the run-key preflight. Not invoked on its own | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-shared/SKILL.md) |
| **orq-cli** | Drive the `orq` command-line interface: install check, authentication, workspace selection, `orq doctor` troubleshooting, and read/write commands with JSON output | [SKILL.md](https://github.com/orq-ai/assistant-plugins/blob/main/skills/orq-cli/SKILL.md) |

See [Orq for coding agents](/ai-studio/integrations/code-assistants/orq-for-coding-agents) for how Skills, the CLI, and MCP divide the work.

## Example workflows

### Instrument an existing app

```
"Add orq.ai tracing to my app"                 → setup-observability
/orq:traces --last 1h                           # Verify traces are flowing
"Analyze these failures"                        → analyze-traces
```

### Build a new agent

```
"I need a customer support agent"              → build-agent
"Which evaluators should it have?"             → recommend-evaluators
"Create test cases for it"                     → generate-synthetic-dataset
"Build an evaluator for response accuracy"     → build-evaluator
"Run an experiment to get a baseline"          → run-experiment
```

### Debug production issues

```
/orq:traces --status error --last 24h          # Find errors
"Analyze these failures"                       → analyze-traces
"Fix the prompt based on the failure analysis" → improve-agent
"Re-run the experiment to verify the fix"      → run-experiment
```

### Improve an existing agent

```
/orq:analytics --group-by deployment           # Spot high error rates
"Analyze traces for the checkout agent"        → analyze-traces
"Build evaluators for the failure modes"       → build-evaluator
"Generate a dataset covering edge cases"       → generate-synthetic-dataset
"Run an experiment and compare"                → run-experiment
"Optimize the prompt based on results"         → improve-agent
```

### Improve an existing prompt

```
"My prompt isn't performing well, help me improve it" → improve-agent
"Create test cases to compare before and after"       → generate-synthetic-dataset
"Build an evaluator for a specific dimension"         → build-evaluator
"Run an experiment: current vs optimized prompt"      → run-experiment
"Refine the prompt based on failure cases"            → improve-agent
```

### Red team and simulate a new agent

```
"I need to simulate user conversations with my agent"   → simulate-agent
"Run adversarial tests against it"                      → red-team
"Build evaluators for the discovered failure modes"     → build-evaluator
"Run an experiment to compare patched vs original"      → run-experiment
```

### Evaluate an agent with custom scorers

```
"Write an evaluatorq script for my support agent"       → evaluatorq
"Simulate edge-case personas against it"                → simulate-agent
"Red team the agent on prompt injection"                → red-team
```

## Resources

<Card title="orq-ai/assistant-plugins" icon="github" href="https://github.com/orq-ai/assistant-plugins">
  Source repository for all skills, commands, and agents
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.