oimiragieo/reddit-researcher

<!-- Agent: nodejs-pro | Task: #7 | Session: 2026-03-09 -->

Reddit Researcher Skill

Purpose

Fetch and analyze public Reddit content without authentication using the Reddit public JSON API. Enables research agents to read subreddit posts, search Reddit globally or within a subreddit, and fetch individual post comments — all through the stable .json endpoint pattern.

No API key. No OAuth. No registration. Reddit's public JSON API is accessible anonymously for read-only operations.

---

When to Use

• Researching community sentiment on a topic
• Finding relevant discussions in a specific subreddit
• Gathering examples, opinions, or use cases from Reddit
• Monitoring a subreddit for recent posts
• Fetching comments on a specific post for analysis

---

Iron Laws

1. ALWAYS validate Reddit URLs against the allowlist before WebFetch — only reddit.com, www.reddit.com, and old.reddit.com are permitted; reject anything else to prevent SSRF attacks.
2. ALWAYS append .json to Reddit URLs before fetching — never fetch HTML pages; the .json suffix returns structured data that can be parsed reliably.
3. ALWAYS include a User-Agent header — Reddit blocks requests without a proper User-Agent; use agent-studio-reddit-researcher/1.0.
4. NEVER make more than 10 WebFetch calls per minute — unauthenticated rate limit is 10 req/min; add 1-2 second delays for multi-call workflows; search endpoints are more restrictive (~3-5 req/min).
5. NEVER write to Reddit — this skill is strictly read-only; no POST requests, no upvoting, no commenting, no authentication flows.

---

API Reference

| Endpoint | Description | Notes | | -------------------------------------------------------------------- | ----------------------- | --------------------------------- | | https://www.reddit.com/r/{sub}.json | Hot posts in subreddit | Default sort: hot | | https://www.reddit.com/r/{sub}/hot.json | Hot posts (explicit) | | | https://www.reddit.com/r/{sub}/new.json | New posts | | | https://www.reddit.com/r/{sub}/top.json?t=week | Top posts by time | t=hour/day/week/month/year/all | | https://www.reddit.com/r/{sub}/about.json | Subreddit metadata | subscriber count, description | | https://www.reddit.com/search.json?q={query} | Global search | | | https://www.reddit.com/r/{sub}/search.json?q={query}&restrict_sr=1 | Subreddit-scoped search | | | https://www.reddit.com/r/{sub}/comments/{id}.json | Post with comments | Returns array[2]: post + comments |

Query Parameters:

• limit — number of results (max 100, default 25; keep at 25 or less to stay within rate limits)
• after / before — pagination cursors (t3_postid format)
• t — time filter for /top: hour, day, week, month, year, all
• restrict_sr=1 — restrict search to current subreddit

Required Headers:

User-Agent: agent-studio-reddit-researcher/1.0

---

SSRF Guard Pattern

Always validate URLs using new URL().hostname before passing to WebFetch. Do not use regex or string-contains matching — those fail on encoded URLs and normalization tricks.

const ALLOWED_REDDIT_HOSTS = new Set(['reddit.com', 'www.reddit.com', 'old.reddit.com']);

function validateRedditUrl(href) {
  let parsed;
  try {
    parsed = new URL(href);
  } catch {
    throw new Error('Invalid URL');
  }
  if (!['http:', 'https:'].includes(parsed.protocol)) {
    throw new Error('Only http/https allowed');
  }
  if (!ALLOWED_REDDIT_HOSTS.has(parsed.hostname)) {
    throw new Error(`Hostname ${parsed.hostname} not in allowlist`);
  }
  return parsed.href;
}

Additional blocks (OWASP-recommended):

• Block file://, gopher://, dict:// schemes
• Block 127.0.0.1, localhost, 0.0.0.0
• Block 169.254.169.254 (AWS/cloud metadata endpoint)

---

Rate Limit Guidance

| Endpoint Type | Limit | Notes | | ------------------------- | ------------ | ----------------------------------- | | General listing endpoints | 10 req/min | Rolling window | | Search endpoints | ~3-5 req/min | More restrictive | | WebFetch built-in cache | 15-min TTL | Repeated calls to same URL are free |

Safe multi-call pattern: Add 1-2 second delays between calls. Use limit=25 to get enough results per call without needing rapid pagination.

---

Response Structure

Post listing (data.children[].data):

{
  "id": "abc123",
  "title": "Post title here",
  "selftext": "Post body text",
  "url": "https://www.reddit.com/r/sub/comments/abc123/...",
  "author": "username",
  "score": 42,
  "num_comments": 10,
  "created_utc": 1234567890,
  "subreddit": "subredditname"
}

Comments response: Array of two elements — [0] is the post, [1] is the comment tree.

---

Usage Examples

Search a subreddit for a topic

Invoke: WebFetch
URL: https://www.reddit.com/r/MachineLearning/search.json?q=transformer+architecture&restrict_sr=1&limit=10
Headers: User-Agent: agent-studio-reddit-researcher/1.0

Get hot posts from a subreddit

Invoke: WebFetch
URL: https://www.reddit.com/r/programming/hot.json?limit=25
Headers: User-Agent: agent-studio-reddit-researcher/1.0

Fetch a specific post with comments

Invoke: WebFetch
URL: https://www.reddit.com/r/programming/comments/abc123.json
Headers: User-Agent: agent-studio-reddit-researcher/1.0

Global Reddit search

Invoke: WebFetch
URL: https://www.reddit.com/search.json?q=claude+code+agent&limit=25
Headers: User-Agent: agent-studio-reddit-researcher/1.0

---

Anti-Patterns

| Anti-Pattern | Why It Fails | Correct Approach | | ------------------------------------------ | ------------------------------------------------------ | --------------------------------------------------------------- | | Fetching reddit.com without .json suffix | Returns HTML, not structured data | Always append .json to the URL path | | Using regex to validate URLs | Fails on encoded/normalized URLs; SSRF bypass possible | Use new URL(href).hostname and check against allowlist Set | | No User-Agent header | Reddit blocks anonymous requests; returns 429 or HTML | Always include User-Agent: agent-studio-reddit-researcher/1.0 | | Rapid successive requests (>10/min) | Rate limit triggers 429 responses | Add 1-2s delays; use limit=100 to reduce call count | | Attempting write operations | Reddit's public JSON API is read-only without OAuth | Use only GET endpoints; never attempt POST/PUT/DELETE |

---

Enforcement Hooks

• Pre-execute (hooks/pre-execute.cjs): Validates input schema (AJV) and checks SSRF allowlist on any url field. Exits with code 2 on violation (fail-closed).
• Post-execute (hooks/post-execute.cjs): Emits observability event via send-event.cjs. Fails open (exit 0) on error to avoid blocking skill execution.

---

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing:

• New Reddit API pattern -> .claude/context/memory/learnings.md
• Issue found (rate limit, API change) -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it is not in memory, it did not happen.