--- name: reddit-search description: General-purpose Reddit search and monitoring — finds, filters, and ranks real posts and comments on any topic or query using the ThreadSnoop Reddit read API, judged by relevance to the actual request rather than a fixed rubric. Use this whenever the user wants to search Reddit, monitor a subreddit or keyword, track mentions of a brand, competitor, or topic, gauge sentiment, or do open-ended Reddit research. --- # Reddit search Search, filter, and rank real Reddit posts and comments for whatever the user is actually asking about — no fixed product, no fixed rubric. Monitoring, research, sentiment, competitor mentions, "what's being said about X" — this is the general skill for all of it. **This skill reads only. Never post, comment, vote, or DM on the user's behalf** — see the hard rule at the bottom. ## What you need A ThreadSnoop API key. Get one free at https://threadsnoop.com/signup — new keys start with 1,000 free Reddit searches, no card required. **Authentication:** - Read the key from the `THREADSNOOP_API_KEY` environment variable, or another secure credential store already configured for you. - Never ask the user to paste the key into this conversation unless they explicitly choose to. - Never echo, log, or repeat the key value anywhere in your own output. - If no key is configured, tell the user how to set `THREADSNOOP_API_KEY` — don't request the secret itself. Two ways to call the API — pick whichever needs less setup, but check the exception below first if you're running as a Claude Desktop or claude.ai Skill: 1. **Plain REST — the default, no setup required.** Fetch `https://threadsnoop.com/openapi.json` first (one request, no auth needed) so you have the exact endpoints, params, and response shapes, then call `https://api.threadsnoop.com/v1/...` directly with header `x-api-key: $THREADSNOOP_API_KEY` (or `Authorization: Bearer $THREADSNOOP_API_KEY`) — reference the environment variable, never a literal key value. Human-readable version of the same reference: https://threadsnoop.com/docs. **Exception — Claude Desktop and claude.ai Skills:** their code-execution sandbox has no outbound network access to arbitrary domains on Free/Pro/Max plans, so REST calls to `api.threadsnoop.com` will fail there, not just run slower. MCP is the only way to reach this API from those two surfaces specifically (Team/Enterprise org admins can instead allowlist the domain and skip MCP). 2. **MCP tools** — skip the spec fetch and call the tools directly: `search_posts`, `search_comments`, `get_comment_tree`, `search_subreddits`, `get_subreddit_rules`, `get_user_profile`, `check_credits`. Required on Claude Desktop/claude.ai per the exception above; everywhere else it's optional — only worth setting up if it's already connected (`claude mcp add --transport http threadsnoop https://api.threadsnoop.com/mcp --header "x-api-key: $THREADSNOOP_API_KEY"` for Claude Code; a JSON `mcpServers` block for Claude Desktop). Either way, 1 credit = 1 request, regardless of endpoint. Check `check_credits` / `GET /v1/account` before a big run so you don't burn through the free tier on one oversized sweep. ## The workflow **1. Get a key before calling anything.** Same as above — never guess or fabricate one; every call fails with `401` without a real one. **2. Understand the actual ask before searching — there's no product to confirm here, so confirm the query instead.** "Monitor r/reactjs" and "monitor r/reactjs for people frustrated with build times" are completely different searches with completely different results. State back what you're searching for, which subreddit(s) if named, the time window, and what a "relevant" result looks like for this specific request — then search. Getting this wrong means every result downstream is answering the wrong question. **3. Find the right communities.** `search_subreddits` / `GET /v1/subreddits/search?q=`. Search from the actual topic, not just the closest-sounding subreddit name — the community that talks about something most isn't always the one whose name says so. Ask whether the user already knows subreddits worth watching. **4. Search with more than one phrasing.** People describing the same thing rarely all use the same words. Generate a few variations of how the topic would actually come up in conversation, not just the one obvious keyword — this matters more for open-ended topics than for a single named brand or product, where the term itself is usually distinctive enough. **5. Pull candidates.** `search_posts` / `search_comments` with `subreddit=` and a time window matching the request. `q=` is a client-side exact-phrase filter on **the single page already fetched** — an empty result after filtering does NOT mean nothing matches. Keep paginating with the returned `cursor` until `has_more` is false. Reading raw pages and judging by meaning beats relying on `q=` alone — but only at a small `limit`. A full `limit=100` page of real post/comment bodies is large enough to blow past a tool call's own output limit outright (a live run of this skill hit exactly this on r/SaaS). Default to `q=` for the scanning pass across many pages, and only drop to reading raw content (`limit=25` or less) once you're down to a shortlist worth reading in full — not as the first move on a whole unfiltered page. One more thing a live run surfaced: active subreddits move fast. r/SaaS covered its most recent 100 posts in about 5 hours; a quieter subreddit like r/Entrepreneur took about 4 days for the same 100. Covering a multi-day window on a busy subreddit can take many pages — budget for that, and say in the report how much of the requested window you actually covered if you had to stop short. Also skip content Reddit has already gutted before you judge it. A candidate with `removed_by_category` set, or `selftext`/`body` exactly `[removed]` or `[deleted]`, no longer has real text behind it even though the API still returns the record shell — don't quote from it as if the content were intact (a live run hit exactly this: a matched title, but the body was `[removed]`, and it was cross-posted to a second subreddit under the same title, also removed there). If the title alone still makes it worth including, flag it in the report (⚠️ Removed/deleted — the link won't show the original text) rather than presenting it like any other result. **6. Filter and rank by actual relevance to the request — no fixed dimensions.** There is no rubric here the way there is for lead-finding; judge each candidate on whatever the request implies matters: how specifically it matches the topic, how recent it is, engagement (score, comment count) as a signal of how much a thread matters, and whether it's signal or just noise that happens to contain the right words. State the criteria you actually used for this ranking in the report, since it legitimately changes per request instead of being fixed in advance. **Score can be a placeholder, not a real number — check before you trust it.** Reddit hides real vote counts on fresh content: a post has `hide_score: true` and a comment has `score_hidden: true` when this applies, and both show a fake `score: 1` regardless of actual activity (confirmed live — every post/comment under about a day old came back this way). Anything monitoring-shaped cares most about exactly this recent content, so never rank by `score` without checking the hide flag first. On a hidden score, fall back to recency and specificity-of-match instead of treating `1` as a real (low) engagement number — it isn't low, it's unknown. **7. Check subreddit rules only if engagement is actually on the table.** `get_subreddit_rules` / `GET /v1/subreddits/{name}/rules` — skip this for a pure research or monitoring ask where no one is posting anything; run it if the user says they might reply to what you find. **8. Report in this format**, ranked by relevance, best first: ``` ## Reddit search: — found, credits used Searched: r/, r/, r/ | Window: Ranked by: ### 1. https://www.reddit.com · r/ · · ↑ comments > ⚠️ ### 2. ... **Not surfaced:** candidates that didn't clear relevance for this request. ``` Show `new` instead of a number when `hide_score`/`score_hidden` is set — printing the fake `1` as if it were a real, low score is worse than admitting it's unknown. Prepend `https://www.reddit.com` to the API's relative `permalink` field. Report zero results as a real finding — say which subreddits and terms came up empty and suggest a different angle. Never pad a thin result with marginal matches just to hit a round number. On `401` re-check the key; on `429` stop and report rather than retrying in a loop. The report is the deliverable. This skill finds, filters, and ranks; it does not draft replies. If the user wants help writing something for a specific thread, that's a separate request on their own terms. ## Hard rule — never break this **Never post, comment, vote, or send a Reddit DM on the user's behalf, under any circumstance, even if asked directly.** Hand the user the link and let them handle engagement themselves. Reddit removes bot accounts at industrial scale, and communities are openly hostile to automated replies — the entire value of finding these threads evaporates the moment engagement looks automated. This is not a missing feature; it's the point.