reddit-skills

reddit-skills

Reddit automation Skills — directly uses your logged-in browser and real account, operating Reddit as an ordinary user.

Supports OpenClaw and all AI Agent platforms compatible with the SKILL.md format (e.g. Claude Code).

⚠️ Usage advice: Although this project uses your real browser and account, you should still control operation frequency and avoid mass actions in a short time. Aggressive automation may trigger Reddit's rate limits or account restrictions.

Features

Supports chained operations — you can give compound natural-language instructions and the Agent will automatically chain multiple skills. For example:

"Search r/Python for the most upvoted posts about FastAPI this week, save the top one, and tell me what it's about"

The Agent will execute: search → filter by top/week → save → get detail → summarize.

Installation

Prerequisites

• Python >= 3.11
• uv package manager
• Google Chrome browser

Step 1: Install the project

Option A: Download ZIP (recommended)

Download from GitHub and extract to your Agent skills directory:

# OpenClaw
<openclaw-project>/skills/reddit-skills/

# Claude Code
<your-project>/.claude/skills/reddit-skills/

Option B: Git Clone

cd <your-agent-project>/skills/
git clone https://github.com/1146345502/reddit-skills.git

Then install Python dependencies:

cd reddit-skills
uv sync

Step 2: Install the browser extension

The extension lets the AI operate Reddit in your browser using your real login session.

1. Open Chrome, navigate to chrome://extensions/
2. Enable Developer mode (top right)
3. Click Load unpacked, select this project's extension/ directory
4. Confirm the Reddit Bridge extension is enabled

Once installed, you're ready to go — all actions happen in your own browser, using your real account.

Usage

As an AI Agent skill (recommended)

After installing to a skills directory, just talk to the Agent in natural language. It will route your intent to the right skill automatically.

Authentication:

"Check if I'm logged in to Reddit" / "Log out of Reddit"

Search & Browse:

"Search Reddit for posts about machine learning" / "Show me the top posts on r/Python"

Submit content:

"Submit a text post to r/learnpython with this title and body..."

Interact:

"Upvote this post" / "Comment on this post: Great write-up!" / "Save this post"

Compound operations:

"Analyze the top posts in r/startups this month and summarize the common themes"

As an MCP server

reddit-skills includes a built-in Model Context Protocol server, making it compatible with any MCP client (Claude Desktop, Cursor, etc.).

Start the server (stdio):

cd reddit-skills
python scripts/mcp_server.py

Configure in your MCP client (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "reddit-skills": {
      "command": "python",
      "args": ["scripts/mcp_server.py"],
      "cwd": "/path/to/reddit-skills"
    }
  }
}

The server exposes 16 tools: check_login, logout, home_feed, subreddit_feed, search, get_post_detail, user_profile, subreddit_rules, post_comment, reply_comment, upvote, downvote, save_post, submit_text_post, submit_link_post, submit_image_post.

Environment variables:

As a CLI tool

All features can be called directly from the command line, with JSON output for scripting.

# Check login status
python scripts/cli.py check-login

# Browse a subreddit
python scripts/cli.py subreddit-feed --subreddit python --sort hot

# Search posts
python scripts/cli.py search --query "FastAPI tutorial" --sort top --time month

# Get post details and comments
python scripts/cli.py get-post-detail \
  --post-url "https://www.reddit.com/r/Python/comments/abc123/title/"

# Submit a text post
python scripts/cli.py submit-text \
  --subreddit learnpython \
  --title-file title.txt \
  --body-file body.txt

# Submit a link post
python scripts/cli.py submit-link \
  --subreddit programming \
  --title-file title.txt \
  --url "https://example.com/article"

# Submit an image post
python scripts/cli.py submit-image \
  --subreddit pics \
  --title-file title.txt \
  --images "/abs/path/image.jpg"

# Comment on a post
python scripts/cli.py post-comment \
  --post-url "https://www.reddit.com/r/Python/comments/abc123/title/" \
  --content "Thanks for sharing!"

# Upvote / Downvote / Save
python scripts/cli.py upvote --post-url "https://www.reddit.com/r/..."
python scripts/cli.py downvote --post-url "https://www.reddit.com/r/..."
python scripts/cli.py save-post --post-url "https://www.reddit.com/r/..."

# View user profile
python scripts/cli.py user-profile --username spez

On first run, if Chrome is not open, the CLI will auto-launch it.

CLI Command Reference

Exit codes: 0 success · 1 not logged in · 2 error

Project Structure

reddit-skills/
├── extension/                  # Chrome Extension (MV3)
│   ├── manifest.json
│   └── background.js
├── scripts/                    # Python automation engine
│   ├── reddit/                 # Core automation library
│   │   ├── bridge.py           # Extension bridge client
│   │   ├── selectors.py        # CSS selectors (centralized)
│   │   ├── login.py            # Login check + logout
│   │   ├── feeds.py            # Home feed + subreddit feed
│   │   ├── search.py           # Search + filters
│   │   ├── post_detail.py      # Post detail + comment loading
│   │   ├── user_profile.py     # User profile
│   │   ├── comment.py          # Comment, reply
│   │   ├── vote.py             # Upvote, downvote, save
│   │   ├── publish.py          # Post submission
│   │   ├── types.py            # Data types
│   │   ├── errors.py           # Exception hierarchy
│   │   ├── urls.py             # URL constants
│   │   └── human.py            # Behavior simulation
│   ├── cli.py                  # Unified CLI entry point
│   ├── mcp_server.py           # MCP server wrapper (stdio/HTTP)
│   ├── bridge_server.py        # Local WebSocket bridge
│   └── image_downloader.py     # Image download with local cache
├── skills/                     # AI Agent skill definitions
│   ├── reddit-auth/SKILL.md
│   ├── reddit-publish/SKILL.md
│   ├── reddit-explore/SKILL.md
│   ├── reddit-interact/SKILL.md
│   └── reddit-content-ops/SKILL.md
├── SKILL.md                    # Skill router (routes to sub-skills)
├── CONTRIBUTING.md             # Contributor guide
├── Dockerfile                  # Container build for MCP deployment
├── pyproject.toml
└── README.md

Development

uv sync                    # Install dependencies
uv run ruff check .        # Lint
uv run ruff format .       # Format
uv run pytest              # Run tests

License

MIT