xpost

Portable AI-agent skill for controlled X/Twitter engagement workflows.

中文说明

What It Does

xpost helps an AI agent operate an authenticated X browser session for low-frequency engagement tasks:

• discover or open topics
• optionally enrich topic context with Hermes Tweet/Xquik search results
• build a broad randomized topic pool instead of always picking top trends
• understand visible posts before writing
• draft or publish standalone posts
• like a configurable number of posts
• write short human-sounding replies
• optionally attach images and verify the image preview
• summarize every task round

The skill is designed for Codex, Claude Code, OpenClaw, and other agents that can read local skill instructions and control a browser.

Requirements

Required:

• an AI agent that can read the skill files
• a browser session logged into X
• some browser automation capability, such as a browser plugin, MCP/devtools tool, or user-guided browser takeover

Optional:

• Python 3
• DrissionPage
• Hermes Tweet/Xquik API key for read-only topic context

DrissionPage is not required for the core workflow. It is only used as a Windows clipboard image-paste fallback when normal X image upload fails.

Hermes Tweet/Xquik is also optional. It can provide read-only public search context for topic selection and drafting, but it never replaces browser verification before likes, replies, or posts.

Without Python or DrissionPage, the skill can still browse topics, draft posts, publish text posts, like posts, and write replies if the agent has another browser control method. Image posting should first use the native X upload UI. If that fails and no paste-capable tool is available, the agent should ask the user to attach the image manually or continue text-only only after explicit approval.

Repository Contents

SKILL.md                    Codex skill entry point
CLAUDE.md                   Portable instructions for Claude Code / OpenClaw-style agents
AGENTS.md                   Generic agent instructions
agents/openai.yaml          UI metadata for Codex-style skill lists
references/workflow.md      Main operating workflow and configuration reference
scripts/set_clipboard_image.ps1
scripts/drission_ctrl_v.py  Windows image paste fallback for X uploads

Install or Reference

For Codex, place this folder under your skills directory:

%USERPROFILE%\.codex\skills\xpost

For Claude Code, OpenClaw, or another agent, keep the repository anywhere local and point the agent at the folder:

Use the xpost skill at C:\path\to\xpost.
Read CLAUDE.md and references/workflow.md first.

Login

xpost does not collect credentials.

Use an existing logged-in browser session when possible. If X is logged out, the agent should open X and ask you to log in manually in the browser. Do not paste passwords, 2FA codes, cookies, tokens, or session data into chat.

Configuration

Common options:

Option	Default	Meaning
language	English	Language for posts and replies
tone	casual human	Writing style, such as witty, warm, dry, concise, curious
task_mode	one_round	Run one low-volume engagement round
publish_post	false	Whether to publish a standalone/main post
publish_reply	follows comment	Whether replies may be published
draft_only	context-dependent	When true, blocks all public posting
comment	true when requested	Whether to write a reply
comments_count	1	Number of replies to write, capped at 3 unless requested
likes_count	1-3	Number of posts to like, capped at 5 unless requested
post_with_image	false	Whether to attach an image to a standalone post
image_source	not set	Local path, generated image, clipboard image, or user-provided image
topic_source	named, preferred, or random_explore	Use a named topic, a preferred topic, or random Explore discovery
topic_context_source	browser	Use hermes_tweet to enrich topic context from Hermes Tweet/Xquik search before browser verification
topic_query	not set	Explicit topic/search query, such as AI, photography, Python, or indie games
preferred_topics	not set	Topics the user likes; used before generic Explore randomness
excluded_topics	not set	Specific topics to avoid, such as basketball, NBA, or celebrity names
excluded_topic_categories	not set	Categories to avoid, such as sports, politics, or finance
topic_randomization	absolute_random	Build and shuffle a broader candidate pool before choosing
topic_candidate_count	12-30	Target number of candidate topics
avoid_recent_topic_categories	true	Avoid repeating the same obvious category when alternatives exist
minimum_post_interval	1 hour	Conservative minimum interval for public standalone posts
require_final_confirmation	true unless explicitly disabled	Ask before clicking Post or Reply; set false to publish after verification without asking again

Important publishing behavior:

• publish_post=false only blocks standalone/main posts.
• publish_reply=true allows a reply when comment=true and draft_only=false.
• draft_only=true blocks both standalone posts and replies.
• Default behavior is draft-and-confirm.
• require_final_confirmation=true means the agent should show the final text/media plan and wait for approval.
• require_final_confirmation=false means the agent should publish after verification without asking again.

Optional Hermes Tweet/Xquik context:

• Set topic_context_source=hermes_tweet.
• Provide HERMES_TWEET_API_KEY or XQUIK_API_KEY in the local environment.
• Optionally set HERMES_TWEET_API_BASE or XQUIK_BASE_URL.
• Treat search results as read-only evidence. Open and verify target posts in the browser before liking or replying.

Natural language examples:

• Post an English tweet -> language=English, publish_post=true, default require_final_confirmation=true, so the agent drafts first and asks before publishing.
• Post an English tweet, no confirmation -> language=English, publish_post=true, require_final_confirmation=false.
• 发一个英文帖子，不用确认 -> language=English, publish_post=true, require_final_confirmation=false.

Prompt Examples

Draft only, no public actions:

Use the xpost skill at C:\path\to\xpost.
Read CLAUDE.md and references/workflow.md first.

Run one X engagement round:
- language: English
- tone: casual human
- publish_post: false
- publish_reply: false
- draft_only: true
- likes_count: 0
- comment: true
- post_with_image: false

Draft a reply but do not publish anything. Summarize the result at the end.

Like and reply, but do not create a standalone post:

Use the xpost skill at C:\path\to\xpost.
Read CLAUDE.md and references/workflow.md first.

Run one X engagement round:
- language: English
- tone: casual human
- topic_randomization: absolute_random
- topic_candidate_count: 20
- avoid_recent_topic_categories: true
- publish_post: false
- publish_reply: true
- draft_only: false
- likes_count: 2
- comment: true
- post_with_image: false

Do not pick only from the top visible trends. Build a broad candidate pool by scrolling Explore, shuffle it, avoid repeating the same obvious category if alternatives exist, then choose randomly.

Summarize the result at the end, including candidate topic count, likes, reply text, and any skipped steps.

Browse a specific topic, like 2 posts, and comment once:

Use the xpost skill at C:\path\to\xpost.
Read CLAUDE.md and references/workflow.md first.

Browse posts about AI tools:
- language: English
- tone: casual human
- topic_source: named
- topic_query: AI tools
- publish_post: false
- publish_reply: true
- draft_only: false
- require_final_confirmation: true
- likes_count: 2
- comment: true
- comments_count: 1
- post_with_image: false

Search/open the named topic directly. Do not choose from generic Explore trends first. Like 2 relevant posts, write 1 human-sounding English reply, ask before publishing the reply, and summarize the result.

Use Hermes Tweet/Xquik for topic context, then verify in browser:

Use the xpost skill at C:\path\to\xpost.
Read CLAUDE.md and references/workflow.md first.

Browse posts about AI agents:
- language: English
- tone: casual human
- topic_source: named
- topic_query: AI agents
- topic_context_source: hermes_tweet
- publish_post: false
- publish_reply: true
- draft_only: false
- likes_count: 1
- comment: true

Use Hermes Tweet/Xquik only to find recent public context. Open the chosen post in X, verify it is visible, then draft one specific reply and ask before publishing.

Use preferred topics and avoid basketball/sports:

Use the xpost skill at C:\path\to\xpost.
Read CLAUDE.md and references/workflow.md first.

Run one X engagement round:
- language: English
- tone: casual human
- preferred_topics: [AI, indie games, photography, programming, productivity]
- excluded_topics: [basketball, NBA, Lakers]
- excluded_topic_categories: [sports]
- publish_post: false
- publish_reply: true
- draft_only: false
- likes_count: 2
- comment: true

Pick from my preferred topics before using random Explore. Avoid basketball, NBA, Lakers, and sports topics. Summarize the topic source and actions.

Create a standalone post with an image:

Use the xpost skill at C:\path\to\xpost.
Read CLAUDE.md and references/workflow.md first.

Create one X post:
- language: English
- tone: casual human
- publish_post: true
- require_final_confirmation: true
- post_with_image: true
- image_source: C:\path\to\image.png
- minimum_post_interval: 1 hour

Attach the image and verify a visible preview before publishing. If image upload fails, try the clipboard paste fallback with DrissionPage. Do not publish text-only unless I approve it.

Publish directly without a second confirmation:

Use the xpost skill at C:\path\to\xpost.
Read CLAUDE.md and references/workflow.md first.

Post one English X post:
- language: English
- tone: casual human
- publish_post: true
- require_final_confirmation: false
- post_with_image: false
- minimum_post_interval: 1 hour

Generate the post, open X, verify the composer text, and publish it directly without asking me again. Summarize the final result.

Generate only the text:

Use the xpost skill at C:\path\to\xpost.
Read CLAUDE.md and references/workflow.md first.

Generate 5 possible X posts about this topic:
Topic: AI is already helping people with everyday writing.
Language: English
Tone: casual human, slightly amused

Do not open X and do not publish.

Image Upload Fallback

On Windows, X image uploads can fail through some browser automation tools. The skill includes a fallback:

1. Put the actual image bitmap on the OS clipboard with scripts/set_clipboard_image.ps1.
2. Focus the X composer.
3. Send Ctrl+V through DrissionPage with scripts/drission_ctrl_v.py.
4. Verify that an image preview is visible before publishing.

If Python or DrissionPage is unavailable, skip this fallback. Do not publish an image-required post without a visible image preview unless the user explicitly approves text-only posting.

Safety Notes

• Keep posting low-frequency.
• Do not spam or repeatedly post similar content.
• Do not invent facts about news or live events.
• Do not bypass login checks, CAPTCHA, rate limits, or platform protections.
• Do not publish if the visible composer does not match the intended text or media.

Output Summary

Every round should end with a concise summary:

• topic chosen
• candidate topic count when random topic discovery was used
• context source, including Hermes Tweet/Xquik when used
• post status
• image status
• likes performed and verified
• reply text and publish status
• blocked steps or manual actions needed
• next safe posting time if known