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 xurlStep 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 --versionIf 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 / NodeWorkflows
1. Query — Find Conversations
List recent threads from a provider:
xurl codexSearch 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 providersQuery by role:
xurl codex/reviewerQuery 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 conversation"
xurl codex/reviewer -d "Review this patch"Append:
xurl codex/<conversation_id> -d "Continue with the next step"With provider CLI parameters:
xurl "agents://codex?cd=%2FUsers%2Falice%2Frepo&model=gpt-5" -d "Review this"Payload from file or stdin:
xurl codex -d @prompt.txt
cat prompt.md | xurl claude -d @-Multi-Step Patterns
Find and read a conversation: xurl 'codex?q=<keyword>' → pick ID → xurl codex/<id>
Explore subagents: xurl -I codex/<id> → find child links → xurl codex/<id>/<child_id>
Cross-agent project search: xurl 'agents://.?q=<keyword>' → read from whichever provider matches
Resolve a bare thread ID: xurl 'agents://.?q=<id_fragment>' → identify provider → xurl <provider>/<id>
Command Reference
xurl [OPTIONS] <URI>| Flag | Purpose |
|---|---|
-I, --head | Frontmatter/discovery only (cannot combine with -d) |
-d, --data <DATA> | Write payload; repeatable; -d "text", -d @file, -d @- |
-o, --output <PATH> | Write output to file |
Multiple -d values are newline-joined. Path-scoped URIs are read/query only (not valid write targets).
URI Quick Reference
[agents://]<provider>[/<token>[/<child_id>]][?<query>]| Pattern | Operation | Example |
|---|---|---|
<provider> | Query recent | xurl codex |
<provider>?q=... | Keyword search | xurl 'codex?q=bug' |
<provider>/<id> | Read conversation | xurl codex/<uuid> |
<provider>/<role> | Role-scoped query | xurl codex/reviewer |
<provider>/<id>/<child> | Read subagent | xurl codex/<uuid>/<child> |
<provider> + -d | Create conversation | xurl codex -d "..." |
<provider>/<role> + -d | Create with role | xurl codex/reviewer -d "..." |
<provider>/<id> + -d | Append to conversation | xurl codex/<id> -d "..." |
/abs/path or . or ~ | Path-scoped query | xurl 'agents://.?q=test' |
Token resolution: <token> is parsed as session ID first; if that fails, treated as role name.
Query parameters: q=<keyword>, limit=<n> (default 10), providers=<name,...> (path-scoped only). In write mode, extra params are forwarded as --<key> <value> to the provider CLI.
Failure Handling
xurl returns clear error messages. Act on them directly:
| Error | Recovery |
|---|---|
command not found: xurl | Install using Prerequisites section |
command not found: <agent> | The provider CLI is not installed. Install and authenticate it, then retry |
| Unknown/unsupported provider | The provider may not be supported yet. Suggest the user file an issue at https://github.com/xuanwo/xurl/issues |
| Write to path-scoped URI | Path URIs are read-only. Use a provider-scoped URI instead |
| Operation unsupported (role create, write, drill-down, etc.) | Not all providers support all operations. xurl's error message will say what's unsupported. Try without the unsupported feature, or suggest filing an issue |
When xurl returns any unexpected error, show the error to the user and suggest filing an issue at https://github.com/Xuanwo/xurl/issues if the feature should be supported.