Skip to content
Get packs

Guide · Agent skill

How to use the X (Twitter) API CLI agent skill: xurl

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

The xurl skill teaches an AI agent to use the xurl command-line tool, which makes authenticated requests to the X (formerly Twitter) API. Once it is installed and you have authenticated on your own machine, the agent can post, reply, quote, search, read posts, look up users, follow or block accounts, send direct messages and upload media. This guide explains what the skill does, how to install it, how to ask for things in plain language and what to watch out for.

X (Twitter) API CLIspinabot/brigade · MIT

Quick start

  1. 1Download and unzip the skill. Download the xurl ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Install the xurl CLI. Install xurl with Homebrew, npm, the shell script or Go, as described in the skill's installation section.
  3. 3Register an X developer app. Create your own app with X and fill in its credentials yourself, outside the agent session.
  4. 4Authenticate. Run xurl auth oauth2 in your terminal, then run xurl auth status to confirm an app is registered.
  5. 5Ask in plain language. Describe the task, such as searching for posts or drafting a reply, and mention X so the agent uses the skill.
  6. 6Review before writing. Check any post, reply or DM the agent proposes before it goes live on your account.

What is an agent skill, and what does xurl let the agent do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when a task matches the skill's description. This one, xurl, tells the agent how to run the xurl command-line tool against X.

Commands return JSON to stdout. The skill covers shortcut commands for common actions and also explains how to call any X API v2 endpoint directly in a curl-style way.

  • Publish and manage posts: post, reply, quote, delete, repost, like, bookmark
  • Search and read: search posts, read a single post, view your home timeline, mentions, bookmarks and likes
  • Manage accounts: look up users, follow, unfollow, block, unblock, mute, unmute, list followers and following
  • Messages and media: send and list direct messages, upload media and check media status

Install the xurl skill in Claude

Download the ZIP of the xurl skill from this page. It contains SKILL.md. Unzip it so the skill folder ends up in ~/.claude/skills/ for all your projects, or in a project's .claude/skills/ folder if you want it only for that project.

Alternatively, in the Claude apps go to Settings, then Capabilities, then Skills, and upload the skill there.

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

Install the xurl CLI tool

The skill needs the xurl command-line tool on your machine. The skill's metadata lists Homebrew and npm as install options, and the source also documents a shell script and Go. Use one of the following.

  • Homebrew (macOS): brew install --cask xdevplatform/tap/xurl
  • npm: installs the @xdevplatform/xurl package globally
  • Shell script: installs to ~/.local/bin; if that is not on your PATH, the script says what to add
  • Go: go install github.com/xdevplatform/xurl@latest
npm install -g @xdevplatform/xurl

Create an X developer app and authenticate

xurl needs an X developer app with API credentials. You must register the app yourself, outside the agent session. The skill is unusable without these credentials.

After the credentials are registered, authenticate with the OAuth 2 flow. Then check that it worked. Tokens are saved to ~/.xurl in YAML format, and each app keeps its own isolated tokens.

If you have several apps, you can set a default or use one for a single request.

  • Register an app manually on X and keep credentials to yourself
  • Authenticate: xurl auth oauth2
  • Check status: xurl auth status
  • List apps: xurl auth apps list
  • Set a default app and user: xurl auth default prod-app alice
  • Use one app for one request: xurl --app dev-app /2/users/me
xurl auth oauth2 xurl auth status

Trigger the skill with natural requests

You do not need to name the skill or type commands. Describe the task in plain language that mentions X, and the agent should pick up the skill because its description covers posting, replying, quoting, searching, reading posts, managing followers, sending DMs and uploading media.

Be specific about the post ID, handle or text. Use a post URL or ID, and a handle with or without the @ sign. Review drafts before publishing, because posts and DMs go live on your real account.

  • "Post this to X: [your text]"
  • "Reply to https://x.com/user/status/1234567890 saying thanks"
  • "Search X for recent posts about our product launch and list the top 10"
  • "Look up @example and tell me their bio"
  • "Show my last 20 mentions"
  • "Upload photo.jpg and post it with the caption ..."

Example commands the agent can run

These are the shortcut commands from the skill reference. Each returns JSON. Post IDs can be replaced with a full post URL, and usernames can omit the leading @.

xurl post "Hello world!" xurl search "QUERY" -n 10 xurl read POST_ID xurl user @handle xurl media upload path/to/file.mp4 xurl media status MEDIA_ID xurl post "Check this out" --media-id MEDIA_ID

Safety: credentials, scripts and network access

xurl runs scripts and uses the network. Every command is a real request to the X API, and write actions such as posting, deleting, following, blocking and sending DMs affect a live account and can be hard to undo.

The skill includes strict secret-handling rules. The agent must never read, print, summarize or upload ~/.xurl, and must never ask you to paste tokens into chat. Credentials are filled in by you on your own machine. The agent is also told not to use --verbose or -v, and not to use secret flags such as --bearer-token, --consumer-key, --consumer-secret, --access-token, --token-secret, --client-id or --client-secret.

Keep these practices in mind: review every write action, avoid this skill on shared or monitored machines, and remember that secret flags typed into agent sessions can leak through context, logs or shell history.

  • Do not paste keys or tokens into chat
  • Ask the agent to draft first, then approve before it posts or sends DMs
  • Use xurl auth status to check setup without exposing secrets

What people use it for

  • Drafting and publishing scheduled-style posts for a brand account after you approve the text
  • Searching X for a topic and summarizing the top results as JSON-backed lists
  • Checking mentions and replying to specific posts by URL
  • Looking up user profiles and managing follows, mutes or blocks on your own account
  • Uploading an image or video, checking its media status, and attaching it to a post

Frequently asked questions

Is the xurl skill free?

The source lists the skill and the xurl tool under an MIT licence. You still need your own X developer app and credentials to use it, and this guide does not state any pricing for X's API.

What do I need to use xurl?

You need the xurl CLI installed through Homebrew, npm, the shell script or Go, an X developer app with API credentials that you register yourself, and authentication through xurl auth oauth2. You also need network access to the X API.

How do I install the xurl skill in Claude?

Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

Why does the agent refuse to read my credentials?

The skill has mandatory secret-safety rules. It forbids the agent from reading or sending ~/.xurl and from asking you to paste tokens into chat, so you fill in credentials yourself on your machine.

Can the agent post without asking me first?

The skill lets the agent run write commands such as post and dm on your live account. To stay in control, ask it to draft the text and wait for your approval before it runs the command.

Is xurl an alternative to using the X API directly?

xurl is a command-line wrapper that handles authentication and returns JSON, and it can also call any X API v2 endpoint directly. This guide does not compare it with other tools, so check the X developer documentation and other options for your own needs.

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 xurl if you already use an X developer app and want an agent to draft, publish, search or monitor activity on your own account with JSON output. Skip it if you will not set up your own X credentials, or if you want an agent to write to a shared or monitored machine without reviewing each action.

Download the skill