A Claude Code research subagent is a markdown file with YAML frontmatter that gives Claude Code a name, description, tool list, and model, then reads business context files before every search. It uses Perplexity for web search and Firecrawl for competitor scraping, and outputs a structured JSON brief with findings, gaps, and a recommended angle.
What you will be able to do
- Create a Claude Code agent definition file with YAML frontmatter that sets its name, description, tools, and model
- Build three research profile files (business context, content strategy, competitor watchlist) the agent reads before every run
- Run research on a Notion post ID or a raw topic with one command and get a JSON brief back in under a minute
- Get competitor coverage analysis with gaps identified and a recommended angle tailored to your audience
- Decide whether a research task belongs in Claude Code, Claude Projects, or n8n using the decision signals framework
Before you start
- Claude Code CLI installed (npm install -g @anthropic-ai/claude-code), check with claude --version
- Node.js installed, check with node --version
- Free Perplexity API key (perplexity.ai/api) and free Firecrawl API key (firecrawl.dev)
- MCP servers for Perplexity and Firecrawl configured in Claude Code settings
Reference
| File / Command | Purpose | Detail |
|---|---|---|
| .claude/agents/content-researcher.md | Agent definition: YAML frontmatter plus system prompt | tools: Read, Glob, Grep, mcp__perplexity__search, mcp__perplexity__reason, mcp__firecrawl__firecrawl_scrape; model: sonnet |
| .claude/research-profiles/business-context.md | Company identity, mission statement, target audiences | Read by the agent before every research run |
| .claude/research-profiles/content-strategy.md | Content pillars, brand voice, format requirements | Read by the agent before every research run |
| .claude/research-profiles/competitor-watchlist.md | Table of direct competitors and adjacent players | Read by the agent before every research run |
| /research |
Runs research from a Notion post ID | Looks up the title in Notion, saves to .claude/research-outputs/by-post/ |
| /research --topic "..." | Runs research on a topic directly | No Notion calendar lookup needed |
| python src/main.py run-agent --agent content_researcher --topic "..." | CLI equivalent of the topic-based slash command | Use if you have not wired up the slash command |
| Output JSON fields | executive_summary, key_findings, competitor_coverage, recommended_angle, suggested_outline, sources | Structured brief the agent always returns |
Common errors and fixes
| What goes wrong | The fix |
|---|---|
| Agent output reads generic, like plain ChatGPT, not tailored to your business | Confirm the agent's system prompt loads business-context.md, content-strategy.md, and competitor-watchlist.md as Step 1 before any research |
| Agent can't search or scrape anything | Complete the Article 1 foundation first: Claude Code CLI, Node.js, Perplexity and Firecrawl API keys, both MCP servers configured in Claude Code settings |
| Trying to do this kind of research inside Claude Projects | Claude Projects can't reach MCP tools, so Perplexity search and Firecrawl scraping have to be done by hand, copy-pasting for every session |
| Reaching for n8n for a one-off, right-now research task | n8n needs 2+ hours of setup (hosting, API nodes, workflow building) plus monthly hosting costs; it fits scheduled or triggered research, not ad-hoc |
| No Notion content calendar to look up a post ID | Skip the ID lookup and run with the --topic flag instead: python src/main.py run-agent --agent content_researcher --topic "your topic" |
Read the full walkthrough
The complete lesson, with screenshots and any downloads, is published on Substack as part of PubFlow OS Agents: Build Your AI Research Team.
More in this section
Continue the course
Browse all lessons in the PubFlow OS Agents: Build Your AI Research Team course, or subscribe to the GenAI Unplugged newsletter to get new lessons in your inbox.
