reddit-readonly

Q: How do I install reddit-readonly?

Run npx skills add https://github.com/tristanmanchester/agent-skills --skill reddit-readonly in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/reddit-readonly/ (personal) or .claude/skills/reddit-readonly/ (project).

by tristanmanchesterMarketing & SEO

Browse and search Reddit in read-only mode using public JSON endpoints. Use when the user asks to browse subreddits, search for posts by topic, inspect comment threads, or build a shortlist of links to review and reply to manually.

Installs: 432
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/tristanmanchester/agent-skills --skill reddit-readonly

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads reddit-readonly automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Reddit Readonly

Read-only Reddit browsing for Clawdbot.

What this skill is for

Finding posts in one or more subreddits (hot/new/top/controversial/rising)
Searching for posts by query (within a subreddit or across all)
Pulling a comment thread for context
Producing a shortlist of permalinks so the user can open Reddit and reply manually

Hard rules

Read-only only. This skill never posts, replies, votes, or moderates.
Be polite with requests:
- Prefer small limits (5–10) first.
- Expand only if needed.
When returning results to the user, always include permalinks.

Output format

All commands print JSON to stdout.

Success: { "ok": true, "data": ... }
Failure: { "ok": false, "error": { "message": "...", "details": "..." } }

Commands

1) List posts in a subreddit

node {baseDir}/scripts/reddit-readonly.mjs posts <subreddit> \
  --sort hot|new|top|controversial|rising \
  --time day|week|month|year|all \
  --limit 10 \
  --after <token>

2) Search posts

# Search within a subreddit
node {baseDir}/scripts/reddit-readonly.mjs search <subreddit> "<query>" --limit 10

# Search all of Reddit
node {baseDir}/scripts/reddit-readonly.mjs search all "<query>" --limit 10

3) Get comments for a post

# By post id or URL
node {baseDir}/scripts/reddit-readonly.mjs comments <post_id|url> --limit 50 --depth 6

4) Recent comments across a subreddit

node {baseDir}/scripts/reddit-readonly.mjs recent-comments <subreddit> --limit 25

5) Thread bundle (post + comments)

node {baseDir}/scripts/reddit-readonly.mjs thread <post_id|url> --commentLimit 50 --depth 6

6) Find opportunities (multi-subreddit helper)

Use this when the user describes criteria like: "Find posts about X in r/a, r/b, and r/c posted in the last 48 hours, excluding Y".

node {baseDir}/scripts/reddit-readonly.mjs find \
  --subreddits "python,learnpython" \
  --query "fastapi deployment" \
  --include "docker,uvicorn,nginx" \
  --exclude "homework,beginner" \
  --minScore 2 \
  --maxAgeHours 48 \
  --perSubredditLimit 25 \
  --maxResults 10 \
  --rank new

Suggested agent workflow

Clarify scope if needed: subreddits + topic keywords + timeframe.
Start with find (or posts/search) using small limits.
For 1–3 promising items, fetch context via thread.
Present the user a shortlist:
- title, subreddit, score, created time
- permalink
- a brief reason why it matched
If asked, propose draft reply ideas in natural language, but remind the user to post manually.

Troubleshooting

If Reddit returns HTML, re-run the command (the script detects this and returns an error).
If requests fail repeatedly, reduce --limit and/or set slower pacing via env vars:

export REDDIT_RO_MIN_DELAY_MS=800
export REDDIT_RO_MAX_DELAY_MS=1800
export REDDIT_RO_TIMEOUT_MS=25000
export REDDIT_RO_USER_AGENT='script:clawdbot-reddit-readonly:v1.0.0 (personal)'

FAQ

What does the reddit-readonly skill do?

How do I install reddit-readonly?

Run npx skills add https://github.com/tristanmanchester/agent-skills --skill reddit-readonly in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/reddit-readonly/ (personal) or .claude/skills/reddit-readonly/ (project).

Which AI agents can use reddit-readonly?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is reddit-readonly safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains reddit-readonly?

It is published by tristanmanchester in tristanmanchester/agent-skills. It has 432 recorded installs.