Guide · Agent skill

How to use the X (Twitter) API agent skill: setup and examples

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The x-api skill teaches an AI agent to work with X (formerly Twitter) through its official API: posting tweets and threads, uploading images, reading timelines, searching recent posts and checking engagement. This guide is for people who have not used agent skills before and want to install it, set up credentials, and get useful results. By the end you will know what to install, what you need first, and how to ask for work in plain language.

X (Twitter) API Integrationaffaan-m/ECC · MIT Download the skill

Quick start

1Get X API credentials. Create an X developer account and generate the bearer token, and for posting, the consumer key and secret plus access token and secret.
2Install the skill. Download the ZIP from this page, unzip it into ~/.claude/skills/ or a project's .claude/skills/, or upload it under Settings → Capabilities → Skills in the Claude apps.
3Set environment variables. Export X_BEARER_TOKEN for read and search, and the X_CONSUMER_* and X_ACCESS_TOKEN* variables for posting, keeping them out of your code.
4Install Python packages. Make sure requests and requests_oauthlib are installed in the Python environment the agent will use.
5Ask for the task in plain language. Describe the account, the content and whether to draft first or post now, for example asking for three draft tweets to review.
6Review and approve. Read the draft the agent returns, ask for changes, and approve only when you want it published.
7Check engagement. Ask the agent to fetch public_metrics for your posts to see likes, reposts and other counts.

What the x-api skill lets the agent do

Once installed, the agent knows how to talk to X on your behalf. It writes the code for each task, such as posting a single tweet, posting a thread where each post replies to the one before, uploading an image and attaching it to a post, reading a user's timeline, searching recent posts, and looking up a user by username.

The skill also covers the parts that are easy to get wrong: which authentication method fits which task, how to read X's rate-limit headers at runtime, how to handle error responses, and how to keep credentials out of your code.

Post single tweets and threads
Upload media and post with it
Read a user's timeline with public metrics
Search recent posts, for example from a specific account without retweets
Pull recent original posts to model a writing voice
Track engagement through public_metrics

Install the x-api skill

Download the ZIP from this page and unzip it. To make the skill available across your projects, place the unzipped folder in ~/.claude/skills/. To make it available only inside one project, place it in that project's .claude/skills/ folder.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

The package includes two files: SKILL.md, which holds the instructions the agent follows, and agents/openai.yaml.

Personal install: ~/.claude/skills/
Project install: .claude/skills/ inside your project folder
Claude apps: Settings → Capabilities → Skills, then upload

Set up X API credentials

You need an X developer account with API credentials. Reading public data and search use a bearer token (app-only authentication). Posting, managing the account, and any write flow require OAuth 1.0a user-context credentials: a consumer key and secret plus an access token and secret.

Store these as environment variables rather than in code. The skill prefers the X_CONSUMER_* and X_ACCESS_TOKEN_SECRET names. Older setups may use aliases such as X_API_KEY, X_API_SECRET or X_ACCESS_SECRET.

Bearer token (read and search): X_BEARER_TOKEN
Write access: X_CONSUMER_KEY, X_CONSUMER_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET
Install Python packages requests and requests_oauthlib before running the code
Regenerate tokens at developer.x.com if they are ever exposed

export X_BEARER_TOKEN="your-bearer-token"

Trigger the skill with natural requests

You do not need special syntax. The skill activates when you ask for X work in ordinary language. The skill's own trigger list includes phrases such as "post to X", "tweet", "X API" or "Twitter API", as well as requests to read a timeline, search X, or track analytics.

Be specific about the account, the content and whether you want it posted now. The skill asks for approval before posting unless you explicitly say to post immediately.

"Draft three tweets about our release notes and show me them before posting."
"Search recent posts from @username without retweets and summarise the topics."
"Post this thread after I approve it: [paste thread]."
"Show the likes and reposts for my last 10 posts."

Example: post a thread safely

The skill's thread function posts the first tweet, then posts each following tweet as a reply to the one before it, and returns the list of tweet IDs. For a safe workflow, ask the agent to draft and validate the posts first, then post only after you approve.

The recommended order is: pull recent posts if voice matters, build a voice profile, generate the draft, check length and thread structure, return the draft for approval, and post only after approval.

Validate length and thread structure before posting
Return the draft for approval unless you asked to post now
Track engagement afterwards through public_metrics

def post_thread(oauth, tweets: list[str]) -> list[str]:
    ids = []
    reply_to = None
    for text in tweets:
        payload = {"text": text}
        if reply_to:
            payload["reply"] = {"in_reply_to_tweet_id": reply_to}
        resp = oauth.post("https://api.x.com/2/tweets", json=payload)
        tweet_id = resp.json()["data"]["id"]
        ids.append(tweet_id)
        reply_to = tweet_id
    return ids

Handle rate limits

X rate limits vary by endpoint, authentication method and account tier, and they change over time. The skill tells the agent not to rely on fixed tables in code. Instead, it reads the x-rate-limit-remaining and x-rate-limit-reset headers on each response and waits when the remaining count is low.

When a request returns status 429, the skill's error handling raises an error that includes the reset time. Check the current X developer documentation for the limits that apply to your account.

Read x-rate-limit-remaining and x-rate-limit-reset on every response
Back off until the reset time instead of retrying immediately
Check the X developer docs for current limits

Keep your credentials and account safe

The skill's security rules are short: never hardcode tokens, use environment variables or .env files, never commit .env files (add them to .gitignore), rotate tokens if they leak, and use read-only tokens when write access is not needed. Keep OAuth secrets out of source code and logs.

The skill does not address X's platform policies. Automating high-volume or spam-like posting can get an account suspended, so keep posting deliberate and reviewed.

Use .gitignore for .env files
Prefer read-only tokens where possible
Do not run high-volume or spam-like posting

What people use it for

Drafting and scheduling-ready review of X posts in your own voice, with approval before publishing
Posting a multi-part thread where each tweet replies to the previous one
Attaching an image to a post by uploading it through the v1.1 media endpoint
Searching recent posts from an account while excluding retweets and replies
Building a script or bot that monitors a timeline or search and tracks engagement

Frequently asked questions

Is the x-api skill free to use?

The skill's source file is licensed under MIT. Using the X API itself depends on your X developer account and its access terms, which the skill does not cover, so check X's developer site for current pricing and plan details.

What do I need before the x-api skill works?

You need Python with requests and requests_oauthlib installed, an X developer account with API credentials, environment variables holding those credentials, and network access to api.x.com and upload.twitter.com. Posting requires the OAuth 1.0a user-context keys.

Which credentials do I need for posting versus searching?

Searching and reading public data use the bearer token. Posting tweets, uploading media and other write flows need the consumer key and secret plus the access token and secret.

How do I install the x-api skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects or into a project's .claude/skills/ folder for one project. In the Claude apps you can upload it under Settings → Capabilities → Skills.

Does the skill run code on my computer?

Yes. The skill runs scripts and uses the network. The code it writes calls api.x.com and upload.twitter.com, so review the code and keep credentials in environment variables or .env files that are never committed.

Can the agent post to X without my approval?

The skill's workflow returns drafts for approval before posting unless you explicitly ask it to post now. Review each draft before approving.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose x-api if you are a developer building a script or bot for X, or a creator or marketer who wants an agent to draft and post in your voice with your approval. Skip it if you do not have an X developer account and API credentials, or if you plan high-volume or spam-like posting, since the skill does not address X's policy rules.

Download the skill