/xurl

name: xurl
description: >-
  Use xurl to access AI agent conversations via agents:// URIs. Invoke when the user:
  gives an agents:// URI, a provider shorthand like provider/..., or a bare thread/session ID;
  mentions conversations, threads, or sessions from any AI coding agent;
  wants to search, read, summarize, compare, or continue agent threads;
  asks what they worked on, what an agent said, or references past agent interactions;
  wants to delegate work to or start a conversation in another agent.

When to Use

Trigger this skill when the user's intent involves **any** AI agent conversation — past, present, or to be created. Examples of natural language triggers:

• Gives an `agents://` URI, provider shorthand (`provider/...`), or a bare thread/session ID
• "Read/show/open this thread/session/conversation ..."
• "What did I discuss with [agent] about ...?"
• "Summarize my last [agent] session"
• "What was I working on in [agent]?"
• "Search my agent history for ..."
• "Find the conversation where I fixed the auth bug"
• "Continue my [agent] conversation about ..."
• "Send this to [agent] for review" / "Ask [agent] to ..."
• "What subagents were spawned in that thread?"
• "Compare what different agents suggested"
• "Check if I've discussed X before across agents"

`[agent]` can be any AI coding agent name (e.g. codex, claude, copilot, cursor, etc.). xurl supports a growing list of providers — just try it. If a provider is not yet supported, xurl will return a clear error.

When NOT to Use

• General questions about AI agents that don't involve their conversation data
• Tasks fully within the current agent session with no cross-agent context needed
• Questions about agent capabilities rather than their conversation history

URI Assembly Guide

You are responsible for constructing the correct `xurl` command from the user's input. The user will rarely give a complete `agents://` URI — you must assemble it.

Decision Flow

User input → What do I have? → What do I need? → Construct URI → Run xurl

**Step 1: Identify the operation**

| User wants to... | Operation | Required info | |---|---|---| | Find/list/search conversations | Query | provider OR path; optional keyword | | Read/show/summarize a conversation | Read | provider + conversation ID | | Inspect metadata or list children | Discover | provider + conversation ID | | Start a new conversation | Write (create) | provider; optional role | | Continue an existing conversation | Write (append) | provider + conversation ID |

**Step 2: Resolve missing information**

| You have | You're missing | Action | |---|---|---| | Nothing | Provider + ID | Query by path: `xurl 'agents://.?q=<keyword>'` to search current project across all providers | | Provider only | Conversation ID | Query the provider: `xurl <provider>` or `xurl '<provider>?q=<keyword>'`, then pick from results | | Bare thread ID only | Provider | Query by path with the ID as keyword: `xurl 'agents://.?q=<id_fragment>'`; or ask the user which provider | | Provider + keyword | Conversation ID | Search: `xurl '<provider>?q=<keyword>'`, pick matching ID from results | | Provider + ID | Nothing | Ready — construct URI directly |

**Step 3: Construct and run**

Assemble the URI: `agents://<provider>/<conversation_id>` (or shorthand `<provider>/<conversation_id>`).

Examples

User says: _"Read thread 019c871c-b1f9-7f60-9c4f-87ed09f13592"_ → You have a bare ID but no provider. Search: `xurl 'agents://.?q=019c871c'`, identify the provider from results, then: `xurl <provider>/019c871c-b1f9-7f60-9c4f-87ed09f13592`

User says: _"What did I discuss about refactoring in codex?"_ → You have provider (codex) + keyword (refactoring). Search: `xurl 'codex?q=refactoring'`, pick the best match, then read: `xurl codex/<id>`

User says: _"Summarize my last copilot session"_ → You have provider (copilot). List recent: `xurl copilot`, take the first result, then read: `xurl copilot/<id>`

User says: _"Have codex review this patch"_ → Write operation with provider (codex). Create: `xurl codex -d "Review this patch"` (or with role: `xurl codex/reviewer -d "Review this patch"`)

User says: _"Check if I've discussed the migration across any agent"_ → Cross-agent search. Query: `xurl 'agents://.?q=migration'`

Prerequisites

Verify xurl is installed before running any command:

xurl --version

If not found, install via the method matching the user's environment:

brew tap xuanwo/tap && brew install xurl   # Homebrew
cargo install xurl-cli                      # Cargo / Rust
uv tool install xuanwo-xurl                 # Python / uv
npm install -g @xuanwo/xurl                 # npm / Node

Workflows

1. Query — Find Conversations

List recent threads from a provider:

xurl codex

Search by keyword with optional limit (default 10):

xurl 'agents://codex?q=refactor&limit=5'

Search by project directory (across providers):

xurl 'agents://.?q=migration'                      # current directory
xurl 'agents:///Users/alice/work/repo?limit=5'     # absolute path
xurl 'agents://~/work/repo?providers=codex,claude'  # filter providers

Query by role:

xurl codex/reviewer

Query results include reduced thread metadata (e.g. `payload.git.branch`, `cwd`) for quick inspection.

2. Read — Display a Conversation

xurl codex/<conversation_id>

Output is Markdown: YAML frontmatter (metadata) followed by numbered timeline sections (User/Assistant message pairs).

Save to file:

xurl -o /tmp/conversation.md codex/<conversation_id>

3. Discover — Inspect Metadata and Children

xurl -I codex/<conversation_id>

Returns frontmatter with flattened metadata and discovery links (`subagents`, `entries`). Use returned URIs for drill-down:

xurl codex/<main_id>/<child_id>

4. Write — Start or Continue Conversations

Create:

xurl codex -d "Start a new con