orq-trace

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	Claude Code plugin
Cursor	Cursor install guide
Codex	Codex install guide
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/claude-plugins marketplace.

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

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

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

---

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/orq-skills

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.

Command	What It Does	Usage
quickstart	Interactive onboarding — credentials, MCP setup, skills tour	/orq:quickstart
workspace	Workspace overview — agents, deployments, prompts, datasets, experiments	/orq:workspace [section]
traces	Query and summarize 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 — requests, cost, tokens, errors	/orq:analytics [--last 24h] [--group-by model]

Examples

/orq:workspace agents          # Show only agents
/orq:traces --status error --last 1h   # Recent errors
/orq:models gpt-4              # Search for GPT-4 variants
/orq:analytics --group-by deployment    # Cost per deployment

---

Skills

Skills are triggered by describing what you need. Claude picks the right skill automatically.