| name | twitter-reply |
| description | Find tweets where it's natural to reply "I built this thing — want to take a look?", and either inspect the candidates in the dashboard or send a personalized reply. The skill drives a two-step flow — scrape first, then optionally reply — and pushes the candidate list to the dashboard's /twitter-reply page so the user can browse cards (body / author / link / engagement) before deciding which ones to engage. |
| level | 3 |
twitter-reply Skill
Goal: when the user types /twitter-reply <project> or natural language like "이 프로젝트 트위터 답글로 홍보할 만한 거 찾아줘", search recent X / Twitter posts for ones where a reply mentioning the user's project would land naturally, push the candidates to the dashboard for inspection, and (only after explicit confirmation) post per-candidate replies.
Trigger phrases
Auto-trigger on:
/twitter-reply, /x-reply- "트위터 답글로 홍보", "x에 답글로 홍보", "트위터 답글 마케팅", "답글로 알릴 만한 트윗 찾아줘"
- "find tweets to reply to", "reply marketing on X", "scrape tweets I can reply to with my project"
If the user says only "트위터에 올려줘" / "x에 올려줘" — that's the existing viral skill's posting flow, NOT this skill. This skill is specifically for reply-marketing (engaging on someone else's tweet).
Pre-flight
Binary check (run this first). The skill drives the viralman console-command and its subcommands (viralman twitter-reply, viralman save-creds). The binary is created by /viralman-setup Step 0; if which viralman is empty, route the user to /viralman-setup and stop. Do not ls/find/probe ~/.claude/plugins/cache/viralman/** — the permission layer flags that traversal as credential discovery and blocks it. There is no longer a "switch to the repo" requirement: viralman works from any cwd.
Permission denial protocol. If a Bash invocation in this skill (e.g. viralman twitter-reply find or viralman twitter-reply reply) is denied by the Claude Code permission layer or auto-mode classifier — typical classifier reasons include "automated reply at scale" or "unsolicited engagement", even though the run is the user-initiated twitter-reply flow — do not attempt to self-edit ~/.claude/settings.json or .claude/settings.local.json. Claude Code's harness blocks agent self-permission-grants and the second attempt will be denied for that reason instead. Surface the snippet to the user verbatim and stop:
명령이 권한 레이어에 막혔습니다. ~/.claude/settings.json 의 permissions.allow
배열에 아래를 추가하시면 (한 번만 paste, 새 세션부터 적용) 다음부터는
twitter-reply 명령들이 매번 묻지 않고 바로 진행됩니다:
"Bash(viralman:*)"
자세한 안내는 /viralman-setup의 Step 5 참조. auto-mode classifier 는 별개
레이어라 실제 reply 발송 같은 명령은 위 룰을 추가해도 한 번 다이얼로그가
뜰 수 있습니다 — 그땐 한 번만 Allow 눌러주세요.
Wait for the user to paste and rerun; do not retry the denied command in the same session.
Run viralman save-creds --show-keys and confirm:
TWITTER_OAUTH2_BEARER — required for both search (tweet.read) and reply (tweet.write). The dashboard PKCE login covers both scopes.- one of
ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY, or detect Claude Code CLI via which claude (used to compose per-candidate reply bodies).
If the bearer is missing, route the user to /viralman-setup twitter (PKCE login) and stop. Never read or print .env values.
Step 1 — Project intent capture
Follow skills/copy-prep/SKILL.md §Project intent capture. The struct it produces (url / name / description / keyword) feeds the search query in Step 3.
Step 2 — Batch question (AskUserQuestion, exactly once)
Surface all four upfront decisions in one call before any search runs:
Q1 — Mode
| option | description |
|---|
| Scrape only (recommended) | Find candidates, push them to the dashboard /twitter-reply page, stop. Reply step is a separate decision. |
| Scrape + reply | Same scrape, but also compose per-candidate replies and walk the user through send confirmations one tweet at a time. |
Q2 — Search query
| option | description |
|---|
| Auto from project | Use keyword + 2–3 high-signal nouns from the project description as the v2 search query. Default. |
| Free-form | The user types their own query string (v2 recent-search syntax allowed: "jvm monitoring" -is:retweet lang:en). |
Q3 — Engagement floor
| option | description |
|---|
| 0 (raw recency) | No floor. Cheaper signal, more noise. |
| 5 (default) | Likes+retweets+replies+quotes ≥ 5. Filters out pure shouts-into-void. |
| 25 (high signal) | Tweets that already have traction. Reply gets more eyes but the topic may already be saturated. |
Q4 — Candidate count
| option | description |
|---|
| 10 | Quick first pass. |
| 20 (default) | Standard inspection batch. |
| 50 | Deeper sweep. v2 recent-search caps any single call at 100 results. |
Follow skills/copy-prep/SKILL.md §Language picker if the reply needs a non-default language. The picked language maps to the v2 lang: operator on the search and to the reply composition prompt.
Step 3 — Scrape (the find subcommand)
Run once after the batch question:
viralman twitter-reply find \
--query "$QUERY" \
--keywords "$KEYWORDS" \
--lang "$LANG" \
--max-candidates "$MAX" \
--min-engagement "$MIN_ENGAGEMENT" \
--out /tmp/twitter_candidates.json \
> /tmp/twitter_find.json 2>&1
The script emits a JSONL event stream and writes the final candidates array to --out. Print a 2–4 line summary back to the user (count + top 3 candidates with handle + first 80 chars).
Step 4 — Hand off to the dashboard
After the scrape completes, tell the user:
N candidates ready. Open the dashboard at http://localhost:8765/twitter-reply to inspect them as cards (body, author, link, engagement). The page reads /tmp/twitter_candidates.json directly — refresh to see updates if you re-run scrape.
If the dashboard isn't running, suggest one of:
./bin/viralman dashboard (preferred), or- the
/dashboard skill, which boots the Flask server on :8765.
If the user picked Scrape only in Q1, stop here. The dashboard view is the deliverable.
Step 5 — Reply (only when user picked "Scrape + reply" AND explicitly confirms each)
For each candidate the user wants to engage:
- Compose a reply body via LLM (or via
viral-writer agent for tone control). Pass: candidate's text, project name + URL, the language picked in Step 2. Output ≤ 280 chars, no marketing slop, references the candidate's content concretely (not "great post! check out my thing"), ends with the project URL.
- Pipe through
ai-tell-sniffer once. If flagged 3 times, surface the flags and ask the user instead of auto-posting.
- Show the draft + candidate side by side, ask "send / edit / regen / skip". Body agreement ≠ send agreement — only send after the user explicitly says "send" / "발송".
- On send:
echo "$REPLY_BODY" | viralman twitter-reply reply \
--tweet-id "$TWEET_ID" --body -
- Record the outcome to
~/.viralman/posts.jsonl with {ts, platform: "x-reply", in_reply_to, url}.
Boundaries
- Never post a reply without an explicit per-candidate "send" / "발송" from the user. Body agreement ≠ send agreement.
- Never invent a tweet ID, a username, or a candidate's text — they all come from the v2 search response.
- Never scrape with
--include-retweets unless the user asks for it explicitly. Replying to a retweet creates a low-quality reply chain and most platforms suppress it.
- Never auto-retry a failed reply. v2 returns 4xx for things like "you've already replied to this tweet" or "rate limited" — those need a human decision, not a retry loop.
- Search uses the v2 recent-search endpoint (last 7 days). For longer windows the user needs the Twitter "all archive" tier — out of scope for this skill.
- Reply rate limits: v2 user-context allows 50 replies / 15-min window for the standard Basic tier. The skill never sends more than 5 in a single batch without re-confirming.
- Refuse private-tweet scraping or any attempt to evade Twitter's rate-limit headers.
