How to use the Perplexity Brain Research agent skill (perplexity-research)

What is an agent skill?

An agent skill is a set of instructions, packaged as a folder with a SKILL.md file, that an AI agent can load to perform a specific task. This skill is markdown instructions that tell the agent how to call Perplexity's API and how to write the result into your brain.

What the skill makes the agent do

The agent first pulls relevant context from your brain using gbrain get or gbrain query. It then writes that context into a Perplexity prompt and asks for current, cited findings. Perplexity searches and reads multiple pages, focusing on what is new relative to the context you supplied.

The result is saved as a research page under research/ with sections for new developments, confirming signals, contradictions, suggested brain updates, and citations. Every claim is meant to carry a URL.

• Key New Developments: what has changed since the brain was last updated
• Confirming Signals: web evidence that supports existing notes
• Contradictions or Updates: conflicts with the brain that need review
• Recommended Brain Updates: specific page changes with source URLs
• Citations: linked sources with access dates

Install the perplexity-research skill

Download the ZIP file from this page and unzip it. Place the resulting folder in ~/.claude/skills/ to make it available across your projects, or in a project's .claude/skills/ folder to limit it to that project.

You can also upload the skill in the Claude apps: open Settings, go to Capabilities, then Skills, and upload the ZIP there.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Set up the requirements

The skill needs three things: gbrain (the brain tool with get, query, search and put_page operations), a PERPLEXITY_API_KEY environment variable for Perplexity's Agent API, and network access to api.perplexity.ai. The key can be set in the agent's environment or in ~/.gbrain/.env. A host-provided perplexity CLI can be used instead of direct API calls.

• gbrain with get, query, search and put_page
• PERPLEXITY_API_KEY set in the environment or ~/.gbrain/.env
• Network access to api.perplexity.ai

Trigger the skill with natural requests

You do not need special syntax. The skill responds to phrases such as the ones below. Name a topic and the agent will gather brain context, query Perplexity, and write the research page. Use it for entity enrichment, current-state checks, deal monitoring, and freshness checks.

It is not the right tool for a single URL, which the web_fetch tool handles more directly, or for questions answered only by your notes, which call for gbrain query.

• "Perplexity research on Acme Corp"
• "What's new about Jane Doe at her company?"
• "Current state of the EU battery regulation deal"
• "Web research on our competitors this week"
• "What changed about the Series B terms?"

How the agent runs a research pass

The source describes a five-step flow. The agent pulls brain context, composes a Perplexity query with that context inline and asks for citations on anything new since a given date, calls the Perplexity Agent API at POST /v1/agent with a preset, reads the answer and citations, and writes the research page with put_page. It then cross-links the people and companies mentioned.

Choose a preset based on the job. The low preset suits deep analysis and entity enrichment. The fast preset suits quick lookups and bulk monitoring. The skill defaults to low. A recency filter (hour, day, week, month or year) can narrow results for news-cycle topics.

• Default to low for deep analysis and entity enrichment
• Use fast for bulk or cron jobs where cost matters more than depth
• Add a recency filter for news topics; omit it for evergreen research

Safety, privacy and limits

This skill runs scripts and uses the network. Brain context you include is sent to Perplexity, a third party, so avoid it for sensitive or confidential topics. Perplexity does not publish a fixed per-request price for presets, so check its pricing page before running bulk jobs.

If the API key is missing or rejected, the skill cannot run its web arm and should answer from the brain only, saying so. If rate limited, it retries after the stated delay. If the brain-context search is degraded, the new-versus-known comparison is less reliable.

• Do not send confidential material to a third-party service
• Check Perplexity's pricing page before bulk runs
• Without a key or gbrain setup, expect brain-only answers
• Keep the citations; claims without URLs should not be trusted

Tips for better results

Send dense brain context. The skill works by letting Perplexity know what you already know, so truncated notes produce repeated facts. Keep entity pages current so the delta is meaningful.

Check the contradictions section first, since those items need a closer look. Review the recommended brain updates before applying them.

• Keep entity pages up to date so the delta stays meaningful
• Use specific topics rather than broad questions
• Review contradictions before accepting new information