Agent skill

Perplexity Search

by escapeWu in escapeWu/perplexity-ai

Searches the live web with citations through perplexity-mcp v2 tools or a bundled Python REST client, with focused ask, deep research and detached tasks.

MITAuto-check passedProductivity & Automation

Install Perplexity Search

skills CLI
$ npx skills add escapeWu/perplexity-ai --skill perplexity-search -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install escapeWu/perplexity-ai perplexity-search --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/escapeWu/perplexity-ai.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/perplexity-search .claude/skills/perplexity-search && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
perplexity-search
GitHub stars
170
Token cost
~1.8k tokens
SKILL.md length
583 words
Files
5 (incl. scripts)
Skills in repo
3
Repo updated
First seen
Licence
MIT

At a glance

Searches the live web with citations through perplexity-mcp v2 tools or a bundled Python REST client, with focused ask, deep research and detached tasks.

  • Looking up recent news or facts with source citations
  • SKILL.md covers Python REST client, Focused Ask, Deep Research and Response contract, plus 4 more sections
  • Runs Python scripts from its folder; calls python3; needs MCP_TOKEN and PPLX_API_KEY
  • Running a broad deep research query on a topic

What it does

This skill gives one workflow over two transports: a connected perplexity-mcp server that exposes the tools directly, or a standard-library Python client in the scripts folder that offers matching methods over REST. Operations are the same either way: a focused ask for current facts and cited answers, a deep research call for broad multi-source reports, and tasks that can be submitted, checked and cancelled.

REST configuration comes from PPLX_BASE_URL, which defaults to a local address on port 8000, and a bearer token in MCP_TOKEN or PPLX_API_KEY, with config.json as a fallback. Credentials must never be printed, quoted, logged or committed. A model can be named when asking, and a thinking option selects its paired variant. The older MCP tools called search, research and perplexity_search are deprecated and should not be used.

When your agent uses it

  • Looking up recent news or facts with source citations
  • Running a broad deep research query on a topic
  • Fact-checking a claim against current web sources
  • Starting a long search as a detached task and checking on it later

Example prompts

  • “Find the latest Python packaging changes and cite primary sources.”
  • “Run deep research comparing enterprise AI agent pricing across vendors.”
  • “Submit a detached research task on EU AI regulation and check its status.”

Requirements

  • A running perplexity-mcp server or a reachable REST service at PPLX_BASE_URL
  • A token in MCP_TOKEN or PPLX_API_KEY
  • Python 3 for the bundled REST client

What it can do on your machine

Read from SKILL.md and the folder at commit a39a13f. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 2 files in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python3

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • MCP_TOKEN
    • PPLX_API_KEY

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Perplexity Search loads about 1.8k tokens when it runs. Until then it costs about 102 tokens; SKILL.md has 583 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~102
When it runs · the whole SKILL.md, loaded when a task matches
~1.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from escapeWu/perplexity-ai at commit a39a13f, republished under its MIT licence (© escapeWu). 583 words, ~1,814 tokens.

Download SKILL.mdSave it as .claude/skills/perplexity-search/SKILL.md (or your agent's skills folder). This skill also uses 4 other files; get the full folder from GitHub.
name
perplexity-search
description
Search the current public web with citations through either the perplexity-mcp v2 tools or the bundled Python REST client. Use for recent information, news, fact checks, source-backed comparisons, research, file-assisted questions, native follow-ups, and detached tasks. Both transports expose the same perplexity_ask_v2, perplexity_research_v2, and task method names and response shapes.
metadata.version
3.0.0

Use one workflow regardless of transport. A connected perplexity-mcp server exposes tools directly; the bundled scripts/client.py exposes matching Python methods over REST.

OperationMCP toolPython REST method
Focused search or cited answerperplexity_ask_v2client.perplexity_ask_v2(...)
Broad Deep Researchperplexity_research_v2client.perplexity_research_v2(...)
Submit detached workperplexity_task_submitclient.perplexity_task_submit(...)
Observe detached workperplexity_task_statusclient.perplexity_task_status(...)
Cancel detached workperplexity_task_cancelclient.perplexity_task_cancel(...)

Choose the available transport, then keep the same operation names, arguments, session rules, and output handling. Do not switch to legacy MCP tools such as search, research, or perplexity_search; they are deprecated.

Python REST client

The client uses only the Python standard library. Load it from this skill's scripts directory:

python
import sys
from pathlib import Path

skill_dir = Path(".agents/skills/perplexity-search").resolve()
sys.path.insert(0, str(skill_dir / "scripts"))

from client import PerplexityRestClient

client = PerplexityRestClient.from_config(skill_dir / "config.json")
result = client.perplexity_ask_v2(
    "What changed in Python packaging this month? Cite primary sources."
)

Configuration is shared by every REST method:

  • PPLX_BASE_URL: service root, with or without /v1; defaults to http://127.0.0.1:8000.
  • MCP_TOKEN or PPLX_API_KEY: bearer token; MCP_TOKEN takes precedence.
  • config.json: fallback configuration when environment variables are absent.

Never print, quote, log, or commit real credentials.

Focused Ask

Use perplexity_ask_v2 for current facts, news, comparisons, source-backed analysis, and ordinary searches.

MCP arguments and Python arguments are identical:

json
{
  "query": "Compare the latest Python packaging changes and cite primary sources.",
  "model": "gpt-5-6-terra",
  "thinking": true,
  "session_id": null,
  "files": null
}
python
result = client.perplexity_ask_v2(
    query="Compare the latest Python packaging changes and cite primary sources.",
    model="gpt-5-6-terra",
    thinking=True,
)

Omit model to use perplexity-search. When selecting a model, pass the exact OAI model ID exposed by the server. Set thinking=True to select its paired thinking variant. Do not pass perplexity-deepsearch to Ask.

Deep Research

Use perplexity_research_v2 for broad investigations with several subtopics, many sources, or report-like synthesis.

python
result = client.perplexity_research_v2(
    query=(
        "Research the 2026 enterprise AI agent market. Compare adoption, pricing, "
        "security constraints, and primary-source evidence."
    )
)

This operation always selects perplexity-deepsearch; it does not accept model or thinking.

Response contract

Both transports return the same success shape for Ask and Research:

json
{
  "status": "ok",
  "session_id": "sess_...",
  "job_id": "job_...",
  "model": "perplexity-search",
  "data": {
    "answer": "...",
    "sources": []
  }
}

Check status before using a result. Read the answer from data.answer, preserve direct URLs from data.sources, and distinguish sourced facts from your synthesis.

Failures use the same top-level convention:

json
{
  "status": "error",
  "error_type": "...",
  "message": "..."
}

Report the non-secret error type and message. Do not silently change models, replace sessions, or treat incomplete task output as success.

Sessions

Omit session_id to create a native session. For a same-topic follow-up, call the same operation with the returned ID and only the latest instruction:

python
follow_up = client.perplexity_ask_v2(
    query="Add exact release dates and one primary source per claim.",
    session_id=result["session_id"],
)

Keep the session ID with its operation family. Start a new session when the topic changes. A session is permanently bound to its first account and supports at most one unfinished task; it does not fail over or accept concurrent turns.

Show full SKILL.md (225 more words)Show less

Files

Pass attachments through files on either Ask, Research, or task submission.

For MCP, files follows the server tool schema. For Python REST, use either a filename-to-content mapping or an iterable of local paths:

python
client.perplexity_ask_v2(
    "Summarize the attached evidence and verify current claims on the web.",
    files=["reports/evidence.pdf"],
)

client.perplexity_ask_v2(
    "Review this note.",
    files={"note.txt": "local text content"},
)

The REST client reads local paths and sends base64 input_file content, so the remote server does not need access to the client's filesystem. Respect server limits: at most 10 files, 20 MiB per file, 100 MiB per request, and allowed extensions.

Detached tasks

Use detached tasks only when work must survive caller disconnects, is expected to run for a long time, or consists of independent concurrent conversations.

MCP users should call get_skill_index and read get_tasks_use before the task tools. Python users call the same task operations through REST:

python
accepted = client.perplexity_task_submit(
    query="Research WebAssembly component model adoption with primary sources.",
    model="perplexity-deepsearch",
    idempotency_key="wasm-adoption-1",
)

status = client.perplexity_task_status(
    accepted["job_id"],
    wait_seconds=20,
    include_output=False,
)

A successful submission means admission, not completion. Retain both job_id and session_id. Only state == "completed" is complete. Fetch output with include_output=True; the answer is in snapshot.answer. Treat failed, timed_out, cancelled, and interrupted as non-success even when a draft exists.

Reuse an idempotency_key only to recover the same submission after a lost receipt. Use a different session for each concurrent task. Cancel explicitly when the task is no longer needed:

python
client.perplexity_task_cancel(accepted["job_id"])

Cancellation cannot undo upstream work already accepted.

Command line

The CLI uses the exact MCP tool names:

bash
python3 "$SKILL_DIR/scripts/client.py" perplexity_ask_v2 \
  "What changed this week? Cite primary sources."

python3 "$SKILL_DIR/scripts/client.py" perplexity_research_v2 \
  "Research current enterprise AI agent adoption."

python3 "$SKILL_DIR/scripts/client.py" perplexity_task_status job_... \
  --wait-seconds 20

cli.py remains a compatibility entry point and dispatches to the same client. Use client.py for new integrations.

© escapeWu, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 4 other files (scripts) in .agents/skills/perplexity-search of escapeWu/perplexity-ai.

  • SKILL.md
  • agents/openai.yaml
  • config.json
  • scripts/cli.py
  • scripts/client.py

Open the folder on GitHubat commit a39a13f

Compare with similar skills

Perplexity Search next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Perplexity Search compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Perplexity Search this skillescapeWu/perplexity-ai170—~1.8kAutomated safety check: PassMIT
Tavily Web Searchallenpeng0705/EnvoyMesh3.1k3 repos~2.5kAutomated safety check: NotesNone
Perplexity Search and Researchartwist-polyakov/polyakov-claude-skills206—~2.5kAutomated safety check: NotesMIT
Exa Neural Search via MCPaffaan-m/ECC276k4 repos~1.1kAutomated safety check: PassMIT
Argo Search and Verificationtaxueseek/argo186—~1.2kAutomated safety check: PassMIT
Weekly Signal DiffNateBJones-Projects/OB14.7k—~1.7kAutomated safety check: PassCustom licence

Similar skills

  • Tavily Web Search

    allenpeng0705/EnvoyMesh

    Searches the web through the Tavily API with LLM-friendly output: clean structured results, optional AI-written answers, domain filters, news mode, images and raw content.

    3.1k GitHub starsUsed in 3 repos~2.5k tokens
    Productivity & AutomationAuto-check: notes
  • Perplexity Search and Research

    artwist-polyakov/polyakov-claude-skills

    Shell scripts for web search and research through the Perplexity API: raw results, cited answers, background deep research and page fetching, with results cached on disk.

    206 GitHub stars~2.5k tokensUpdated today
    Productivity & AutomationAuto-check: notes
  • Searches the web, code, companies and people through the Exa MCP server, with notes on setup, the web_search_exa tool and treating results as untrusted data.

    276k GitHub starsUsed in 4 repos~1.1k tokens
    Productivity & AutomationAuto-check passed
  • Unified web search, page fetching and evidence checking across hundreds of sources, with result verification, a research-dossier mode and vertical search engines.

    186 GitHub stars~1.2k tokensUpdated 2 days ago
    Research & ScienceAuto-check passed
  • Weekly Signal Diff

    NateBJones-Projects/OB1

    Turns a noisy week of AI or software market news into a short list of structural changes, weighted by what the user already tracks in Open Brain memory.

    4.7k GitHub stars~1.7k tokensUpdated today
    Research & ScienceAuto-check passed
  • Browser Search

    Johell1NS/browser-search

    Multi-engine web search (SearXNG) + browsing/scraping (Camofox, CloakBrowser).

    529 GitHub stars~2.5k tokensUpdated 1 mo ago
    Productivity & AutomationAuto-check passed

More from escapeWu/perplexity-ai

  • Version Bump and Release

    escapeWu/perplexity-ai

    Bumps a project version, updates both changelogs, builds the frontend, then commits, tags and pushes the release.

    170 GitHub stars~528 tokensUpdated 11 days ago
    Auto-check passed
  • Perplexity Server Deploy

    escapeWu/perplexity-ai

    Deploys the perplexity-ai project to its production server by pushing main, fast-forwarding the server checkout, rebuilding the image there and verifying health.

    170 GitHub stars~662 tokensUpdated 11 days ago
    Auto-check: notes

Questions about Perplexity Search

What does Perplexity Search do?

Searches the live web with citations through perplexity-mcp v2 tools or a bundled Python REST client, with focused ask, deep research and detached tasks. This skill gives one workflow over two transports: a connected perplexity-mcp server that exposes the tools directly, or a standard-library Python client in the scripts folder that offers matching methods over REST. Operations are the same either way: a focused ask for current facts and cited answers, a deep research call for broad multi-source reports, and tasks that can be submitted, checked and cancelled.

When should I use Perplexity Search?

Perplexity Search fits situations like: looking up recent news or facts with source citations; running a broad deep research query on a topic; fact-checking a claim against current web sources; starting a long search as a detached task and checking on it later.

How do I install Perplexity Search in Claude Code?

Run `npx skills add escapeWu/perplexity-ai --skill perplexity-search -a claude-code`. Or copy the skill folder (.agents/skills/perplexity-search in escapeWu/perplexity-ai) into .claude/skills/perplexity-search in your project. Claude Code loads it when a task matches its description.

How do I install Perplexity Search in Codex?

Run `npx skills add escapeWu/perplexity-ai --skill perplexity-search -a codex`. Or copy the skill folder (.agents/skills/perplexity-search in escapeWu/perplexity-ai) into .agents/skills/perplexity-search in your project. Codex loads it when a task matches its description.

Can I use Perplexity Search in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add escapeWu/perplexity-ai --skill perplexity-search -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/perplexity-search, .gemini/skills/perplexity-search, .github/skills/perplexity-search and .opencode/skills/perplexity-search in your project.

What does Perplexity Search need to run?

Going by SKILL.md and its folder, Perplexity Search needs Python for the scripts in its folder, the command-line tools its instructions call (python3) and credentials named MCP_TOKEN and PPLX_API_KEY. Our summary lists: A running perplexity-mcp server or a reachable REST service at PPLX_BASE_URL; A token in MCP_TOKEN or PPLX_API_KEY; Python 3 for the bundled REST client.

Does Perplexity Search access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Perplexity Search safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Perplexity Search use?

Perplexity Search is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Perplexity Search use?

About 1.8k tokens (SKILL.md is roughly 7.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Perplexity Search?

Skills that share tags, products or a category with Perplexity Search: Tavily Web Search (allenpeng0705/EnvoyMesh, 3.1k stars), Perplexity Search and Research (artwist-polyakov/polyakov-claude-skills, 206 stars), Exa Neural Search via MCP (affaan-m/ECC, 276k stars) and Argo Search and Verification (taxueseek/argo, 186 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Perplexity Search?

escapeWu (a GitHub user) maintains it in escapeWu/perplexity-ai, which has 170 GitHub stars. The repository holds 3 skills in this directory. The repository was last updated on September 27, 2026.

Source: escapeWu/perplexity-ai on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.