orq

Orq.ai Agent Skills

Agent Skills for the full Build → Evaluate → Optimize lifecycle of LLM pipelines on orq.ai.

Skills are multi-step workflows that require reasoning (e.g. build an agent, run an experiment);

Commands are quick actions for immediate results (list traces, show analytics).

Each skill encodes best practices from prompt engineering, agent design, evaluation methodology, and experimentation into repeatable workflows. From creating agents and writing prompts, through trace analysis and dataset generation, to running validated experiments and iterating on results.

Built on the Agent Skills standard format, so it works with any compatible agent (Claude Code, Cursor, Gemini CLI, and others).

Setup

Prerequisites

• An orq.ai account

• An API key from Settings → API Keys

  export ORQ_API_KEY=your-key-here
  

Quick reference

Tool	Recommended install
Claude Code (CLI)	Claude Code plugin
Claude Cowork (Desktop)	Claude Cowork install guide
Cursor	Cursor install guide
Codex	Codex install
Gemini CLI, Cline, Copilot, Windsurf	Skills-only install (npx)
Any MCP-capable client	MCP-only install

---

Claude Code plugin

Use this if you want easy access to all components — skills, MCP tools, and trace hooks — in one install. Installed via the orq-ai/assistant-plugins marketplace.

# In Claude Code:
/plugin marketplace add orq-ai/assistant-plugins

# Install all 3 plugins
/plugin install orq-skills@assistant-plugins
/plugin install orq-mcp@assistant-plugins
/plugin install orq-trace@assistant-plugins

Plugin	What it gives you
orq-skills	Skills, commands, and agents for the Build → Evaluate → Optimize lifecycle
orq-mcp	MCP server registration — Claude can call orq.ai APIs directly
orq-trace	OTLP tracing hooks that capture Claude Code sessions into orq.ai

Verify with the interactive onboarding — checks ORQ_API_KEY, MCP reachability, and credentials:

/orq:quickstart

---

Codex

# 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

Restart Codex. Verify with /mcp (lists orq-workspace) or the prompt "List my orq.ai agents".

Codex plugins don't support slash commands, so /orq:* shortcuts are Claude Code-only — in Codex, describe tasks in natural language to trigger skills.

---

Skills-only install

Use this when you're on a non-Claude agent (Cursor, Gemini CLI, Cline, Copilot CLI, Codex, Windsurf, and many others), or when you only want the skills without MCP/trace hooks.

npx skills add orq-ai/assistant-plugins

Auto-detects your agent and writes skills to the correct location (e.g. .claude/skills/, .cursor/rules/). Run inside your project directory.

Agent-specific install guides:

• Cursor plugin
• Codex plugin
• Manual clone (Claude Code)

---

MCP-only install

Use this when you want orq.ai MCP tools in a tool that isn't the Claude Code plugin (Claude Desktop, other MCP-capable clients, or manual Claude Code setup).

# Manual registration in Claude Code
claude mcp add --transport http orq-workspace https://my.orq.ai/v2/mcp \
  --header "Authorization: Bearer ${ORQ_API_KEY}"

For other clients, most accept a JSON block with url + headers:

{
  "mcpServers": {
    "orq-workspace": {
      "type": "http",
      "url": "https://my.orq.ai/v2/mcp",
      "headers": { "Authorization": "Bearer ${ORQ_API_KEY}" }
    }
  }
}

---

Manifest validation

tests/scripts/validate-plugin-manifests.sh

---

Commands

Quick-action slash commands. Use /orq:<command> in Claude Code.