Research Agents, Custom Slash Commands, Subagents

Learning objectives

• Define a Claude Code subagent: its own context window, its own allowed-tools set, reporting only a summary back.
• Write a custom slash command that chains multiple subagents in sequence.
• Design a Reddit research subagent modeled on PRAW's read-only vs. authorized instance pattern.
• Apply "name parameters unambiguously" and "build in pagination" when scoping a subagent's tools.
• Explain why the unauthenticated ".json trick" is a fragile research shortcut, not a production dependency.

Prerequisites: Lesson 6.3.2.

Core concepts

Claude Code subagents run in their own separate context window, with their own restricted set of allowed tools, and report back only a summary to the main thread, keeping the primary conversation clean even when a subagent does significant research work underneath it. They are defined as markdown files inside .claude/agents/, and custom slash commands that chain several subagents in sequence are the code-native replacement for a Zapier or n8n automation pipeline (alexop.dev; Claude Code docs). For a Reddit operation with five anchor subreddits, this is the direct implementation of the parallelization pattern from Lesson 6.1.3: five subagents, one per subreddit, each running independently, each reporting a short structured summary back to an orchestrating slash command.

---
name: reddit-subreddit-researcher
description: Researches new/rising posts in one named subreddit and returns
  a scored summary. Called by /reddit-weekly-scan, never invoked directly
  on a whole product line at once.
tools: [mcp__reddit__search, mcp__reddit__get_posts]
---
You are a research subagent scoped to exactly one subreddit, passed as
{{subreddit_name}}. Pull posts from the last 7 days, apply
reddit-context/icp.md relevance criteria, and return only: top 5 threads,
each with title, age, comment count, and one-line relevance note. Do not
draft replies. Do not exceed your assigned subreddit.

# .claude/commands/reddit-weekly-scan.md
Fan out to reddit-subreddit-researcher for each subreddit in
reddit-context/subreddit-map.md's anchor list, running in parallel.
Collect all five summaries, then synthesize into a single ranked
weekly-digests/ entry using reddit-intent-scorer on each candidate thread.

Anthropic's own tool-design guidance applies directly to scoping a subagent's tools: name parameters unambiguously, subreddit_name, not sub, and build pagination, filtering, and truncation into any tool's response so it doesn't flood the subagent's limited context window ("Writing effective tools for AI agents," Anthropic Engineering). If you build a custom Reddit-reading tool rather than relying entirely on an MCP server, the canonical foundation is PRAW (praw-dev/praw, Python 3.10+, v7.8.1), whose core mental model, a Reddit instance is either read-only (public data only) or authorized (full account actions), is the exact distinction your subagents should respect: research subagents stay strictly read-only; nothing in this layer should ever hold write credentials. PRAW's own streaming tutorial (subreddit.stream.submissions() / .stream.comments(), with skip_existing=True) is the reference pattern for real-time monitoring if you outgrow polling. One shortcut to avoid in production: appending .json to a public Reddit URL still returns structured data with no auth, but as of 2026 these endpoints increasingly return 403, fine for a five-minute prototype, unfit for anything you depend on daily (Simon Willison's TIL).

Video lessons

Supporting reading

• Writing effective tools for AI agents, Anthropic Engineering (https://www.anthropic.com/engineering/writing-tools-for-agents), the source for unambiguous parameter naming and pagination/truncation discipline applied above.
• praw-dev/praw (GitHub) (https://github.com/praw-dev/praw), the canonical Python Reddit wrapper and the read-only-vs-authorized mental model every research subagent should respect.
• PRAW Submission Stream Reply Bot tutorial (https://praw.readthedocs.io/en/latest/tutorials/reply_bot.html), the official real-time monitoring pattern via stream.comments()/stream.submissions().
• Scraping Reddit via their JSON API, Simon Willison's TILs (https://til.simonwillison.net/reddit/scraping-reddit-json), the .json trick and its 2026 fragility, taught here as a shortcut to recognize and avoid depending on.
• wrhilton/Reddit-User-Analysis (GitHub) (https://github.com/wrhilton/Reddit-User-Analysis), an open-source PRAW template combining account-age/karma checks and sentiment analysis, a useful scaffold for a research subagent's credibility checks.

Exercise

Write the reddit-subreddit-researcher subagent and the /reddit-weekly-scan slash command above. Run it against your five anchor subreddits and confirm five independent, correctly-scoped summaries come back.

Assignment

Submit your finished subagent .md file, your slash command file, and one run's actual output (five subreddit summaries plus the synthesized digest). Note any tool-naming or pagination fix you had to make after Anthropic's tool-design guidance flagged a problem in your first draft.

Claude workflow

• Prompt: "/reddit-weekly-scan" (the entire point of this lesson is that the slash command itself replaces a multi-step manual prompt).
• Skill idea: a "subagent-scope-auditor" skill that checks every .claude/agents/*.md file for write-capable tools and flags any research subagent that isn't strictly read-only.
• Automation: a scheduled daily or twice-weekly run of /reddit-weekly-scan, writing its output to weekly-digests/ for the human review queue Lesson 6.4.1 formalizes, the last purely technical automation this stage builds before assembly.

Expected outcomes

• Working /reddit-weekly-scan slash command fanning out to five subreddit subagents and synthesizing a digest.
• Can explain subagent context isolation and why research subagents must stay read-only.
• Can state the "name parameters unambiguously, build in pagination" rule and show where it applied to your own tool scoping.