Skills and analyst agents
The MCP connection gives an assistant urlquery tools. A skill or a dedicated agent adds a repeatable investigation method on top: how to frame the question, which evidence to collect first, what not to conclude, and how to structure the answer.
| Option | Use it when | Supported in |
|---|---|---|
| Skill | Your everyday assistant should recognize web threat-research requests and apply the method when they come up. | Claude Code, Codex, opencode |
| Dedicated agent | You want a focused analyst you hand investigations to, with only the urlquery tools and no file editing or shell access. | Claude Code, opencode |
Both are optional. Connect the MCP server first; the examples assume it is named urlquery.
Threat-research skill
The skill is one SKILL.md file in the open Agent Skills format, so the same file works in every client that supports skills. Download the raw SKILL.md.
---
name: urlquery-threat-research
description: Analyze suspicious URLs, reports, domains, IPs, hashes, phishing infrastructure, and web threat activity with the urlquery MCP server. Use when a request needs URL behavior, report evidence, infrastructure pivots, reputation, trends, or a defensible CTI assessment.
---
# urlquery Threat Research
Use the urlquery MCP server as the primary evidence source for web threat investigations.
## Investigation Method
1. Frame the question, relevant indicators, time window, and required outcome.
2. Observe captured behavior in representative reports before making campaign or infrastructure claims.
3. Correlate exact indicators and distinctive infrastructure facts across a bounded report population.
4. Assess what the evidence supports, alternative explanations, confidence, and collection gaps.
5. Preserve report IDs, hashes, queries, dates, and important tool arguments in the result.
## Evidence Strategy
- For an existing report, summarize it first and retrieve focused detections, HTTP activity, scripts, artifacts, technologies, screenshots, or resources only when needed.
- For one important HTTP transaction, preserve its original one-based index and request detailed metadata before opting into captured raw headers or request-data chunks.
- For a URL, check exact URL/FQDN reputation and search visible reports before expanding related infrastructure. For domains, IPs, hashes, Telegram tokens, and other unsupported reputation inputs, use report search and the applicable indicator or host pivots.
- When preparing a handoff with `list_report_indicators`, request explicit kinds; omitted kinds include exact threat-actor Telegram bot tokens.
- For change over time, use explicit complete periods and report the analyzed population.
- For host relationships, prefer distinctive certificates, cookie fingerprints, and corroborated interactions over common hosting or technology matches.
- Return to report-level behavior to validate candidates produced by pivots or graph searches.
## Safety and Interpretation
- Submit a new URL only with explicit authorization and an intentional visibility setting.
- Never place credentials, private tokens, personal data, or confidential internal names in submissions or metadata.
- Treat detections, reputation, tags, and relationships as observations, not automatic verdicts or attribution.
- Do not describe missing detections as proof that an indicator is benign.
- State when results are bounded, partial, visibility-dependent, or limited by the available time window.
## Response Structure
Return:
1. Executive summary
2. Direct observations and supporting report IDs
3. Correlated infrastructure and IOCs
4. Assessment with confidence
5. Gaps, alternative explanations, and recommended next pivots
Install it in the folder your client reads skills from. Keep the folder name urlquery-threat-research, matching the skill's name:
| Client | Project | All projects |
|---|---|---|
| Claude Code | .claude/skills/urlquery-threat-research/SKILL.md | ~/.claude/skills/urlquery-threat-research/SKILL.md |
| Codex | .agents/skills/urlquery-threat-research/SKILL.md | ~/.agents/skills/urlquery-threat-research/SKILL.md |
| opencode | .opencode/skills/urlquery-threat-research/SKILL.md | See the opencode documentation. |
For example, to install it for every Claude Code project:
mkdir -p ~/.claude/skills/urlquery-threat-research
curl --fail --output ~/.claude/skills/urlquery-threat-research/SKILL.md \
https://docs.urlquery.net/examples/skills/urlquery-threat-research/SKILL.md
The assistant loads the skill when a request matches its description. You can also call it by name: /urlquery-threat-research in Claude Code, or $urlquery-threat-research in Codex. Restart the client, or start a new session, after adding it.
Dedicated analyst agent
An analyst agent runs investigations in its own context with only the urlquery tools. Hand it an investigation and it returns a structured assessment, without filling your main conversation with raw evidence.
Claude Code
Install the subagent at .claude/agents/urlquery-analyst.md for one project, or ~/.claude/agents/urlquery-analyst.md for all projects. Download the raw file.
---
name: urlquery-analyst
description: Investigates suspicious URLs, reports, domains, IPs, hashes, and web infrastructure with urlquery evidence and produces defensible CTI assessments. Use for web threat-research and incident-handoff requests.
tools: mcp__urlquery__*
---
You are a web threat research analyst using the urlquery MCP server.
Translate the user's investigation question into a bounded evidence plan. Examine representative report behavior before making broader claims, correlate exact indicators and distinctive infrastructure facts, and preserve the identifiers required to reproduce important pivots.
Use urlquery evidence to:
- explain redirects, network activity, scripts, artifacts, detections, and screenshots;
- research URLs, domains, IPs, ASNs, and hashes across visible reports;
- compare report populations across explicit time periods;
- identify candidate infrastructure through shared facts and observed relationships;
- prepare incident handoffs with evidence, IOCs, confidence, and gaps.
Before submitting a URL that has not already been analyzed, require explicit authorization and an explicit `public`, `restricted`, or `private` visibility choice. Never rely on the default visibility. Never assume a clean reputation result, missing detection, shared host, or graph relationship proves benignness, ownership, campaign membership, or attribution.
Keep collection proportional to the question. Begin with concise report or search context, expand only the evidence needed, and distinguish direct observations from analytical judgment.
Structure the final response as:
1. Executive summary
2. Evidence
3. Correlated infrastructure and IOCs
4. Assessment and confidence
5. Gaps and next steps
tools: mcp__urlquery__* gives the agent every urlquery tool and nothing else: no file edits, no shell. The agent has no model field, so it uses your default. Combine it with the permission rules that ask before submit_url, so a new analysis always needs your approval.
Ask for it by name, or let Claude Code delegate when a request matches:
Use the urlquery-analyst agent to investigate report
<REPORT_ID>and prepare an incident handoff.
opencode
opencode names agent files after the agent. Install this example at .opencode/agents/urlquery-analyst.md. Download the raw file.
The instructions are the same as the Claude Code agent's; only the front matter differs:
---
description: Investigates suspicious URLs and web infrastructure with urlquery evidence and produces defensible CTI assessments.
mode: subagent
permission:
edit: deny
bash: deny
---
You are a web threat research analyst using the urlquery MCP server.
…
The front matter denies project edits and shell commands and leaves the urlquery tools available. Restart opencode after adding the file; running sessions do not reload agent definitions.
Codex
For Codex, install the skill. To keep a session read-only, disable submit_url as shown in connect Codex.
Example requests
- “Use the urlquery analyst to investigate this report and produce an incident handoff.”
- “Research this domain over the last 30 days and identify corroborated infrastructure.”
- “Compare this phishing query across two complete monthly periods.”
- “Explain what this certificate pivot supports and what it does not prove.”
See use cases and workflows for investigation patterns and the tool reference for exact arguments.