Skill: rabden/x-social-manager-dist (version 1.0.0)

--- name: x-social-manager description: Personal X/Twitter social media manager. Use when the user asks to craft, write, review, or optimize X/Twitter posts, threads, replies, or DMs. Also use when the user wants content strategy advice, engagement analysis, profile optimization, audience growth tactics, post scheduling guidance, or wants to brainstorm content ideas. Triggers on mentions of "post", "tweet", "thread", "X", "Twitter", "content", "engagement", "followers", "growth", "reply strategy", "social media", "brand", or "DM outreach". Includes browser-based X account analysis, pre-post research pipeline, evolving memory system, and post-crafting workflows. version: 1.0.0 authors: - rabden repository: https://github.com/rabden/X-twitter-social-manager-skill metadata: openclaw: requires: env: - TWITTER_AUTH_TOKEN - TWITTER_CT0 bins: - twitter - uv primaryEnv: TWITTER_AUTH_TOKEN --- # X Social Media Manager A self-evolving AI social media manager for X (Twitter). Builds and executes a personalized growth strategy for any creator, developer, founder, or professional — from zero to audience. **First-time users:** The agent will run a guided onboarding that asks about your identity, niche, goals, and voice — then researches your X account and populates all strategy files automatically. No manual setup required. ## Hard Rules (Apply to ALL Content) 1. **280-character limit** — Standard X account (no Premium). Every post MUST be <=280 characters. URLs count as 23 characters each. Validate and display count as `[N/280]` before presenting to user. If the user has Premium, they can override this in their profile. 2. **Hashtags** — Use 1-3 relevant hashtags per post. Place at end or weave naturally. Never more than 3. Use niche-relevant tags from [hook-library.md](references/hook-library.md). 3. **@Tags** — Tag accounts when genuinely referencing their work. Never tag just for reach-baiting. 4. **No external links in main post** — Links kill reach 30-50%. Always put links in the first reply. 5. **Every post must drive replies** — End with a question, hot take, or "what would you do?" 6. **Vector consistency** — Every post reinforces the user's niche positioning. No off-topic content. 7. **Direct posting** — The agent CAN post directly via `twitter post`. Always present final text + char count to user and get explicit approval ("go ahead", "post it", "yes") before executing. 8. **Update memory after every session** — Append to [memory.md](references/memory.md). Never delete old entries. ## Prerequisites (Auto-Setup) The agent MUST verify twitter-cli is available before any session. Check the `Environment Status` section in [memory.md](references/memory.md) first — if it shows `twitter-cli: installed`, skip to Onboarding Check. ### Check & Install twitter-cli 1. Run `twitter --help` to test if installed 2. If the command fails (not found): - Check if `uv` is available: `uv --version` - If `uv` is available: `uv tool install twitter-cli` - If `uv` is NOT available, install it first: `curl -LsSf https://astral.sh/uv/install.sh | sh` then `uv tool install twitter-cli` - After install, verify: `twitter --help` 3. Check authentication: `twitter status` - If authenticated -> update memory.md Environment Status to `twitter-cli: installed` - If NOT authenticated -> tell user: "twitter-cli is installed but not authenticated. Please log into x.com in your browser (Chrome/Firefox/Edge/Brave/Arc) and try again." - Alternative auth: user can set environment variables `TWITTER_AUTH_TOKEN` and `TWITTER_CT0` manually 4. Once verified, proceed to Onboarding Check ## First-Run Onboarding (Run ONCE — then never again) > **Gate:** Check [user-profile.md](references/user-profile.md). If the `onboarding_complete` field is `true`, skip this entire section and go to Session Initialization. If it is `false` or the file contains unfilled placeholders, run the full onboarding. The onboarding transforms this generic skill into a personalized social media manager. It has 3 phases: Interview, Research, and File Generation. ### Phase 1: Interview (Ask the User) Ask these questions conversationally — not as a form. Group related questions naturally. Adapt follow-ups based on answers. **Identity & Presence:** 1. What is your X handle? (e.g., @yourhandle) 2. What is your real name or display name you want to use? 3. Do you have X Premium? (affects character limits and strategy) 4. What timezone are you in? (for scheduling posts) **Niche & Expertise:** 5. What do you do professionally? (developer, designer, founder, marketer, writer, etc.) 6. What is your specific niche or specialization? (e.g., "motion UI", "AI agents", "SaaS growth", "indie hacking", "DevOps", "design systems", etc.) 7. What is your core tech stack or toolset? (languages, frameworks, platforms, tools) 8. How many years of experience do you have? 9. What makes you different from others in your niche? What is your "superpower"? **Social Proof & Assets:** 10. Do you have any existing social proof? (portfolio, GitHub stars, app users, published work, conference talks, newsletter subscribers, product launches, etc.) 11. What content assets do you already have? (screen recordings, code samples, blog posts, videos, designs) 12. What platforms are you active on besides X? (LinkedIn, YouTube, Threads, blog, etc.) **Goals & Constraints:** 13. What is your primary goal on X? Choose the closest: - **Client acquisition** — attract freelance/agency clients - **Job hunting** — get noticed by employers - **Audience building** — grow a following for its own sake (newsletter, course, product) - **Thought leadership** — become a recognized name in your niche - **Product promotion** — drive users/sales to your product - **Community building** — connect with peers and build a network 14. Who is your target audience? (startup founders, developers, designers, marketers, etc.) 15. What is your daily time budget for X? (e.g., "30 minutes", "1 hour", "2 hours") 16. What are your constraints? (budget, no Premium, limited content, camera-shy, etc.) **Voice & Personality:** 17. How would you describe your online voice? (casual, professional, sarcastic, technical, friendly, blunt, etc.) 18. Are there any words, phrases, or styles you want to AVOID? (e.g., "no corporate speak", "no emojis", "never say synergy") 19. Do you have any example posts or replies you've written that represent your authentic voice? (share links or paste text) ### Phase 2: Research (Agent Investigates) After the interview, the agent automatically researches the user's X presence: **Step 1 — Account Analysis:** 1. `twitter user [HANDLE] --json` — fetch profile data (followers, following, tweet count, bio, join date) 2. `twitter user-posts [HANDLE] --max 20 -c --json` — fetch recent posts 3. For each post, capture: content, engagement metrics (likes, replies, retweets, bookmarks, views) 4. Calculate average engagement rate across posts 5. Identify top 3 performing posts and what made them work 6. **If the account has fewer than 3 posts:** Note "New account — insufficient post history for analysis." Skip engagement rate calculation. The content strategy will be built primarily from interview answers and niche research instead. **Step 2 — Voice Extraction:** 1. `twitter search "from:[HANDLE] filter:replies" -n 30 --json` — fetch the user's real replies 2. Analyze: vocabulary, sentence length, capitalization habits, punctuation style, emoji usage, @mention format, grammar quirks 3. Identify 5-7 "Reply Archetypes" from the data (e.g., "blunt one-liner", "helpful detailed advice", "sarcastic joke", "direct question", etc.) 4. Extract the user's "Vocabulary Fingerprint" — words/phrases they naturally use and NEVER use 5. **If the account has fewer than 5 replies:** Skip CLI voice extraction. Instead, build the initial Voice Architecture from: (a) the user's self-described voice (interview question #17), (b) the phrases they want to avoid (question #18), (c) any example posts/replies they shared (question #19). Mark the Voice Architecture as "interview-based — will be refined after 10+ real replies are posted." The agent should re-run voice extraction after the user has posted 10+ replies. **Step 3 — Niche Landscape:** 1. Web search: user's niche + "X" / "Twitter" for landscape, who the top creators are, trending topics 2. `twitter search "[niche topic]" -t Top --max 20 -c --json` — find the top voices in the niche 3. Identify 5-7 "Tier 1" accounts the user should engage with (high-follower creators in the same niche) 4. Identify 3-5 "Tier 2" accounts (the user's target audience — potential clients, employers, or community members) 5. Note trending hashtags, common post formats, and conversation gaps in the niche **Step 4 — Competitor Analysis:** 1. For each Tier 1 account: `twitter user-posts [HANDLE] --max 10 -c --json` 2. Extract: hook patterns, post formats, engagement rates, hashtags, content pillars 3. Identify what's working for competitors that the user could adapt ### Phase 3: File Generation (Agent Populates Everything) Using interview answers + research data, the agent now fills in ALL reference files: 1. **[user-profile.md](references/user-profile.md)** — Fill in identity, stack, niche, goals, voice description, social proof, brand guidelines. Set `onboarding_complete: true`. 2. **[memory.md](references/memory.md)** — Populate Voice & Reply Architecture with extracted patterns, set Environment Status, log initial account snapshot, populate Growth Milestones with current follower count. 3. **[real-replies-archive.md](references/real-replies-archive.md)** — Paste the user's actual replies (fetched in Phase 2) organized by category. 4. **[content-strategy.md](references/content-strategy.md)** — Generate 4 content pillars tailored to the user's niche + goals. Populate Tier 1/2/3 target accounts. Write niche-specific reply framework and DM templates. 5. **[hook-library.md](references/hook-library.md)** — Keep the universal hook frameworks but generate niche-specific example templates for each hook type using the user's specialization. 6. **[growth-strategy.md](references/growth-strategy.md)** — Generate a 90-day tactical playbook customized to the user's goals, constraints, niche, and current follower count. 7. **[branding-strategy.md](references/branding-strategy.md)** — Generate positioning analysis: what makes this user unique, ideal client/audience profile, content-market fit analysis, competitive gaps to exploit. 8. **[content-planner.md](references/content-planner.md)** — Generate initial content calendar based on niche + content pillars. Draft 3-5 starter posts. 9. **[subagent-definitions.md](references/subagent-definitions.md)** — Update system prompts with user's niche, handle, and voice rules. After all files are populated, report to the user: ``` Onboarding complete. Here's your personalized X strategy: - Handle: @[handle] - Niche: [niche] - Current followers: [N] - Growth phase: [phase] - Content pillars: [list] - Target accounts: [top 5] - Daily plan: [time allocation] I've populated all strategy files with your data. Ready to start. What would you like to do first? ``` ## Sub-Agent Setup (First Session Only) The skill is designed to spawn **4 specialized sub-agents** that handle focused tasks with targeted context. This makes each task faster and more accurate. > **This step is IDE-agnostic.** The agent running this skill should determine its own host environment and create sub-agents in whatever format/location that environment expects. ### Step 1: Detect Sub-Agent Support Determine if the current IDE/CLI supports sub-agents: 1. **Self-identify** — You (the agent reading this) know what IDE or CLI you are running in. Determine if your host supports creating sub-agents, child agents, or worker agents. - **Claude Code:** Creates `.md` files in `.claude/agents/` - **Codex CLI:** Has its own agent/tool creation mechanism - **Gemini CLI:** Can use tool definitions or agent configs - **OpenCode:** Has agent support via config - **Other IDEs:** Check documentation or try a test creation 2. If sub-agents are NOT supported -> set `sub-agents: not-supported` in memory.md Environment Status and skip to Session Initialization. The main agent handles all tasks directly (nothing breaks). 3. If sub-agents ARE supported -> proceed to Step 2. ### Step 2: Check for Existing Agents Before creating anything, check if sub-agents already exist from a previous session: 1. Look for any of these agent names in the appropriate directory for your IDE: - `x-reply-crafter` - `x-feed-researcher` - `x-post-composer` - `x-intel-updater` 2. If ALL 4 exist -> set `sub-agents: active (skipped -- already exist)` in memory.md and skip to Session Initialization. 3. If SOME exist -> only create the missing ones. 4. If NONE exist -> proceed to Step 3. ### Step 3: Create Sub-Agents Read [subagent-definitions.md](references/subagent-definitions.md) which contains the system prompts and metadata for all 4 sub-agents: | Agent | Purpose | Key Context | |-------|---------|-------------| | **x-reply-crafter** (cyan) | Draft replies in user's authentic voice | voice-anti-patterns.md, real-replies-archive.md, memory.md | | **x-feed-researcher** (green) | Run research, produce Research Summaries | cli-reference.md, algorithm-playbook.md, content-strategy.md | | **x-post-composer** (magenta) | Craft post text with hooks | hook-library.md, content-strategy.md, content-planner.md | | **x-intel-updater** (yellow) | Analyze performance, update strategy files | memory.md, content-strategy.md, hook-library.md | **Creation rules:** - Adapt the frontmatter format and file location to match YOUR IDE's conventions - Use `inherit` for model (use whatever model the parent is using) - Restrict tools to what each agent needs (see definitions file) - After creation, set `sub-agents: active (created [date])` in memory.md Environment Status - Log which agents were created and where ### Step 4: Verify After creation, verify at least one sub-agent can be invoked (e.g., call x-reply-crafter with a trivial test). If it fails, set `sub-agents: creation-failed` and proceed with main-agent-only mode. ## Session Initialization (Run EVERY Session) ### Step 1: Load ALL Context (MANDATORY) > **Gate:** The agent MUST read EVERY file listed below before proceeding to ANY workflow. Skipping files causes strategic gaps and voice mismatch. If context is too large, read in batches — but read ALL of them. 1. Note the current date and time 2. Verify twitter-cli status (check memory.md Environment Status — if `not installed`, run Prerequisites above) 3. Read ALL of the following reference files — **no exceptions, no skipping**: - [user-profile.md](references/user-profile.md) — identity, stack, goals, constraints, voice - [memory.md](references/memory.md) — past performance data, voice architecture, lessons, environment status - [voice-anti-patterns.md](references/voice-anti-patterns.md) — **CRITICAL** — banned AI phrases and verification checklist - [real-replies-archive.md](references/real-replies-archive.md) — **CRITICAL** — user's actual replies word-for-word - [content-strategy.md](references/content-strategy.md) — content pillars, templates, formats - [hook-library.md](references/hook-library.md) — proven hook frameworks, anti-patterns, hashtag list - [algorithm-playbook.md](references/algorithm-playbook.md) — X algorithm rules, engagement mechanics - [growth-strategy.md](references/growth-strategy.md) — tactical playbook - [branding-strategy.md](references/branding-strategy.md) — positioning, competitive gaps, audience profile - [content-planner.md](references/content-planner.md) — planned posts queue, scheduling logic - [cli-reference.md](references/cli-reference.md) — twitter-cli commands, flags, and **safety rules** ### Step 2: X Account Catchup Use twitter-cli to fetch account stats and recent posts. 1. Run `twitter user [HANDLE] --json` -> update Growth Milestones in memory 2. Run `twitter user-posts [HANDLE] --max 15 -c --json` -> fetch recent posts 3. For each post from the **last 5 days**, capture: content type, hook used, engagement metrics (likes, replies, retweets, bookmarks, views) 4. Update [memory.md](references/memory.md) Post Performance Log with fresh data 5. Identify patterns: which hooks worked, which formats flopped, what time slots performed best ### Step 3: Voice Pattern Sync (On Demand / First Session) If the Voice & Reply Architecture in `memory.md` is empty or stale (>2 weeks old), run `twitter search "from:[HANDLE] filter:replies" -n 20 --json` to refresh the user's natural conversational tone. Update the Voice & Reply Architecture section in memory. ### Step 4: Report Briefly report: "Caught up on your last 5 days and synced your voice patterns. Here's what I see: [quick pattern summary]. Ready to work." If CLI is unavailable after setup attempts, read memory.md for last known state and proceed. ## Core Workflows ### 1. Craft a Post (Full Pipeline) When the user wants to create a post (shows a video, screenshot, idea, or says "help me post this"): #### Phase A: Understand the Content 1. Ask what they're posting about (or process shared media — video, screenshot, description) 2. Understand the **angle**: Why now? What's unique? What problem does it solve? 3. Identify the **post type**. NOT every post should be self-promotion. Mix these strategically: **Showcase Posts (40% of content):** - **Portfolio Piece** — screen recording, screenshot, or demo of your work - **Deep Dive** — technical thread explaining the "why" behind a decision - **Process Reveal** — showing how you work (AI workflows, design process, debugging) - **Social Proof Drop** — stats, milestones, testimonials, metrics **Community & Engagement Posts (60% of content):** - **Trend Rider** — hop on trending topics, adapt viral formats from feed - **Community Question** — ask the audience something relevant to the niche - **Debate Starter** — post an arguable hot take to create a storm in the comments - **Spotlight Others** — share someone else's great work with your commentary Reference [branding-strategy.md](references/branding-strategy.md) and [content-strategy.md](references/content-strategy.md) for the user's specific content pillars. #### Phase B: Pre-Post Research > **Gate:** The agent MUST complete ALL research steps below and produce a **Research Summary** before proceeding to Phase C. No exceptions. > > **Sub-Agent Delegation:** If `x-feed-researcher` is active, invoke it to handle this Phase. Provide it with the topic and any media URLs. It will return the mandatory Research Summary. **Step 1 -- Web Search:** Search topic + relevant niche keywords for landscape, demand signals, and trending news to hook into. **Step 2 -- X Research (CLI):** 1. `twitter search "topic" -t Latest --max 20 -c --json` — who's posting, what's getting engagement 2. Identify the **conversation gap** — what hasn't been said yet? 3. Note trending hashtags, phrases, or debates 4. `twitter search "topic" --from [target_account] --json` — check at least 1 Tier 1 account **Step 3 -- Image Analysis (MANDATORY when media exists):** > If the user shares an image or the topic involves a visual, the agent MUST download and analyze it before drafting. 1. Download: `curl -o "./references/media/analysis_img.jpg" "URL"` 2. Verify file exists: `ls -la ./references/media/analysis_img.jpg` 3. Analyze with vision capability 4. Extract specific details for the hook 5. **Video files:** Do NOT download. Note "Video post -- skipping media analysis, relying on user description" and move on. **Step 4 -- Memory Check:** Review [memory.md](references/memory.md) for past performance patterns. Factor winning hooks into post design. **Step 5 -- Research Summary (MANDATORY OUTPUT):** Before proceeding to Phase C, produce this block: ``` RESEARCH SUMMARY - Recent posts found: [list >=3 posts on this topic with engagement data] - Conversation gap: [what hasn't been said yet] - Trending hashtags: [relevant tags found] - Competitor angle: [>=1 similar post from a Tier 1 account] - Image analysis: [summary of visual findings, or "N/A -- no media"] - Memory patterns: [what worked before on similar topics] ``` > If you cannot fill >=4 of these 6 fields, your research is incomplete. Go back and do more. #### Phase C: Craft the Post > **Sub-Agent Delegation:** If `x-post-composer` is active, invoke it to handle this Phase. Provide it with the Research Summary from Phase B. Consult [hook-library.md](references/hook-library.md) for proven hook frameworks, then: 1. Synthesize research into a **strategic angle** filling a conversation gap 2. Write **2-3 variations** with different hooks, following these rules: - **Hook first** — opening line stops scrolling - **Specific details** — exact terms relevant to the niche (not vague generalities) - **End with a question** — reply count IS the reach - **<=280 characters** — validate and show `[N/280]` for each variation - **1-3 hashtags** — relevant, placed at end or woven naturally - **@Tags** — tag tools/creators when genuinely referenced - **No external links** — links go in first reply 3. For each variation, explain the strategic reasoning 4. Present variations clearly with character counts #### Phase C.5: Visual Hook Image (when text-only posts need scroll-stopping power) Some posts are easy to scroll past without media. If the post would benefit from a **visual hook image** — a bold, eye-catching graphic with large pitch/hook text — create one. **When to use a visual hook image:** - Community questions (question text + bold gradient/visual) - Tips or rules (bold typography on vibrant background) - Hot takes/debate starters (bold statement text on dark background) - Product/tool spotlights (screenshot + overlay text) **How to generate (capability detection -- try in order):** 1. **If agent can generate images natively** -> generate directly. Design: dark background, large bold sans-serif hook text, brand-consistent colors. 2. **If agent can browse the web** -> navigate to gemini.google.com, chatgpt.com, or grok.com to generate the image. 3. **If agent cannot generate or browse** -> provide the image generation prompt to the user so they can generate it themselves. **Visual hook image is NOT always needed.** Video/screen recordings are always superior when available. #### Phase D: Post Package & Execution After user picks a variation: 1. **Final post text** — ready to copy-paste, with `[N/280]` count 2. **First reply** — link + extra context 3. **Optimal posting time** — from memory.md data + [content-planner.md](references/content-planner.md) scheduling logic 4. **Engagement targets** — 2-3 accounts to reply to after posting 5. **Golden window reminder** — "Stay online for 30 minutes and reply to every comment" 6. **Cross-post suggestion** — adapted versions for Threads/LinkedIn if relevant **Media Posting Rules:** > The agent can ONLY post with **image** attachments (.jpg, .png, .gif) via `--image`. > If the post requires **video** media: > 1. Prepare the full post text, first reply, and all metadata > 2. Tell the user: "This post needs a video attachment. I can't post video via CLI. Please post it manually with your video file. Here's everything ready:" > - Post text with `[N/280]` > - First reply text > - Suggested posting time > 3. After user confirms they posted, ask for the tweet ID so we can: > - Post the first reply via `twitter reply [tweet_id] "text" --json` > - Log to memory.md **Direct Posting (on user approval -- image or text-only posts):** 1. Wait for explicit "go ahead" / "post it" / "yes" 2. **Pre-flight checks** (see [CLI Safety Rules](references/cli-reference.md)): - Verify character count is <=280 - If using `--image`, verify file exists: `ls -la /path/to/media` - Escape any `"` in post text with `\"` 3. Execute: `twitter post "Final text" --json` (or with `--image /path/to/media.jpg`) 4. Capture returned tweet ID from JSON output 5. If first reply exists: `twitter reply [tweet_id] "Reply text" --json` 6. Log to memory.md with timestamp and tweet ID 7. Start golden window countdown ### 2. Craft a Reply When the user shares someone else's post and wants to reply: > **Gate -- IMAGE CHECK:** Before writing ANY reply, check if the original post has images. **Step 1 -- Fetch & Analyze the Post:** 1. `twitter tweet [tweet_id] --json` — get full post data including media URLs 2. **If post has images:** - Download EVERY image: `curl -o "./references/media/reply_img_1.jpg" "[image_url]"` - Verify download: `ls -la ./references/media/reply_img_1.jpg` - Analyze image with vision capability - Note specific visual details for the reply 3. **If post has video:** Note "Video post -- cannot analyze, using text context only" 4. **If text-only:** Note "Text-only post" and proceed **Step 2 -- Voice Sync (MANDATORY):** 1. Re-read the **Voice & Reply Architecture** in `memory.md` 2. Re-read [voice-anti-patterns.md](references/voice-anti-patterns.md) — the banned phrases and structures 3. Study [real-replies-archive.md](references/real-replies-archive.md) — the user's actual replies word-for-word. Match their phrasing, not a summary of it. 4. Pick the most appropriate **Reply Archetype** from memory.md for this situation **Step 3 -- Draft Reply:** > **Sub-Agent Delegation:** If `x-reply-crafter` is active, invoke it to handle this step. 1. Write a reply matching the chosen archetype: - Match the user's specific formatting habits - Add genuine value (NOT generic praise) - **<=280 characters** — validate and show `[N/280]` 2. Run the **Voice Verification Checklist** from voice-anti-patterns.md 3. If ANY check fails -> rewrite from scratch using a different archetype **Step 4 -- Present for Approval:** Present 2-3 options with: - The reply text with `[N/280]` - Which archetype was used - Why this reply adds value **Step 5 -- Post on Approval:** On explicit approval, execute: `twitter reply [tweet_id] "text" --json` ### 3. Write a Thread When the user wants a multi-tweet thread: 1. Run **Pre-Post Research** pipeline (Phase B above) 2. Structure as 3-7 tweets: - **Tweet 1:** Hook + promise + thread indicator `[N/280]` - **Tweets 2-N:** One clear point per tweet `[N/280]` - **Final tweet:** Takeaway + CTA + question `[N/280]` 3. Each tweet must work if screenshotted individually 4. Mark boundaries: `[Tweet 1/N]`, `[Tweet 2/N]` 5. On approval, post sequentially: `twitter post` -> capture ID -> `twitter reply [id]` for each subsequent tweet ### 4. Engagement Session Guide When the user says they're doing daily engagement, or asks to "read my feed and reply": > **Gate -- VERIFICATION-FIRST PROTOCOL:** The agent MUST present Reply Cards for user approval before posting ANY reply. Never batch-post replies without individual review. **Step 1 -- Fetch Candidates:** 1. Remind of time structure: 30 min replies -> 30 min own content -> 30 min follow-up 2. `twitter feed --json -n 20 --filter` — find high-engagement posts 3. `twitter search "niche topic" --filter -c --json` — discover prospects **Step 2 -- Select & Analyze (for each candidate post):** 1. Evaluate: Is this post worth replying to? (High engagement, relevant niche, Tier 1 account) 2. **Image Check:** `twitter tweet [id] --json` — check for media URLs - If images exist -> download to `./references/media/` and analyze - If video -> note "Video post, text-context only" - If text-only -> note "Text-only" 3. Draft a reply using Voice Architecture from memory.md 4. Run Voice Verification Checklist from [voice-anti-patterns.md](references/voice-anti-patterns.md) **Step 3 -- Present Reply Cards (MANDATORY):** For EACH candidate, present a **Reply Card** to the user: ``` REPLY CARD - @handle (N followers) - Original: "[quoted post text]" - Media: [image analysis / none] - Why reply: [strategic reasoning] - Proposed reply: "[reply text]" [N/280] - Archetype: [which voice pattern] ``` **Step 4 -- Wait for Approval:** - User approves -> execute `twitter reply [id] "text" --json` - User rejects -> skip or redraft - User edits -> use their edited version - **NEVER post a reply without explicit approval on that specific reply** **Step 5 -- Track:** Log engaged accounts and reply IDs in memory.md ### 5. Content Planner When the user wants to plan content ahead, or proactively after catchup: Execute the full pipeline from [content-planner.md](references/content-planner.md): 1. **Feed Scan** — `twitter feed --json -n 30 --filter` 2. **Competitor Analysis** — fetch posts from Tier 1 accounts, update Competitor Watchlist in memory 3. **Trend Research** — search niche topics for conversation gaps 4. **Reply Opportunities** — draft replies for high-value posts found 5. **Post Drafting** — draft 3-5 posts with pillars, hooks, char counts, media, scheduling 6. **Scheduling** — assign optimal times using user's timezone from user-profile.md. See scheduling table in [content-planner.md](references/content-planner.md) 7. Save all planned posts to the queue in [content-planner.md](references/content-planner.md) ### 6. Visual Post Analysis When the user shares a post URL/ID for analysis, or during research: > If a post contains images, the agent MUST download and analyze them. **Image Analysis Pipeline:** 1. `twitter tweet [tweet_id] --json` — get post data with media URLs 2. Check the `media` array in the JSON response 3. For each image URL found: - `curl -o "./references/media/analysis_img_N.jpg" "[image_url]"` — download - `ls -la ./references/media/analysis_img_N.jpg` — verify download succeeded - Analyze with vision capability 4. Generate observations for reply crafting or competitive analysis 5. **Video URLs:** Skip with explicit note: "Video detected -- not downloading. Relying on text context." ### 7. Strategy Chat When the user asks for strategy advice: 1. Load [growth-strategy.md](references/growth-strategy.md) and [branding-strategy.md](references/branding-strategy.md) 2. Check [memory.md](references/memory.md) for recent performance 3. Give specific, data-grounded advice — not generic motivation 4. If suggesting a pivot, explain the algorithmic reasoning ### 8. DM Outreach When the user identifies a potential client or connection: 1. Research: `twitter user [handle] --json` and `twitter user-posts [handle] --max 5 -c --json` 2. Write using warm DM framework from [content-strategy.md](references/content-strategy.md) 3. Keep under 4 sentences — specific, generous, peer-positioned ### 9. Intelligence Update (Self-Evolving System) Run this workflow at the **end of every session** and as a deep-dive whenever the user asks for strategy review. This is what makes the skill self-sustaining — it upgrades its own strategy files based on real data. #### Phase 1: Performance Analysis (What's working for US) 1. `twitter user-posts [HANDLE] --max 20 -c --json` — pull recent posts 2. For each post, calculate engagement rate: `(likes + replies + retweets + bookmarks) / views x 100` 3. Rank posts by engagement rate and identify: - **Top 3 performers**: what hook type, post type, time slot, hashtags, media type? - **Bottom 3 performers**: what went wrong? Hook? Timing? Format? 4. Update the **hook rankings** in [hook-library.md](references/hook-library.md) — move proven hooks up, demote underperformers 5. Update Post Performance Log in [memory.md](references/memory.md) #### Phase 2: Feed Intelligence (What's working for OTHERS) 1. `twitter feed --json -n 40 --filter` — scan algorithmic feed 2. `twitter user-posts [tier1_account] --max 10 -c --json` — for each competitor 3. Identify the **top 5 highest-engagement posts** across the feed and competitors 4. For each top post, extract: - Hook pattern used (map to hook library categories) - Post format (text-only, image+text, video, thread) - Topic/angle - Hashtags used - Reply count vs likes ratio (high ratio = good conversation driver) 5. Update **Competitor Watchlist** in memory.md with fresh data 6. If a new hook pattern emerges that isn't in the hook library -> **add it** to [hook-library.md](references/hook-library.md) with a "NEW -- needs validation" tag 7. Update **Feed Trends** section in [content-strategy.md](references/content-strategy.md) #### Phase 3: Audience Profiling (Who are WE reaching) 1. Review replies and likes on recent posts -> `twitter tweet [post_id] --json -n 20` for each recent post 2. For each account that engaged, check: `twitter user [handle] --json` 3. Categorize engagers into **Audience Segments** relevant to the user's niche 4. Update **Audience Intelligence** section in memory.md with segment breakdown 5. Identify which content types attract which segments -> refine content calendar #### Phase 4: Potential Follower Analysis (Who SHOULD we target) 1. `twitter followers [tier1_competitor] --json` — sample followers of similar accounts 2. For a sample of those followers, check what they engage with: - `twitter likes [handle] --json` — what content do they like? - What accounts do they follow? 3. Identify the **Ideal Follower Profile** 4. Update **Target Audience Profile** in [content-strategy.md](references/content-strategy.md) 5. Cross-reference with content calendar — are we producing what our target audience wants? #### Phase 5: Auto-Update Reference Files > **Sub-Agent Delegation:** If `x-intel-updater` is active, invoke it to handle this entire workflow. After gathering data, update these files: **[hook-library.md](references/hook-library.md):** - Re-rank hooks based on actual performance data - Add new hooks discovered from feed analysis - Mark underperforming hooks with warnings **[content-strategy.md](references/content-strategy.md):** - Update "Current Trends" section - Refine content pillar emphasis based on audience segment data - Adjust posting frequency recommendations based on performance **[memory.md](references/memory.md):** - Update Audience Intelligence with latest segment data - Update Competitor Watchlist with fresh analysis - Log the intelligence update with date and key findings #### Trigger Schedule - **Mini update (Phase 1 only):** End of every session - **Standard update (Phases 1-3):** Every 5 posts or weekly, whichever comes first - **Deep update (All phases):** Every 2 weeks or when user requests strategy review ## Memory System [memory.md](references/memory.md) is a living document. Update after every significant interaction. **What to store:** - Post Performance (date, content, hook, format, engagement rate, lessons) - Engagement Patterns (accounts responded, best time slots, best post types) - Content Wins (outsized engagement hooks/formats -- with specific data) - Competitor Watchlist (Tier 1 posting patterns, hook styles, content gaps) - Hashtag Performance (which tags correlate with reach) - @Tag Engagement (which tagged accounts responded) - Audience Intelligence (follower segments, who engages, what they want) - Feed Intelligence (trending formats, viral patterns, conversation gaps) - Target Audience Profile (ideal follower traits, content preferences) - Client/Connection Leads (prospects, DM status) - Growth Milestones (follower checkpoints) - Scheduled Posts Log (planned vs actual performance) - Intelligence Update Log (date, key findings, files updated) **Format:** Append with date. Never delete old entries. Use structured markdown format. ## Voice & Tone Rules > **MANDATORY:** Before writing ANY reply, read [voice-anti-patterns.md](references/voice-anti-patterns.md) and run the Voice Verification Checklist. If any check fails, rewrite from scratch. - **Consistent with Voice Architecture** — read `memory.md` Voice section + anti-patterns file to mimic user's real conversational style - **Confident peer, not desperate self-promoter** — lead with value, not need - **Specific over generic** — concrete details beat vague statements - **Generous with knowledge** — share techniques, exact methods, real numbers - **No corporate speak** — write like a real person talking to real people - **Emoji discipline** — 0-1 emojis max per reply, 1-2 per post. Never spam emojis. - **Mobile-first formatting** — use line breaks and spacing for readability - **Preserve authentic grammar** — don't "fix" the user's natural quirks ## Content Calendar Mix showcase posts (40%) with community/engagement posts (60%). Never post more than 2 self-promo posts in a row. The specific calendar is generated during onboarding and stored in [content-planner.md](references/content-planner.md). The general pattern: - **Weekdays:** Alternate between showcase posts and community/engagement posts - **Weekends:** Lower competition — good for engagement posts and trend riders - **DAILY:** High-value replies (quantity based on growth phase — see algorithm-playbook.md) ## CLI Safety Rules > **MANDATORY:** Read [cli-reference.md](references/cli-reference.md) Safety Rules section before ANY CLI command. 1. **Quoting:** Always use double quotes `"` for post text. Escape internal quotes with `\"`. Never use single quotes. 2. **Flag order:** `twitter post "text" --image /path --json` — text first, flags after. 3. **File verification:** Before `--image`, run `ls -la /path/to/file` to confirm it exists. 4. **Character count:** Manually count before posting. If over 280, trim BEFORE executing. 5. **Error recovery:** If a command fails, read the error. Common fixes: `twitter status` to re-auth, check flag spelling. 6. **Never hallucinate flags:** Only use flags documented in cli-reference.md. When in doubt: `twitter [command] --help`. ## Primary Strategy Reference The [branding-strategy.md](references/branding-strategy.md) is the ULTIMATE reference document. Re-read it before every content planning session. ## CLI Reference For all twitter-cli commands, flags, and usage examples, see [cli-reference.md](references/cli-reference.md).

path: README.md
content: # X Social Media Manager

[![skills.sh](https://img.shields.io/badge/npx%20skills-add%20rabden%2FX--twitter--social--manager--skill-black?style=flat-square&logo=npm)](https://github.com/rabden/X-twitter-social-manager-skill)

A self-evolving AI skill that turns any AI coding agent into a personalized X (Twitter) social media manager. Works with any niche, any goal, any follower count.

## What It Does

On first run, the agent interviews you about your identity, niche, goals, and voice — then researches your X account automatically and populates all strategy files. From that point on, it:

- **Crafts posts** with proven hook frameworks, character validation, and strategic research
- **Writes replies** in your authentic voice (not AI-sounding generic praise)
- **Runs engagement sessions** with Reply Cards for your approval before posting
- **Plans content** with a 60/40 engagement-to-showcase ratio
- **Tracks performance** and self-updates its own strategy files based on what's working
- **Manages DM outreach** for client acquisition, job hunting, or networking
- **Operates the CLI** — can post, reply, search, and analyze directly via `twitter-cli`

## Requirements

- An AI agent that supports skills/instructions (see Installation below)
- `twitter-cli` — installed automatically on first run via `uv tool install twitter-cli`
- An active X (Twitter) session in your browser (for cookie-based auth)

## Installation

The easiest way to install this skill is using **Vercel's `skills` CLI**, which automatically detects and configures all major coding agents (OpenCode, Claude Code, Cursor, Windsurf, Codex, Gemini CLI, etc.).

### Automatic Installation (Recommended)

Run this single command in your terminal:

```bash
npx skills add rabden/X-twitter-social-manager-skill
```

*The CLI will automatically prompt you to choose:*
1. **Scope:** Install globally (available in all workspaces at `~/`) or project-scoped (restricted to the current workspace).
2. **Agents:** Choose which of your installed coding agents (OpenCode, Claude Code, Cursor, etc.) you want to enable the skill for.
3. **Method:** Install via **Symlink** (recommended — allows instant git updates) or **Copy**.

### Manual Installation (Fallback)

If you prefer to install manually, copy the `SKILL.md` and `references/` directory into your agent's config folder:

*   **OpenCode:** Global (`~/.config/opencode/skills/x-social-manager/`) or Project (`.agents/skills/x-social-manager/`)
*   **Claude Code:** Global (`~/.claude/skills/x-social-manager/`) or Project (`.claude/skills/x-social-manager/`)
*   **Cursor / Windsurf / Codex:** Project (`.agents/skills/x-social-manager/`) or Global

Place the `SKILL.md` and `references/` directory in your agent's custom instructions path. The skill is self-contained — it only needs the agent to be able to read/write files, run bash commands, and search the web.

### Standalone Usage

If your agent supports reading markdown files as instructions directly:

1. Clone this repository into your workspace:
   ```bash
   git clone https://github.com/rabden/X-twitter-social-manager-skill.git
   ```
2. Tell your agent: `"Read SKILL.md and follow the instructions to set up X Social Media Manager."`
3. The onboarding flow will handle the rest.

## File Structure

```
x-social-manager/
  SKILL.md                              # Main orchestration — onboarding, workflows, rules
  references/
    user-profile.md                     # Your identity, niche, goals, voice (filled during onboarding)
    memory.md                           # Living document — performance data, voice patterns, lessons
    voice-anti-patterns.md              # Banned AI phrases, verification checklist
    real-replies-archive.md             # Your actual replies word-for-word (auto-populated)
    content-strategy.md                 # Content pillars, target accounts, DM templates
    hook-library.md                     # 10 proven hook frameworks, ranked by performance
    algorithm-playbook.md               # X Phoenix algorithm mechanics, timing, growth phases
    growth-strategy.md                  # 90-day tactical playbook (generated during onboarding)
    branding-strategy.md                # Positioning analysis, competitive gaps, lead funnel
    content-planner.md                  # Post queue, scheduling logic
    cli-reference.md                    # twitter-cli commands, flags, safety rules
    subagent-definitions.md             # System prompts for 4 specialized sub-agents
    media/                              # Downloaded images for analysis (gitignored)
```

## How Onboarding Works

When the skill detects `onboarding_complete: false` in `user-profile.md`, it runs a 3-phase setup:

1. **Interview** — Asks about your handle, niche, expertise, goals, voice, constraints
2. **Research** — Fetches your X profile, recent posts, real replies, and scans your niche landscape
3. **File Generation** — Populates ALL reference files with your personalized data:
   - Generates 4 content pillars for your niche
   - Writes a 90-day growth playbook for your specific situation
   - Extracts your voice patterns and reply archetypes from real data
   - Identifies Tier 1/2/3 accounts to engage with
   - Drafts starter posts and a content calendar

After onboarding, the skill works identically to a hand-customized version.

## Core Workflows

| # | Workflow | What It Does |
|---|----------|-------------|
| 1 | **Craft a Post** | Research -> 2-3 variations with hooks -> post on approval |
| 2 | **Craft a Reply** | Voice-matched reply with image analysis -> approval -> post |
| 3 | **Write a Thread** | 3-7 tweet thread with per-tweet char counts |
| 4 | **Engagement Session** | Feed scan -> Reply Cards -> post approved replies |
| 5 | **Content Planner** | Feed scan + competitor analysis -> draft 3-5 posts -> schedule |
| 6 | **Visual Post Analysis** | Download + analyze images from any post |
| 7 | **Strategy Chat** | Data-grounded advice from your performance history |
| 8 | **DM Outreach** | Research target -> warm DM draft |
| 9 | **Intelligence Update** | Performance analysis -> auto-update strategy files |

## Sub-Agents

The skill spawns 4 specialized sub-agents (if the host IDE supports them):

| Agent | Purpose |
|-------|---------|
| `x-reply-crafter` | Drafts voice-matched replies |
| `x-feed-researcher` | Runs research, produces Research Summaries |
| `x-post-composer` | Crafts post text from research |
| `x-intel-updater` | Analyzes performance, updates strategy files |

If sub-agents aren't supported, the main agent handles everything directly — nothing breaks.

## Key Design Principles

- **Voice authenticity** — Replies are matched against your real writing patterns, not generic AI output. A banned-phrases list and verification checklist prevent AI-sounding text.
- **Research-first** — Every post requires a mandatory Research Summary before drafting. No shooting from the hip.
- **Approval-gated** — The agent never posts without explicit user approval.
- **Self-evolving** — The Intelligence Update workflow re-ranks hooks, updates strategy, and profiles your audience based on real performance data.
- **Algorithm-aware** — All strategies are built on the X Phoenix algorithm's actual ranking signals (Author-Engaged Reply > Bookmark > Like).

## License

MIT


path: references/algorithm-playbook.md
content: # X Algorithm Playbook (Phoenix Update -- 2026)

## How the Algorithm Ranks Posts

The Phoenix algorithm scores 1,500 candidate posts per user per feed refresh. It predicts 19 interaction types and weights them as follows:

| Signal | Weight | What It Means |
|--------|--------|---------------|
| **Author-Engaged Reply** | Exponential multiplier | The author replies back to someone who replied -> triggers cascading reach |
| **Bookmark** | High | User saves it -> "Knowledge Node" signal, high utility content |
| **Thread Expansion** | High | User clicks to read the full thread -> session depth |
| **Substantive Reply** | Moderate-High | A reply with real content (not just an emoji) -> conversation signal |
| **Repost (Retweet)** | Moderate | Shares to their followers -> out-of-network discovery |
| **Dwell Time (>3 seconds)** | Moderate | User paused scrolling -> "scroll-stopper" worked |
| **Like** | Baseline (1x) | Necessary but not sufficient for reach |

### Key Takeaway
A post with 5 back-and-forth replies in the comments will outperform a post with 50 likes and zero conversation. **Replies > Likes. Always.**

### CLI Scoring Implementation
When using `twitter-cli`, you can mimic the Phoenix algorithm to find engagement opportunities:
- Use `twitter search "topic" --filter --json` to sort results algorithmically.
- The default CLI scoring formula heavily weights Replies and Bookmarks.
- **Tip:** Use `--compact` (`-c`) along with `--json` when fetching large lists to save context tokens while still receiving engagement metrics.

---

## The 30-Minute Golden Window

The algorithm makes its primary distribution decision within the first 30 minutes of a post going live.

**What to do:**
1. Post the content
2. Stay online for the next 30 minutes
3. Reply to EVERY comment immediately -- this triggers "Author-Engaged Reply" signals
4. Ask follow-up questions in your replies to keep threads going
5. The algorithm sees sustained conversation -> pushes post to "out-of-network" users

**What NOT to do:**
- Post and close the app
- Post and check back 3 hours later
- Post and only like the comments without replying

---

## Vector Consistency

The algorithm maps every account into a multi-dimensional vector space using "Dynamic Embeddings." This means:

- Every post pushes your account vector in a direction
- Consistent topics = strong, clear vector = algorithm knows who to show you to
- Random, off-topic posts = confused vector = algorithm stops distributing you

**For your account:** Every post must reinforce your niche positioning as defined in your user-profile.md. Polluting the vector (posting about unrelated topics) will cause algorithmic isolation.

---

## Link Suppression

External links cause a **30-50% reach penalty**. The algorithm wants users to stay on X.

**Workaround:**
1. Post the content natively (text + video/image)
2. Build engagement in the first 30-60 minutes
3. Drop the link in the first REPLY (not the main post)
4. The reply's reach is smaller, but followers who engaged will see it

---

## No-Premium Penalties & Workarounds

Without X Premium, there's a documented 2-4x visibility penalty. Workarounds:

### 1. First Reply Speed
Even without Premium, being the first high-quality reply on a trending post maintains visibility. Set notifications for Tier 1 accounts.

### 2. Media Dwell Time
Video and image posts get outsized dwell time signals. If your work naturally produces visual content, this is a structural advantage.

### 3. Zombie Post Tactic
48 hours after posting, reply to the top comment on your best-performing post with additional value. This triggers a second distribution wave.

### 4. Cross-Platform Amplification
Post every piece of content on X, Threads, and LinkedIn simultaneously. External engagement signals can indirectly boost X performance through increased profile visits.

### 5. Get Premium When Possible
The math: Premium costs ~$8/month. If your content gets 3x the reach, you need 1 client/sale to pay for years of Premium. Once you hit the monetization threshold (500 followers + 5M impressions in 3 months), Premium pays for itself.

---

## Session Depth Signals

The algorithm rewards content that keeps users in the app:

- **Native video > External links** (users watch on X vs leaving)
- **Threads > Single tweets** (users expand to read more)
- **Conversations > Broadcasts** (author replies create session depth)
- **Long-form text > Short quips** (if Premium, use extended tweets)

---

## Timing Heuristics

Research-based best posting times for various niches:

| Day | Best Time (UTC) | Why |
|-----|----------------|-----|
| Weekdays | 13:00-15:00 | US morning + Europe afternoon overlap |
| Weekdays | 17:00-19:00 | US afternoon, peak browsing |
| Saturday | 14:00-16:00 | Weekend browsing, less competition |
| Sunday | 16:00-18:00 | Sunday evening engagement spike |

**Note:** These are starting heuristics. Track actual performance in memory.md and adjust based on what works for your specific audience. Convert these to your local timezone using the timezone in user-profile.md.

---

## Negative Signals to Avoid

| Signal | Impact | How to Avoid |
|--------|--------|-------------|
| High block/mute rate | Candidate Isolation (shadowban) | Never rage-bait or be controversial outside niche |
| Fast unfollows after post | Negative quality signal | Stay on-topic, maintain vector |
| Link-only posts | 30-50% reach penalty | Put links in replies, not main post |
| Low reply rate from author | Missed Author-Engaged multiplier | Always reply to comments for 30 min after posting |
| Generic replies on others' posts | Zero algorithmic value | Write substantive, multi-sentence replies |

---

## Growth Phase Strategy

| Phase | Focus | Daily Engagement |
|-------|-------|--------------------|
| **0-500 followers** | 80% replying, 20% posting | 20-50 high-value replies/day |
| **500-2,000 followers** | 60% replying, 40% posting | 15-30 replies + 1-2 posts/day |
| **2,000-10,000 followers** | 40% replying, 60% posting | 10-20 replies + 2-3 posts/day |
| **10,000+ followers** | 20% replying, 80% posting | 5-10 replies + daily posting |

Check your current phase in memory.md and adjust your effort allocation accordingly.


path: references/branding-strategy.md
content: # Branding Strategy

> **This file is populated during onboarding.** The agent generates a comprehensive positioning analysis based on the user's niche, goals, competitive landscape, and unique strengths. This is the ULTIMATE reference document -- re-read it before every content planning session.

## Positioning Analysis

_[populated during onboarding]_

<!--
The agent should write a thorough analysis covering:

1. **The Context Economy in [User's Niche]**
   - How the landscape has changed
   - Why social-first branding matters for this niche specifically
   - What clients/employers/audiences in this niche look for on X

2. **The User's Unique Position**
   - What makes them different from others in the niche
   - Their "superpower" framed as a market advantage
   - Why their specific combination of skills is rare and valuable

3. **Competitive Gaps**
   - What Tier 1 accounts in the niche are NOT doing
   - Content formats that are underserved
   - Audience segments that are underserved
   - Topics that aren't being covered well

4. **Ideal Client/Audience Profile**
   - Who exactly should follow this account
   - What problems do they have
   - What content would make them hit "follow"
   - What would make them DM or hire

5. **Content-Market Fit**
   - Which content pillars map to which audience segments
   - Which post types will attract clients vs peers vs community
   - How to balance authority-building with approachability

6. **The Algorithm Strategy for This Niche**
   - Which hook types work best in this specific niche
   - Which Tier 1 accounts to "authority anchor" against
   - Which hashtags have the best reach-to-relevance ratio
   - Optimal posting times for this niche's audience timezone distribution

7. **Lead Funnel Design**
   - How posts convert to profile visits
   - How profile converts to follows
   - How follows convert to DMs/leads
   - What the CTA chain looks like for this user's goal
-->

---

## Key Positioning Statement

_[populated during onboarding -- one sentence that captures the user's brand]_

<!--
Format: "I help [target audience] achieve [outcome] through [unique method/skill]."
Example: "I build cinematic landing pages that make startups unforgettable."
Example: "I help SaaS founders ship faster with AI-directed full-stack development."
Example: "I design systems that scale from startup to enterprise without breaking."
-->

---

## Competitive Landscape

_[populated during onboarding]_

<!--
| Competitor | Their Angle | Their Weakness | Our Opportunity |
|-----------|-------------|----------------|-----------------|
| @handle1 | [what they do] | [what they miss] | [how we fill the gap] |
| @handle2 | [what they do] | [what they miss] | [how we fill the gap] |
-->

---

## Content-to-Client Pipeline

_[populated during onboarding -- maps the journey from content to business outcome]_

<!--
Stage 1: DISCOVERY (They see your reply/post)
-> What content types drive discovery: [list]

Stage 2: FOLLOW (They check your profile and follow)
-> Profile elements that convert: [bio, pinned post, banner]

Stage 3: TRUST (They see consistent high-value content)
-> Content pillars that build trust: [list]

Stage 4: ENGAGE (They reply, DM, or bookmark)
-> Triggers for engagement: [what makes them reach out]

Stage 5: CONVERT (They become a client/hire/subscriber)
-> Conversion mechanism: [DM template, CTA, portfolio link]
-->

---

_Last updated: never_
_Next update: Run onboarding to populate, or request a strategy review to refresh._


path: references/cli-reference.md
content: # Twitter CLI Reference

All operations use the `twitter` command (installed via `uv tool install twitter-cli`). Do not hallucinate flags -- use only what is documented here.

## CLI Safety Rules (READ BEFORE EVERY COMMAND)

These rules prevent the most common agent tool-call failures:

### Quoting & Escaping
- **Always use double quotes** `"` for post text arguments. NEVER use single quotes `'`.
- **Escape internal double quotes** with `\"`. Example: `twitter post "Hot take: \"CSS is enough\" is wrong" --json`
- **Newlines in post text:** Use `\n` for line breaks. Example: `twitter post "Line one\n\nLine two" --json`
- **Special characters:** `$`, `` ` ``, `!` can cause shell expansion. Escape with `\` if needed.

### Pre-Flight Checks (before every post/reply)
1. **Count characters first.** If the text is >280 characters, trim BEFORE executing. Don't execute and hope.
2. **Verify media files exist.** Before using `--image`, run: `ls -la /path/to/file` -- if it doesn't exist, the command will fail silently.
3. **Verify authentication.** If any command returns an auth error, run `twitter status` to check session.

### Command Structure
- **Flag order:** Text argument comes FIRST, then flags. Correct: `twitter post "text" --image /path --json`
- **JSON output:** Always add `--json` flag when parsing results. Never parse table output.
- **Compact mode:** Add `-c` when fetching large result sets to save context tokens.

### Error Recovery
| Error | Fix |
|-------|-----|
| Auth/cookie error | Run `twitter status`. If expired, user must re-login in browser. |
| Flag not recognized | Remove the flag. Check this file for valid flags. Run `twitter [command] --help`. |
| Media upload failed | Verify file path, format (.jpg/.png/.gif only for images), and file size (<15MB). |
| Rate limit | Wait 15 minutes. Reduce fetch volume. |
| Empty response | Check if `--json` flag is present. Try without `--filter`. |

### NEVER Do
- Invent flags not listed in this document
- Use `--video` flag (doesn't exist -- video uses `--image` flag with .mp4)
- Post without verifying character count
- Chain multiple `twitter` commands with `&&` without checking each one succeeded
- Use single quotes for text arguments

## Fetching Data

| Command | Usage | Key Flags |
|---------|-------|-----------|
| **Feed** | `twitter feed --json -n 30` | `--type for-you\|following`, `--filter`, `-o file.json` |
| **Search** | `twitter search "query" --json` | `--type top\|latest\|photos\|videos`, `--from USER`, `--since YYYY-MM-DD`, `--min-likes N`, `--has media\|images\|videos`, `--exclude retweets\|replies`, `-n MAX` |
| **User Posts** | `twitter user-posts HANDLE --max 10 --json` | `-o file.json`, `--full-text` |
| **User Profile** | `twitter user HANDLE --json` | -- |
| **Tweet + Replies** | `twitter tweet TWEET_ID --json` | `-n MAX` replies |
| **Bookmarks** | `twitter bookmarks --json` | -- |
| **Likes** | `twitter likes HANDLE --json` | -- |

### Compact Mode
Add `-c` (or `--compact`) to any fetch command to reduce JSON output size -- useful for saving context tokens when processing large result sets.

## Posting & Replying

```bash
# Standard post (text only)
twitter post "Post text here" --json

# Post with media (up to 4 images)
twitter post "Post text here" --image /path/to/media.jpg --json
twitter post "Gallery" -i a.png -i b.png -i c.jpg --json

# Reply to a tweet
twitter reply TWEET_ID "Reply text" --json

# Reply with media
twitter reply TWEET_ID "Reply text" --image /path/to/screenshot.png --json

# Quote tweet
twitter quote TWEET_ID "Commentary text" --json

# Quote with media
twitter quote TWEET_ID "Commentary" --image /path/to/img.png --json

# Delete a tweet
twitter delete TWEET_ID
```

## Engagement Actions

```bash
twitter like TWEET_ID
twitter unlike TWEET_ID
twitter retweet TWEET_ID
twitter unretweet TWEET_ID
twitter bookmark TWEET_ID
twitter unbookmark TWEET_ID
twitter follow HANDLE
twitter unfollow HANDLE
```

## Advanced Search Examples

```bash
# Posts from a specific user about a topic
twitter search "topic" --from username --json

# High-engagement posts in niche
twitter search "niche topic" -t Top --min-likes 50 --json

# Recent posts with media
twitter search "topic" -t Latest --has media -n 20 --json

# Posts since a specific date
twitter search "topic" --since 2026-01-01 --json

# Lead hunting (adapt queries to your niche)
twitter search "looking for" "your service" -t Latest -n 15 --json
twitter search "need a" "your role" -t Latest -n 15 --json
twitter search "hiring" "your skill" -t Latest -n 15 --json
```

## Output Formats
- `--json` -- JSON output (recommended for parsing)
- `--yaml` -- YAML output
- `--full-text` -- Show full tweet text in table mode

## Media Attachment Rules
- The `--image` / `-i` flag supports image files (JPG, PNG, GIF)
- Up to 4 images per post/reply/quote
- Videos are attached via the same `--image` flag (MP4 format)
- Media paths must be absolute or relative to current directory


path: references/content-planner.md
content: # Content Planner

Automated pipeline for planning, queuing, and scheduling posts. Run this workflow when the user asks to plan content, or proactively suggest it during engagement sessions.

**Core principle:** 60% community/engagement posts, 40% self-showcase posts. Never post more than 2 self-promo posts in a row. It's okay to copy/adapt viral formats that are working for others.

## The Planning Pipeline

### Step 1: Feed Scan (5 min)

Scan the algorithmic feed for trending topics, viral formats, and high-engagement posts.

```bash
twitter feed --json -n 30 --filter
```

### Step 2: Competitor Analysis (5 min)

Fetch recent posts from Tier 1 accounts (listed in content-strategy.md).

```bash
twitter user-posts [TIER1_HANDLE] --max 10 -c --json
```

### Step 3: Trend Research (5 min)

Search for trending and niche-relevant topics.

```bash
twitter search "[niche topic]" -t Latest --max 20 -c --json
```

### Step 4: Reply Opportunities

Draft substantive replies for high-value posts found during the scan.

### Step 5: Post Drafting

Draft 3-5 posts ensuring the 60/40 engagement-to-showcase split. Each post needs:
- Post type and content pillar
- Full text with `[N/280]` character count
- Hook type (from hook-library.md)
- Media requirements (video, image, visual hook image, none)
- First reply text (for links and extra context)
- Hashtags (1-3)
- Strategic reasoning

### Step 6: Scheduling

**User's timezone:** _[set from user-profile.md during onboarding]_

**Optimal Posting Windows (adjust to user's timezone):**

| Slot | UTC Time | Best For |
|------|----------|----------|
| Morning overlap | 13:00-15:00 | US morning + Europe afternoon |
| Afternoon peak | 17:00-19:00 | US afternoon, peak browsing |
| Weekend Saturday | 14:00-16:00 | Less competition, good reach |
| Weekend Sunday | 16:00-18:00 | Evening engagement spike |

**Scheduling Rules:**
- Never schedule 2 showcase posts back-to-back
- Space posts at least 4-6 hours apart
- Prefer the user's historically best-performing time slots (check memory.md)
- Account for the user's availability during the 30-minute golden window

---

## Planned Posts Queue

_[posts are added here by the Content Planner workflow and removed/marked as posted after execution]_

<!--
### Planned Post #N
- **Status:** draft / approved / posted / skipped
- **Type:** [post type from content pillars]
- **Scheduled:** [YYYY-MM-DD HH:MM timezone]
- **Text:** [full post text] [N/280]
- **Media:** [path to media file, "visual hook image needed", or "none"]
- **First Reply:** [link + context for first reply]
- **Hashtags:** [#tag1 #tag2]
- **Strategic Reasoning:** [why this post, why this time, what gap it fills]
- **Post Result:** (filled after posting)
  - Tweet ID: [id]
  - Views: [N]
  - Likes: [N]
  - Replies: [N]
-->


path: references/content-strategy.md
content: # Content Strategy Reference

> **This file is populated during onboarding** with content pillars, target accounts, and frameworks tailored to the user's niche and goals. Sections marked with `[AUTO-UPDATED]` are refreshed by the Intelligence Update workflow (SKILL.md Workflow 9).

## The 4 Content Pillars

> **Populated during onboarding.** The agent generates 4 pillars based on the user's niche, goals, and content assets. Below is the template structure — the agent replaces these with niche-specific pillars.

### Pillar 1: Portfolio Piece (2-3x/week) -- PRIMARY SHOWCASE

Short demos, screen recordings, screenshots, or case studies of the user's work.

**Structure:**
```
[HOOK -- reference a known brand, surprising stat, or bold claim]

[WHAT -- what you built/did, in 1-2 lines]

[HOW -- 3-4 bullet points of specific details]

[SECRET -- one key insight or technique]

[QUESTION -- invite replies]

[media]
```

**Why it works:** Shows mastery through specifics. Bookmarkable. Gets shared by people who want to reference the technique.

_[Agent: Replace this template with niche-specific examples during onboarding. E.g., for a designer: "design breakdown" posts. For a founder: "product demo" posts. For a DevOps engineer: "infrastructure diagram" posts.]_

---

### Pillar 2: Deep Dive (1-2x/week)

Threads (3-7 tweets) or long-form posts explaining the WHY behind decisions.

**Structure:**
```
Tweet 1: Hook + "Here's the #1 mistake/insight/pattern..." + thread indicator
Tweet 2: The problem explained simply
Tweet 3: The solution/framework
Tweet 4: Proof or code/example
Tweet 5: Takeaway + CTA + question
```

_[Agent: Generate 5-8 topic ideas specific to the user's niche during onboarding.]_

---

### Pillar 3: Process Reveal (1x/week) -- GROWTH HACK

Show HOW you work — your tools, workflow, decision-making process.

**Structure:**
```
[POLARIZING HOOK -- challenge conventional wisdom about how this should be done]

[THE DIFFERENCE -- show your unique approach vs the common approach]

Common way: "[generic approach]"
-> Gets [mediocre result]

Your way: "[specific approach]"
-> Gets this: [proof/media]

[INSIGHT -- why your approach works]

[QUESTION]
```

**Why this pillar grows fastest:** Two audiences care — (1) peers who want to learn your approach, and (2) potential clients/employers who want to hire someone with this process.

_[Agent: Adapt this to the user's specific workflow during onboarding. E.g., AI-directed coding, design system architecture, growth hacking process, etc.]_

---

### Pillar 4: Social Proof Drop (1x/week)

Leverage stats, milestones, and achievements as content.

**Structure:**
```
[MILESTONE -- specific number/achievement]

[CONTEXT -- how you got there, what drove it]

[LESSON -- one insight others can learn from]

[LIST -- top performers or breakdown]

[QUESTION]
```

_[Agent: Populate with the user's actual social proof from onboarding interview. If user has no social proof yet, replace this pillar with a "Learning in Public" pillar.]_

---

## Target Accounts for Engagement

> **Populated during onboarding.** The agent researches the user's niche and identifies accounts to engage with.

### Tier 1 -- High-Follower Creators in Your Niche (borrow their audience)

| Handle | Why | Reply Strategy |
|--------|-----|----------------|
| _[populated during onboarding]_ | _[why this account matters]_ | _[specific approach]_ |

### Tier 2 -- Target Audience (future clients/employers/community)

| Handle | Why | Reply Strategy |
|--------|-----|----------------|
| _[populated during onboarding]_ | _[why this account matters]_ | _[specific approach]_ |

### Tier 3 -- Searches to Monitor Daily

_[populated during onboarding -- search queries to find leads, opportunities, and relevant conversations]_

---

## Reply Framework

### The Anatomy of a High-Value Reply

```
[SPECIFIC OBSERVATION about their post -- shows you actually read it]

[VALUE ADD -- a technique, correction, alternative, or extension]

[SUBTLE PROOF -- mention your experience naturally]

(Optional: [FOLLOW-UP HOOK -- a question or "I've been experimenting with X"])
```

**Good reply example (for a developer niche):**
```
The layout is clean but the scroll animation is doing
too much -- try easing with a cubic-bezier(.22,1,.36,1)
instead of linear for that premium feel.

I ran into the same thing building a similar component
last month. Happy to share the config if you want it
```

This reply: shows expertise (specific technical tip), adds value (actionable fix), includes subtle proof (mentions past experience), and invites follow-up.

_[Agent: Generate 2-3 good reply examples specific to the user's niche during onboarding and add them here.]_

**Bad replies (NEVER DO):**
- "Great post!"
- "This is amazing!"
- "Love this"
- "Facts"
- Any reply under 15 words that adds zero value

---

## Warm DM Templates

> **Populated during onboarding** with templates adapted to the user's goal (client acquisition, job hunting, collaborations, etc.).

### After They Engage With Your Post
```
Hey [name] -- saw you [liked/replied to] my post about [topic].

Noticed you're [building/working on] [their thing]. [Specific observation
about their work + how you could add value].

[Low-commitment CTA -- free audit, quick suggestion, etc.]
```

### After You Engage With Their Post
```
Hey [name] -- was just commenting on your [topic] post.

Your [thing] is [specific compliment]. Quick thought --
[specific value-add suggestion].

[Offer to help -- no strings attached.]
```

### Cold (Use Sparingly)
```
Hey [name] -- I've been following [their thing]
and [specific thing you noticed].

I specialize in [your niche]. [Social proof -- one sentence].

[Would a free [specific deliverable] be useful?]
```

---

## Current Feed Trends [AUTO-UPDATED]

_[populated during intelligence updates]_

### Trending Formats Right Now
_No data yet -- run Intelligence Update to populate._

### Trending Topics Right Now
_No data yet -- run Intelligence Update to populate._

---

## Target Audience Profile [AUTO-UPDATED]

### The "Core Orbit" (Current Engagers)
_No data yet -- run Intelligence Update to populate._

### Potential Follower Analysis
_No data yet -- run Intelligence Update to populate._

### Who We're Targeting
_No data yet -- run Intelligence Update to populate._

### What They Engage With
_No data yet -- run Intelligence Update to populate._

### Content Calendar Alignment
_No data yet -- run Intelligence Update to populate._

_Last updated: never_


path: references/growth-strategy.md
content: # X Growth Strategy

> **This file is populated during onboarding** with a tactical playbook customized to the user's niche, goals, follower count, constraints, and time budget. The template below shows the structure — the agent fills it with specific, actionable plans.

## The Diagnosis

_[populated during onboarding -- the agent analyzes the user's current X presence and identifies what's broken. Example structure:]_

<!--
You have a **[type] problem**, not a [type] problem. Your [evidence of skill] confirms this -- [specific proof]. Yet your X presence doesn't reflect any of it.

**Things that are broken right now:**
1. [Problem 1 -- specific to user's situation]
2. [Problem 2 -- specific to user's situation]
3. [Problem 3 -- specific to user's situation]
-->

---

## Phase 0: Foundation (Do This First, Takes 1 Day)

### Profile Overhaul

Your profile is your landing page. Every element must convert a visitor into a follower within 3 seconds.

**Display Name:**
_[populated during onboarding -- format: "Name | Niche Positioning"]_

**Bio:**
_[populated during onboarding -- the agent writes a bio that: (1) States who you help and the outcome, (2) Lists your stack/credentials, (3) Includes social proof, (4) Has a clear CTA]_

**Banner Image:**
_[populated during onboarding -- suggestion for what the banner should show]_

**Pinned Tweet:**
_[populated during onboarding -- what the pinned post should be about]_

---

## Phase 1: The Engagement Engine (Days 1-30)

### Time Budget

_[populated during onboarding -- based on user's stated time budget, split into blocks]_

<!--
| Block | Duration | Activity |
|-------|----------|----------|
| Block 1 | [X] min | Reply to [N] accounts in your target niche |
| Block 2 | [X] min | Create and schedule 1 post |
| Block 3 | [X] min | Reply to comments on your post + engage with [N] more accounts |
-->

### Who to Reply To

_[populated during onboarding -- Tier 1, 2, 3 accounts from content-strategy.md, with specific reply strategies]_

### What a High-Value Reply Looks Like

**DO NOT reply with:** "Great post!" or "This is amazing!" -- these are invisible to the algorithm and look desperate.

**Instead, add genuine value.** Structure:

```
[Specific observation about their post -- proves you read it]

[Value add -- a technique, correction, alternative, or extension]

[Subtle proof -- mention your experience naturally]
```

---

## Phase 2: Content Pillars (Days 1-90)

Your content should rotate between the 4 pillars defined in [content-strategy.md](content-strategy.md). Every post must be **engineered for conversation**.

_[populated during onboarding -- the agent describes each pillar with niche-specific examples, "good post" vs "bad post" comparisons, and hook templates]_

---

## Phase 3: No-Premium Workaround Strategy

_[populated during onboarding -- only included if user doesn't have Premium. References algorithm-playbook.md workarounds with specific tactical steps.]_

---

## Phase 4: Goal-Specific Acquisition Framework (Days 31-90)

_[populated during onboarding -- customized to the user's primary goal]_

<!--
For CLIENT ACQUISITION:
- Warm DM system
- Video audit lead magnet
- Portfolio positioning

For JOB HUNTING:
- Targeted engagement with hiring managers and tech leads
- "Building in public" content that demonstrates hire-ability
- Technical thread strategy for visibility

For AUDIENCE BUILDING:
- Newsletter/product CTA optimization
- Community building tactics
- Collaboration strategy

For THOUGHT LEADERSHIP:
- Contrarian positioning strategy
- Conference/event content leverage
- Media/podcast guest strategy
-->

---

## 90-Day Targets

_[populated during onboarding -- realistic targets based on current follower count, time budget, and niche competitiveness]_

<!--
| Metric | Day 30 | Day 60 | Day 90 |
|--------|--------|--------|--------|
| Followers | [target] | [target] | [target] |
| Avg impressions/post | [target] | [target] | [target] |
| [Goal-specific metric] | [target] | [target] | [target] |
| [Goal-specific metric] | [target] | [target] | [target] |
-->

---

## Key Principles to Remember

- **The Algorithm Cheat Code:** Every post must end with something that FORCES a reply. A question, a hot take, a "what would you do?" -- the reply count IS the reach.
- **The 30-Minute Golden Window:** When you post, stay online and reply to EVERY comment for the first 30 minutes. This triggers the "Author-Engaged Reply" multiplier -- the highest-weighted signal in the Phoenix algorithm.
- **Vector Consistency:** NEVER post about off-topic subjects. Every single post must reinforce your niche positioning. The algorithm maps your account into a vector space -- pollute it and you become invisible.
- **Don't post and ghost.** A post with 50 likes and zero author replies is algorithmically WORSE than a post with 5 likes and 3 back-and-forth conversations. Engagement is not optional -- it's the product.


path: references/hook-library.md
content: # Hook Library -- Proven Frameworks

> **AUTO-UPDATING FILE** -- This file is maintained and re-ranked automatically by the Intelligence Update workflow (SKILL.md Workflow 9). The agent will demote underperforming hooks, add new viral patterns discovered in the feed, and update performance stats.
>
> **During onboarding**, the agent generates niche-specific example templates for each hook type. The frameworks below are universal — the examples are customized.

Hooks ranked by historical performance across niches. Reference this before writing any post.

## Performance-Ranked Hook Types

### 1. Authority Anchor

Tag or reference the official creator of a tool, brand, or concept with a high-level technical opinion or unique framing.

**Why it works:** Bypasses low follower reach by appearing in the brand's "Engaged" feed. Instant credibility through association. Especially powerful for accounts under 1,000 followers.

**Universal Templates:**
- "Hot take: [TOOL] is not a [common label]. It's a [reframed label]."
- "[BRAND] does [thing] better than anyone. Here's the one detail nobody notices:"
- "Everyone uses [TOOL] for [common use]. But its real power is [unexpected use]."

**Niche-Specific Examples:**
_[populated during onboarding -- 2-3 examples using the user's actual tools and niche]_

---

### 2. Negative Parallel

Call out a bad practice, then present the solution.

**Why it works:** Negativity bias stops the scroll. The "fix" creates a knowledge gap that drives thread expansion and bookmarks.

**Universal Templates:**
- "Stop doing [bad practice]. Here's what [experts/top performers] do instead:"
- "Your [thing] looks [mediocre] because of [specific mistake]. The fix takes 2 minutes:"
- "[Common approach] is why your [outcome] is [bad result]. Try [alternative] instead."

**Niche-Specific Examples:**
_[populated during onboarding]_

---

### 3. Knowledge Gap

Tease expertise the reader doesn't have.

**Why it works:** Curiosity gap -> thread expansion -> session depth signal.

**Universal Templates:**
- "90% of [professionals] get [thing] wrong. Here's proof:"
- "I've [done X thing N times]. Here's the #1 mistake I keep seeing:"
- "The [technique/trick] [famous brand/person] uses on EVERY [thing] -- and nobody talks about it:"

**Niche-Specific Examples:**
_[populated during onboarding]_

---

### 4. Contrarian Take / Unpopular Opinion

Challenge conventional wisdom or share a relatable "unpopular" struggle.

**Why it works:** Sparks debate or instant relatability -> reply velocity -> Author-Engaged Reply multiplier.

**Universal Templates:**
- "Unpopular opinion: [thing everyone accepts] is actually [contrarian view]."
- "[Widely recommended practice] is overrated. Fight me."
- "Hot take: [group A] can become [group B]. But [group B] can never become [group A]."

**Niche-Specific Examples:**
_[populated during onboarding]_

---

### 5. Showcase Reveal

Build tension around a visual showcase or achievement.

**Why it works:** Media dwell time + technical specificity -> bookmarks.

**Universal Templates:**
- "This [thing] took me [time] to get right. Here's what I learned:"
- "The difference between a [cheap version] and a [premium version]? This one detail:"
- "If your [thing] doesn't [quality], it's forgettable."

**Niche-Specific Examples:**
_[populated during onboarding]_

---

### 6. Social Proof Drop

Lead with numbers and milestones.

**Why it works:** Concrete numbers = credibility. Questions at end drive replies.

**Universal Templates:**
- "Just hit [X metric]. Here's what I learned about [topic]:"
- "[X metric]. Zero [marketing/ads/connections]. Here's why [approach] beats [alternative]:"
- "[Nth achievement]. Here's the pattern across all my top [things]:"

**Niche-Specific Examples:**
_[populated during onboarding]_

---

## Community & Engagement Hooks (for the 60% engagement posts)

### 7. Community Bait

Ask a question or make a "show me yours" request that's impossible to scroll past.

**Why it works:** Low barrier to reply -> high reply count -> massive algorithmic boost. Visual media (gradient, abstract image) forces scroll-stop.

**Universal Templates:**
- "Name something this reminds you of" + visual
- "Show me your best [thing]. I'll give honest feedback"
- "What's the one [tool/technique/principle] you can't live without?"
- "Your favorite [niche-specific thing]? Mine is [yours]. Fight me"
- "This is my favorite [thing]. Show me yours?"

**Usually needs a Visual Hook Image** -- a bold gradient, abstract art, or simple visual to force the scroll-stop.

---

### 8. Debate Bomb

Drop a deliberately arguable statement to create a war in the comments.

**Why it works:** Controversy -> reply velocity -> the algorithm sees "important conversation" -> pushes to more feeds.

**Universal Templates:**
- "[Group A] can become [Group B]. But [Group B] can never become [Group A]."
- "[Popular tool] is overrated. Fight me."
- "[Popular belief] is just [reductive reframe] and nobody wants to admit it."
- "If your [portfolio/product/profile] doesn't have [thing], you're not a real [role]."

**Works great with a reaction image, meme, or bold statement card.**

---

### 9. Trend Jacker

Ride a viral format or trending topic. Copy what's working and adapt it to your niche.

**Why it works:** Proven formats have pre-validated engagement patterns. Adapting them to your niche gives you the viral mechanics + your unique angle.

**How to use:**
1. Spot a viral format in your feed (gradient + question, "unpopular opinion", ranking list, before/after, etc.)
2. Copy the structure, swap the content for your niche
3. Credit the inspiration if appropriate

**No fixed templates** -- that's the point. Adapt whatever is trending.

---

### 10. Spotlight Generosity

Share someone else's great work with your genuine commentary.

**Why it works:** Builds goodwill -> the spotlighted person engages -> their audience sees you -> network expansion.

**Universal Templates:**
- "[Professionals in niche], this might be the next-level [thing]. Bookmark it for later"
- "I've been using [@person]'s [thing] for [time]. It changed how I [do thing]. Here's why:"
- "[Person/Tool] just shipped [thing] and it's genuinely impressive. Here's what I noticed:"

**Screenshot of their work or product adds scroll-stopping power.**

---

## Hook Selection Guide

| Post Type | Best Hook Types | Visual Media? | Fallback |
|-----------|----------------|---------------|----------|
| Portfolio Piece | Showcase Reveal, Authority Anchor | Media (recommended) | Negative Parallel |
| Deep Dive | Knowledge Gap, Contrarian Take | Optional hook image | Authority Anchor |
| Process Reveal | Contrarian Take, Knowledge Gap | Video preferred | Showcase Reveal |
| Social Proof | Social Proof Drop | Screenshot/stats image | Knowledge Gap |
| Trend Rider | Trend Jacker | Copy the trending format's media | Community Bait |
| Community Question | Community Bait | Visual hook image (recommended) | Trend Jacker |
| Debate Starter | Debate Bomb | Reaction image / bold statement card | Contrarian Take |
| Spotlight Others | Spotlight Generosity | Screenshot of their work | Community Bait |

## Anti-Patterns (NEVER USE)

- "Built a new [thing]" -- zero tension, zero curiosity
- "Check this out!" -- no hook, no specificity
- "Rate it guys" -- generic ask, no value exchange
- "Just launched: [product]" with external link in main post -- link penalty + no hook
- Hashtag-only hooks with no human text
- 5+ self-promo posts in a row -- kills community feeling, looks desperate
- Text-only posts that could be scrolled past without at least considering a visual hook image

## Hashtag Strategy

Use 1-3 maximum per post. Place at end or weave naturally.

**How to pick hashtags:**
- Use 1 broad niche tag (high reach) + 1-2 specific tags (targeted audience)
- Check what Tier 1 accounts in your niche use
- Track which tags correlate with higher reach in your Post Performance Log

**Common high-value tags by niche:**
- Dev: `#WebDev`, `#React`, `#Frontend`, `#Backend`, `#DevOps`, `#BuildInPublic`
- Design: `#UIDesign`, `#UXDesign`, `#DesignSystems`, `#Figma`
- AI/ML: `#AI`, `#MachineLearning`, `#LLM`, `#AIAgents`
- Startup: `#StartupLife`, `#SaaS`, `#IndieHacker`, `#BuildInPublic`
- Marketing: `#GrowthHacking`, `#ContentMarketing`, `#SEO`

**Avoid:**
- Tags that are too generic (`#coding`, `#tech`)
- More than 3 hashtags -- looks spammy
- Hashtags that dilute your niche vector

**Niche-specific tags for this user:**
_[populated during onboarding]_


path: references/memory.md
content: # Memory -- X Account Evolution Log

> This is a living document. Append new entries after every significant interaction. Never delete old entries.
> **This file is initialized during onboarding and updated continuously by the agent.**

---

## Account Snapshot

- **Handle:** _[populated during onboarding]_
- **Followers:** _[populated during onboarding]_
- **Premium:** _[populated during onboarding]_
- **Phase:** _[populated during onboarding -- e.g., "Zero-to-One (pre-500 followers)"]_
- **Start Date:** _[populated during onboarding]_

---

## Voice & Reply Architecture

<!-- Auto-populated during onboarding by analyzing the user's real replies. MANDATORY READ before writing ANY reply. Also read voice-anti-patterns.md EVERY TIME. -->

### Vocabulary Fingerprint

**Words/phrases the user naturally uses:**
_[populated during onboarding -- extracted from real replies]_

**Words/phrases the user NEVER uses:**
_[populated during onboarding -- inferred from reply analysis + user interview]_

### Structural Patterns

_[populated during onboarding -- sentence length, capitalization habits, punctuation style, line break usage, emoji usage, @mention format, grammar quirks]_

### Reply Archetypes (with real examples)

_[populated during onboarding -- 5-7 archetypes extracted from the user's actual replies, each with a label, description, and 2-3 real examples]_

### Mandatory Pre-Reply Check
Before finalizing ANY reply, the agent MUST read [voice-anti-patterns.md](voice-anti-patterns.md) and run the Voice Verification Checklist. If any check fails, rewrite from scratch.

---

## Environment Status

- **twitter-cli:** _[set during prerequisites check]_
- **Sub-agents:** _[set during sub-agent setup]_
- **Auth method:** _[set during prerequisites check]_
- **Last verified:** _[set during prerequisites check]_

---

## Post Performance Log

_[entries added automatically after each post -- format below]_

<!--
### [Date] -- [Post Title/Topic] ([Post Type])
- **Topic:** [what the post was about]
- **Format:** [text-only / image+text / video / thread]
- **Hook used:** [which hook framework from hook-library.md]
- **Stats:**
  - Likes: [N]
  - Retweets: [N]
  - Replies: [N]
  - Bookmarks: [N]
  - Views: [N]
- **Engagement Rate:** [calculated: (likes+replies+retweets+bookmarks)/views x 100]
- **Lesson:** [what worked or didn't]
-->

---

## Engagement Tracking

_[entries added after engagement sessions -- format below]_

<!--
### [Date] ([Session Type])
- **Accounts engaged with:** [@handle1, @handle2, ...]
- **Replies sent:**
  - @handle: [brief description]. [ID: tweet_id]
- **Strategy used:** [which archetypes, which approach]
- **Notable interactions:** [any brand/creator responses, new connections]
-->

---

## Intelligence Update Log

_[entries added after each intelligence update -- format below]_

<!--
### [Date] -- [Update Type: Mini/Standard/Deep]
- **Key Findings:**
  - [finding 1]
  - [finding 2]
- **Files Updated:** [list of files modified]
- **Audience Segment:** [primary segments engaging]
-->

---

## Growth Milestones

| Date | Followers | Notes |
|------|-----------|-------|
| _[onboarding date]_ | _[starting count]_ | Initial onboarding |

---

## Lessons Learned

_[entries added as patterns emerge -- format below]_

<!--
- **[Topic]:** [lesson learned from data]
-->

---

## Competitor Watchlist

_[populated during intelligence updates -- format below]_

<!--
| Account | Niche | Avg Engagement | Hook Style | Content Gap |
|---------|-------|---------------|------------|-------------|
| @handle | [niche] | [rate] | [style] | [gap we can fill] |
-->

---

## Audience Intelligence

_[populated during intelligence updates -- format below]_

<!--
### Audience Segments
| Segment | % of Engagers | Preferred Content | Peak Activity |
|---------|--------------|-------------------|---------------|
| [segment] | [%] | [type] | [time] |
-->

---

## Client/Connection Leads

_[entries added when potential leads are identified -- format below]_

<!--
| Handle | Type | Status | Last Contact | Notes |
|--------|------|--------|-------------|-------|
| @handle | [client/employer/collaborator] | [prospect/contacted/replied/converted] | [date] | [notes] |
-->


path: references/real-replies-archive.md
content: # Real Replies Archive

> **PURPOSE:** This file contains the user's actual replies word-for-word. The agent MUST read this file before drafting ANY reply to study the user's authentic voice, phrasing, and tone. This is NOT a summary -- these are exact quotes.
>
> **Populated during onboarding** by fetching the user's real replies via `twitter search "from:[HANDLE] filter:replies"`. New replies should be appended periodically.

---

## How This File Gets Populated

During onboarding, the agent runs:
```bash
twitter search "from:[HANDLE] filter:replies" -n 30 --json
```

The agent then organizes the replies into categories based on tone and content type. Categories vary per user but common ones include:

- **Technical / Product Replies** — replies about tools, code, technical topics
- **Casual / Conversational** — everyday chat, opinions, banter
- **Playful / Sarcastic** — humor, jokes, roasts
- **Helpful / Advisory** — giving advice, sharing knowledge
- **Self-Promo / Outreach** — mentioning own work, connecting
- **Storytelling / Personal** — sharing experiences, backstory
- **Feedback / Acknowledgment** — responding to praise, criticism

---

## Archived Replies

_[populated during onboarding -- the agent pastes real replies here organized by category]_

---

_Last updated: never_
_Next update: Run onboarding or manually run `twitter search "from:[HANDLE] filter:replies" -n 50 --json` and append new replies not already in this file._


path: references/subagent-definitions.md
content: # Sub-Agent Definitions

> **PURPOSE:** This file contains the system prompts and metadata for 4 specialized sub-agents. The main agent reads this file and creates the sub-agent files in whatever format the host IDE requires.
>
> These definitions are IDE-agnostic -- the content is the same regardless of whether the host is Claude Code, Codex, Gemini CLI, OpenCode, or any other agent-capable IDE.
>
> **During onboarding**, the agent updates the system prompts below with the user's handle, niche, and voice rules.

---

## Sub-Agent 1: x-reply-crafter

**Color:** cyan
**Model:** inherit
**Tools:** Read, Grep, Bash

**Description:**
Use this agent when drafting replies to other people's X/Twitter posts. This agent specializes in matching the user's authentic voice and avoiding AI-generated patterns.

**Trigger examples:**
- "reply to this post"
- "draft a reply"
- "what should I say to this"
- When the main agent needs a voice-matched reply during engagement sessions

**System Prompt:**

```
You are the Reply Crafter for @[HANDLE]'s X account. Your ONLY job is to draft replies that sound exactly like the user -- not like an AI.

**MANDATORY: Before writing ANY reply, read these files:**
1. references/voice-anti-patterns.md -- banned phrases and structures
2. references/real-replies-archive.md -- the user's ACTUAL replies word-for-word
3. references/memory.md -- Voice & Reply Architecture section only

**Your Process:**
1. Read the original post carefully. If it has images, note visual details provided.
2. Pick the most appropriate Reply Archetype from memory.md (archetypes are populated during onboarding based on the user's real replies).
3. Draft the reply matching that archetype's tone, length, and formatting.
4. Run the Voice Verification Checklist:
   - Would a human type this on their phone in 10 seconds?
   - Does it read like a LinkedIn comment? -> rewrite
   - Does it contain any banned phrase? -> rewrite
   - Is it a numbered list? -> restructure
   - Could you remove half the words? -> too wordy
   - More than 1 emoji? -> remove extras
5. Present 2-3 options with [N/280] count and archetype label

**Voice Rules:**
- Match the user's vocabulary fingerprint from memory.md
- Match the user's structural patterns (capitalization, punctuation, line breaks)
- Preserve authentic grammar quirks -- do NOT "fix" them
- NEVER: "Great take!", "Love this!", "This resonates", numbered lists, perfect grammar, em dash abuse
- Emoji usage should match the user's natural pattern (check real-replies-archive.md)
```

---

## Sub-Agent 2: x-feed-researcher

**Color:** green
**Model:** inherit
**Tools:** Read, Grep, Bash

**Description:**
Use this agent when running pre-post research on X/Twitter topics. This agent searches the platform, analyzes competitor posts, identifies conversation gaps, and produces structured Research Summaries.

**Trigger examples:**
- "research this topic before posting"
- "what's trending around [topic]"
- "find what competitors are saying"
- When the main agent needs a Research Summary during post creation

**System Prompt:**

```
You are the Feed Researcher for @[HANDLE]'s X account. Your ONLY job is to run thorough research and produce a structured Research Summary.

**MANDATORY: Read these files first:**
1. references/cli-reference.md -- twitter-cli commands and SAFETY RULES
2. references/algorithm-playbook.md -- how the X algorithm works
3. references/content-strategy.md -- content pillars, target accounts

**Your Process:**
1. Web Search: Search the topic + relevant niche keywords for landscape and demand signals
2. X Research:
   - `twitter search "[topic]" -t Latest --max 20 -c --json`
   - `twitter search "[topic]" --from [tier1_account] --json` for at least 1 competitor
3. Identify the conversation gap -- what hasn't been said yet
4. Note trending hashtags, phrases, or debates
5. If analyzing a post with images:
   - Download: `curl -o "./references/media/research_img.jpg" "[URL]"`
   - Verify: `ls -la ./references/media/research_img.jpg`
   - Describe visual findings

**MANDATORY OUTPUT -- Research Summary:**
```
RESEARCH SUMMARY
- Recent posts found: [>=3 posts with engagement data]
- Conversation gap: [what hasn't been said]
- Trending hashtags: [relevant tags]
- Competitor angle: [>=1 post from Tier 1 account]
- Image analysis: [visual findings or "N/A"]
- Memory patterns: [what worked before]
```

You MUST fill >=4 of these 6 fields. If you cannot, do more research.

**CLI Safety Rules:**
- Always use double quotes for text arguments
- Always add --json flag
- Add -c for large result sets
- Never hallucinate flags -- only use what's in cli-reference.md
```

---

## Sub-Agent 3: x-post-composer

**Color:** magenta
**Model:** inherit
**Tools:** Read, Grep

**Description:**
Use this agent when crafting X/Twitter post text. This agent takes a Research Summary and produces 2-3 post variations with hooks, character counts, and strategic reasoning.

**Trigger examples:**
- "write the post"
- "craft variations"
- "compose the tweet"
- When the main agent has a Research Summary and needs post text

**System Prompt:**

```
You are the Post Composer for @[HANDLE]'s X account. Your ONLY job is to craft compelling post text from a Research Summary.

**MANDATORY: Read these files first:**
1. references/hook-library.md -- proven hook frameworks ranked by performance
2. references/content-strategy.md -- content pillars, templates, reply framework
3. references/content-planner.md -- planned posts queue, scheduling
4. references/user-profile.md -- user identity, stack, brand guidelines

**Your Process:**
1. Receive a Research Summary from the researcher
2. Select the best hook type from hook-library.md for this angle
3. Write 2-3 variations with different hooks:
   - Hook first -- opening line stops scrolling
   - Specific details relevant to the user's niche (not vague generalities)
   - End with a question -- reply count IS the reach
   - <=280 characters -- validate and show [N/280]
   - 1-3 hashtags from the approved list
   - @Tags only when genuinely referencing someone's work
   - NO external links in main post
4. For each variation, explain the strategic reasoning
5. Prepare first reply text (link + extra context)

**Hard Rules:**
- Every post MUST be <=280 characters. URLs = 23 chars each.
- Never more than 3 hashtags
- Every post must drive replies (question, hot take, "what would you do?")
- Every post reinforces the user's niche vector (from user-profile.md)
- Emoji usage should match the user's natural style
- Mobile-first formatting with line breaks

**Media Rule:**
- If post needs video media -> flag it: "VIDEO NEEDED -- user must post manually"
- If post needs image -> note the image path or suggest generating one
```

---

## Sub-Agent 4: x-intel-updater

**Color:** yellow
**Model:** inherit
**Tools:** Read, Write, Grep, Bash

**Description:**
Use this agent when running the Intelligence Update workflow -- analyzing post performance, scanning competitor feeds, profiling the audience, and auto-updating strategy files.

**Trigger examples:**
- "run intelligence update"
- "update the strategy"
- "what's working and what's not"
- At the end of sessions for the mini performance update

**System Prompt:**

```
You are the Intelligence Updater for @[HANDLE]'s X account. Your ONLY job is to analyze performance data and update strategy files.

**MANDATORY: Read these files first:**
1. references/memory.md -- post performance log, audience intelligence, growth milestones
2. references/content-strategy.md -- content pillars, target accounts, feed trends
3. references/hook-library.md -- hook rankings, performance data
4. references/cli-reference.md -- twitter-cli commands and SAFETY RULES

**Your Process (5 Phases):**

Phase 1 -- Performance Analysis:
1. `twitter user-posts [HANDLE] --max 20 -c --json`
2. Calculate engagement rate: (likes + replies + retweets + bookmarks) / views x 100
3. Rank posts, identify top 3 and bottom 3 performers
4. Update Post Performance Log in memory.md

Phase 2 -- Feed Intelligence:
1. `twitter feed --json -n 40 --filter`
2. Identify top 5 high-engagement posts across feed
3. Extract hook patterns, formats, topics, hashtags
4. Update Competitor Watchlist in memory.md

Phase 3 -- Audience Profiling:
1. Review replies/likes on recent posts
2. Categorize engagers into segments relevant to the user's niche
3. Update Audience Intelligence in memory.md

Phase 4 -- Potential Follower Analysis:
1. Sample followers of competitor accounts
2. Identify what content they engage with
3. Update Target Audience Profile in content-strategy.md

Phase 5 -- Auto-Update Files:
- Re-rank hooks in hook-library.md based on performance
- Add new hooks discovered from feed analysis
- Update feed trends in content-strategy.md
- Log the update with date and findings in memory.md

**Update Schedule:**
- Mini (Phase 1 only): End of every session
- Standard (Phases 1-3): Every 5 posts or weekly
- Deep (All phases): Every 2 weeks or on user request

**CLI Safety:** Follow all rules in cli-reference.md. Always use --json and -c flags.
```

---

_These definitions are templates. The host agent should adapt the file format (frontmatter structure, directory location) to match whatever IDE/CLI it's running in. During onboarding, replace `[HANDLE]` with the user's actual X handle._


path: references/user-profile.md
content: # User Profile

> **This file is populated during onboarding.** If you see unfilled placeholders below, the onboarding has not been run yet. The agent should detect this and trigger the onboarding flow from SKILL.md.

**onboarding_complete:** false

---

## Identity

- **Name:** _[populated during onboarding]_
- **X Handle:** _[populated during onboarding]_
- **Brand Position:** _[populated during onboarding -- e.g., "Cinematic Web Experiences", "AI-Native SaaS Builder", "Design Systems Architect"]_
- **Professional Status:** _[populated during onboarding -- e.g., "Solo freelancer", "Employed at X, building side projects", "Indie hacker"]_
- **Location/Timezone:** _[populated during onboarding]_
- **X Premium:** _[populated during onboarding -- Yes/No]_
- **Current Follower Count:** _[populated during onboarding]_

---

## Niche & Expertise

- **Professional Role:** _[populated during onboarding -- e.g., "Frontend developer", "Full-stack engineer", "Designer", "Founder", "DevRel"]_
- **Specialization:** _[populated during onboarding -- the specific niche within the role]_
- **Years of Experience:** _[populated during onboarding]_
- **Superpower:** _[populated during onboarding -- what makes this person different from others in the niche]_

### Core Tech Stack / Toolset

| Category | Technologies |
|----------|-------------|
| _[e.g., Frameworks]_ | _[populated during onboarding]_ |
| _[e.g., Languages]_ | _[populated during onboarding]_ |
| _[e.g., Tools]_ | _[populated during onboarding]_ |
| _[e.g., Platforms]_ | _[populated during onboarding]_ |

---

## Social Proof & Assets

### Existing Social Proof
_[populated during onboarding -- portfolio links, GitHub stars, app users, published work, conference talks, newsletter subscribers, product metrics, etc.]_

### Content Assets
_[populated during onboarding -- screen recordings, code samples, blog posts, videos, designs, etc.]_

### Other Platforms
_[populated during onboarding -- LinkedIn, YouTube, Threads, blog, etc.]_

---

## Goals

- **Primary Goal:** _[populated during onboarding -- client acquisition / job hunting / audience building / thought leadership / product promotion / community building]_
- **Target Audience:** _[populated during onboarding -- who the user wants to reach]_
- **Short-term (0-90 days):** _[populated during onboarding]_
- **Medium-term (90-180 days):** _[populated during onboarding]_
- **Long-term:** _[populated during onboarding]_

---

## Constraints

- **Daily Time Budget:** _[populated during onboarding -- e.g., "1 hour"]_
- **Budget:** _[populated during onboarding -- e.g., "Zero marketing budget"]_
- **Other Constraints:** _[populated during onboarding -- e.g., "No Premium", "Camera shy", "Limited content backlog"]_

---

## Voice & Personality

- **Voice Description:** _[populated during onboarding -- e.g., "casual, blunt, technical", "friendly and approachable", "sarcastic but helpful"]_
- **Avoid:** _[populated during onboarding -- words, phrases, or styles the user wants to avoid]_
- **Authentic Examples:** _[populated during onboarding -- example posts/replies the user shared]_

---

## Brand Guidelines

### DO:
_[populated during onboarding -- generated from niche + goals + superpower]_

### DON'T:
_[populated during onboarding -- generated from constraints + anti-patterns + voice]_

### Key Phrases to Weave Into Content
_[populated during onboarding -- generated from niche + specialization + unique angles]_


path: references/voice-anti-patterns.md
content: # Voice Anti-Patterns -- What NEVER To Write

> **MANDATORY READ** before writing ANY reply. If a drafted reply contains ANY pattern from this file, rewrite it from scratch.

## Banned Phrases (Instant AI Detection)

Never use these — they are the #1 signal that a reply is AI-generated:

- "Great take!", "This is fire", "Love this!", "Couldn't agree more"
- "This resonates with me", "Spot on!", "This hits different"
- "Here's the thing though...", "Let me break this down"
- "As someone who...", "I've been saying this for years"
- "Absolutely!", "Totally agree!", "100% this"
- "This is incredibly...", "This is genuinely..."
- "I'd love to see...", "Would love to connect"
- "Thanks for sharing this!", "Thanks for putting this out there"
- "This is a great point", "Really appreciate this"
- "Nailed it!", "Chef's kiss"
- Starting replies with "I" more than once in a row
- "Not gonna lie" followed by formal language
- "Here's my two cents"
- "Just stumbled upon this"
- "This is a game-changer"
- "Super insightful"
- "This is everything"
- "Couldn't have said it better myself"

## Banned Structures

These structural patterns scream AI:

- **Numbered lists in replies** — real humans don't structure X replies as "1. 2. 3."
- **Perfect grammar and punctuation throughout** — real posts have casual punctuation
- **Intro -> Body -> Conclusion structure** — replies are NOT mini-essays
- **More than 1 emoji per reply** — most people don't emoji-spam in substantive replies
- **Mirroring the original poster's exact phrase structure** — sounds like parroting
- **Em dash abuse** — using -- more than once per reply
- **Starting with a compliment then pivoting to substance** — the "sandwich" technique is obvious
- **Overly specific technical terms the user wouldn't naturally use** — don't fake expertise on unfamiliar topics
- **Semicolons** — almost nobody uses semicolons in casual X replies
- **Parenthetical asides (like this) in every reply** — occasional is fine, every time is a pattern
- **Overly balanced "on one hand... on the other hand" structure** — pick a side
- **Three-part parallel sentences** — "It's not X. It's not Y. It's Z." once is fine, repeatedly is a tell

## Required Natural Elements

The user's replies MUST include authentic markers from their Voice Architecture (see memory.md). Universal markers of authentic human writing:

- **Natural contractions**: "gonna", "don't", "it's", "can't", "wouldn't"
- **Occasional lowercase starts**: not every sentence needs to start with a capital letter
- **Variable sentence length**: mix short punchy lines with longer thoughts
- **Direct questions without preamble**: "what stack is this?" not "I'm curious about what tech stack you used here"
- **Whitespace-heavy formatting**: break thoughts into separate lines for readability
- **Unpolished grammar when casual**: authentic typos and grammar quirks should be PRESERVED, not fixed
- **Blunt honesty**: say what you mean without diplomatic hedging
- **Personal anecdotes dropped casually**: real experiences mentioned naturally, not formally introduced
- **Direct @mention tagging**: just "@handle text" without "Hey" or "Hi" prefix

## Voice Verification Checklist

Run this mentally before finalizing ANY reply. If any check fails, rewrite:

1. Would a human type this on their phone in 10 seconds? If no -> too polished
2. Does it read like a LinkedIn comment? If yes -> rewrite completely
3. Does it contain any phrase from the Banned Phrases list? If yes -> rewrite
4. Is it a numbered list or uses intro/body/conclusion? If yes -> restructure
5. Could you remove half the words and keep the meaning? If yes -> it's too wordy
6. Does it start the same way as the last 3 replies? If yes -> vary the opening
7. Does it have more than 1 emoji? If yes -> remove extras
8. Would the user actually say this out loud? If no -> rewrite in their voice
9. Does it sound like it's trying to impress? If yes -> make it casual
10. Is it longer than necessary? If yes -> cut ruthlessly


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)