reddit-marketing

Reddit Marketing Skill

Help the user run a low-risk, value-first marketing campaign on Reddit using PRAW. Every comment and post requires explicit user approval before it is sent. No exceptions.

Why this skill exists

Reddit is one of the highest-trust referral surfaces on the web and one of the easiest places to get permanently banned for ham-fisted promotion. Almost every large subreddit removes self-promo on sight; site-wide guidance is that ≥90% of an account's activity should be non-promotional. A naive "post product link in 50 threads" loop will get the account, the domain, and sometimes the IP shadowbanned within a day.

This skill exists to do the opposite: identify threads where the product is actually the best answer to the question being asked, draft a response that leads with genuine help, disclose the connection, and ask the human before hitting submit. The cost of a "wrong" post is high (ban + domain blacklist), so the workflow biases hard toward caution.

When to use this skill

The skill activates whenever a user wants to engage on Reddit on behalf of a product. Typical triggers:

• "Find Reddit threads where I could mention "
• "Draft a reply to this Reddit post about "
• "Help me run a Reddit campaign for "
• "Where on Reddit should I talk about ?"

Use it even when the user says "marketing on Reddit" without specifying how — the skill's whole job is to translate that vague intent into rule-checked, human-approved drafts.

Two account profiles

Ask the user up front: fresh account or established account?

	Fresh account (<3 months old, low karma)	Established account (older, real history)
Default posture	Lurk and comment first, no submissions, no links for the first N approved comments	Comments OK; submissions allowed if subreddit rules permit
Per-account daily comment cap	3	10
Allowed to include product link?	No, mention by name only with disclosure	Yes, one link max, with disclosure
Subreddits to avoid	Any sub that auto-removes low-karma users (r/AskReddit, r/personalfinance, large defaults)	Subs that explicitly forbid self-promo
Sentiment guard threshold	Skip if post has any flame-war signals	Skip if post is hostile toward competitor or product category

Read references/fresh_account_workflow.md or references/established_account_workflow.md for the full per-profile playbook before drafting any comment.

The orchestration loop

Follow this sequence. Skip steps only when the user explicitly says so.

1. Understand the product

Ask the user for either a URL or a .md file path describing the product. Run:

uv run ${CLAUDE_PLUGIN_ROOT}/skills/reddit-marketing/scripts/analyze_product.py --source <url-or-path>

This returns a JSON object: {summary, value_props, target_personas, suggested_keywords} with 3–5 keyword candidates. Show the keywords to the user and ask:

"Here are 5 candidate search terms. Want to add, remove, or change any?"

Capture the final keyword list before continuing.

2. Confirm scope

Ask three short questions in one turn:

1. Time window? (day / week / month / year)
2. Account profile? (fresh / established) + Reddit username
3. Subreddit preferences? (provide a list, or have the skill discover them)

3. Account health check

Run:

uv run ${CLAUDE_PLUGIN_ROOT}/skills/reddit-marketing/scripts/check_account_health.py --username <user>
uv run ${CLAUDE_PLUGIN_ROOT}/skills/reddit-marketing/scripts/check_promo_ratio.py --username <user>

If the account is fresh AND the user picked the established workflow, switch them to fresh — explain why (low karma triggers spam filters regardless of comment quality). If the promo ratio is already worse than 1:9, warn and recommend a non-promotional comment session before continuing.

4. Search and filter

For each keyword, run:

uv run ${CLAUDE_PLUGIN_ROOT}/skills/reddit-marketing/scripts/search_posts.py --keyword "<kw>" --time <window> --limit 25

Combine and dedupe by post id. Then for each unique subreddit that appears, run:

uv run ${CLAUDE_PLUGIN_ROOT}/skills/reddit-marketing/scripts/score_subreddit.py --sub <name>

Drop subreddits that score below threshold or that the rules cache marks as self_promo: forbidden. Rank remaining posts by (post_score * sub_relevance) / age_hours^0.5 — this favors recent, popular, on-topic threads.

Important: the search and rules-fetch scripts cache results to ./reddit-skill-state/cache/. They will return the cache for 6 hours rather than re-hitting the API. Do not bypass the cache unless the user asks for fresh data — the goal is minimal API calls.

5. Per-post: rules → context → draft → approve

For each candidate post in ranked order, do this sequence. Stop early if the user has approved enough comments to hit their daily cap (see profile table).

a. Rules check. Run uv run ${CLAUDE_PLUGIN_ROOT}/skills/reddit-marketing/scripts/fetch_rules.py --sub <name>. Read the output. Decide one of:

• forbidden — sub explicitly bans self-promo. Skip this post entirely; don't even draft.
• restricted — sub has rules like "must contribute X non-promo posts first" or "must be flaired". Surface the restriction to the user; skip unless user explicitly says proceed.
• allowed — proceed.

b. Context fetch. Run uv run ${CLAUDE_PLUGIN_ROOT}/skills/reddit-marketing/scripts/fetch_post.py --post-id <id>. This returns the post body + top 10 comments. Read it carefully. Specifically check for:

• Hostility / flame war. If the post or top comments are angry or hostile, skip. A pitch in a hostile thread reads as predatory.
• Already-answered. If the top comment already gives the same advice you'd give, your reply will look redundant or like piling on. Skip or reframe.
• Competitor-bashing post. "X sucks, what should I use instead?" — tempting but predatory. Default to skip; if the user wants to engage, the comment must lead with neutral advice including alternatives, not a pitch.
• Question vs rant. Genuine questions are good targets. Rants and vents are not.

c. Draft the comment. Use the patterns in references/comment_patterns.md. The draft must:

• Lead with a useful answer to the actual question being asked. The reader should get value even if they ignore the product mention entirely.
• Include disclosure ("I work on X", "Disclosure: I built X") near the product mention. Non-negotiable.
• Mention the product at most once, in at most one sentence.
• Match the subreddit's tone (technical subs ≠ casual subs).
• Respect the per-profile link policy from the table above.

d. Present for approval. Show the user a single block per post:

─── r/<sub> · <post title> ─── <link>
Rules verdict: <allowed/restricted> — <one-line reason>
Post excerpt: <2–3 lines>
Sentiment: <neutral/positive/negative>
Already-answered risk: <low/med/high>
Ban-risk assessment: <low/med/high> — <why>

Draft comment:
> <draft>

Action? [post / skip / rewrite "<note>"]

Wait for the user. Never call post_comment.py without an explicit "post" from the user for that specific draft.

e. Post and verify. When the user approves:

uv run ${CLAUDE_PLUGIN_ROOT}/skills/reddit-marketing/scripts/post_comment.py --post-id <id> --body-file <path> --confirm

The --confirm flag is the discipline: never pass it unless the user just approved this specific draft. After posting, wait ~60 seconds and run:

uv run ${CLAUDE_PLUGIN_ROOT}/skills/reddit-marketing/scripts/verify_visible.py --comment-id <id>

This checks the comment is visible to logged-out users. If it isn't, the comment was likely auto-removed by the subreddit's spam filter or AutoModerator. Tell the user; do not retry on the same post.

6. End-of-session summary

After the session, show: posts reviewed, comments posted, comments removed, current promo ratio, and any subreddits flagged as restricted that the user might want to come back to after building karma.

Hard rules

1. Never post without explicit approval for that specific draft. A general "go ahead with the campaign" is not approval for any specific comment.
2. Never pass --confirm to a write script speculatively. No dry-run of a real post.
3. Never strip the disclosure. If the user asks to remove it, push back: explain the FTC guidance and the karma-cost when caught. If they insist, do it but flag the increased ban risk in the approval block.
4. Never bypass the rules cache without reason. API calls are not free in rate-limit budget; refetching the same rules per comment is wasteful and looks botty.
5. Never post on a flame-war thread or competitor-bashing thread without warning the user about predatory perception.
6. Never recommend more than the per-profile daily cap. The cap exists to keep the promo ratio sustainable.

State and audit

Everything writes to ./reddit-skill-state/:

reddit-skill-state/
├── cache/
│   ├── rules-<sub>.json
│   ├── search-<hash>.json
│   └── post-<id>.json
├── audit.jsonl              # append-only log of every action
└── pending/<id>.json        # drafts awaiting user decision

The audit log is the source of truth for the promo-ratio check and for showing the user what they've done across sessions. Every write script appends one line.

When the user pushes for a shortcut

If the user says "just post it, skip the rules check" or "force post, I don't care about the rule":

1. Restate the specific risk (ban + comment removal + sub blacklist).
2. Offer to post anyway with a rule-aware rewrite — often a small tweak to phrasing satisfies the rule without losing the message.
3. If the user still insists after that, post it. Add force_posted: true to the audit log entry so future sessions can see the override.

This is a guardrail, not a refusal. The user has authority over their own account; the skill's job is to make sure they understand the cost before they pay it.

References

• references/auth_setup.md — How to register a Reddit script app and configure PRAW credentials
• references/fresh_account_workflow.md — Detailed playbook for accounts <3 months old or with low karma
• references/established_account_workflow.md — Playbook for accounts with real history
• references/rule_compliance.md — How to read subreddit rules; common patterns; the forbidden / restricted / allowed taxonomy
• references/comment_patterns.md — Value-first comment templates with disclosure; tone-matching guidance per subreddit category

Tool scripts

All scripts live at ${CLAUDE_PLUGIN_ROOT}/skills/reddit-marketing/scripts/ and use PEP 723 inline dependencies — run them with uv run. Each script accepts --help and outputs JSON to stdout for easy parsing. Cache and audit state always writes to ./reddit-skill-state/ in the user's current working directory, so different projects keep separate state.

Read-only (cheap, cache-aware):

• scripts/analyze_product.py — URL or .md → product summary + keywords
• scripts/search_posts.py — keyword + time window → posts
• scripts/score_subreddit.py — sub name → relevance, members, activity, self-promo policy summary
• scripts/fetch_rules.py — sub name → rules + cached verdict
• scripts/fetch_post.py — post id → post body + top comments
• scripts/check_account_health.py — username → karma, age, recent removed, shadowban check
• scripts/check_promo_ratio.py — username → ratio over local audit log
• scripts/verify_visible.py — comment/post id → logged-out visibility check

Write (gated by --confirm, must have explicit user approval):

• scripts/post_comment.py
• scripts/post_submission.py

Helper:

• scripts/_audit.py — shared module for reading/writing audit.jsonl
• scripts/_praw_client.py — shared PRAW client factory

If uv is not available, fall back to pip install praw requests beautifulsoup4 in a venv and python ${CLAUDE_PLUGIN_ROOT}/skills/reddit-marketing/scripts/<script>.py.