| 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
cargo install xurl-cli
uv tool install xuanwo-xurl
npm install -g @xuanwo/xurl
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'
xurl 'agents:///Users/alice/work/repo?limit=5'
xurl 'agents://~/work/repo?providers=codex,claude'
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 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.
