Guide · Agent skill
How to use the xurl X API CLI agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The xurl skill teaches an AI agent how to use xurl, the official command-line tool for the X (formerly Twitter) API. Once it is installed, you can ask your agent to post, reply, search, read timelines and send direct messages, and the agent will run the matching xurl commands on your machine. This guide covers what the skill does, how to install it, how to trigger it, the setup it needs, and the safety limits you should know before you use it.
X API CLI (xurl)steipete/agent-scripts · MIT Download the skill Quick start
- 1Get the skill files. Download the xurl skill ZIP from this page and unzip it.
- 2Place the skill folder. Move the unzipped folder into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Install the xurl CLI. Install xurl with Homebrew, npm, the shell script or Go, then run xurl version to confirm.
- 4Create an X developer app. Register an app with OAuth 2.0 credentials yourself in the X developer portal, using http://localhost:8080/callback as the redirect URI. Keep secrets out of the agent chat.
- 5Log in with OAuth 2.0. Run xurl auth oauth2 on your own machine and complete the login, then run xurl auth status to check.
- 6Ask the agent for an action. Describe what you want in plain language, such as searching posts or replying to a post, and review what it does.
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. The xurl skill's SKILL.md explains how to use the xurl CLI for the X API.
With the skill, the agent can post, reply, quote, like, repost, bookmark, follow, read timelines and search, and send direct messages by running xurl commands on your machine. It also explains how to log in with OAuth and how to make raw requests to any X API endpoint.
- Post, reply, quote and delete posts
- Read posts, search, view your timeline and mentions
- Like, unlike, repost, unrepost, bookmark and unbookmark
- Follow, unfollow, and list following and followers
- Send and list direct messages
- Upload media and check its status
How do you install the xurl skill?
Download the ZIP for this skill from our page, then unzip it. For a personal setup, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.
The skill also expects the xurl CLI itself to be installed. The SKILL.md lists these install methods: Homebrew, npm, a shell script, and Go.
- Homebrew: brew install --cask xdevplatform/tap/xurl
- npm: npm install -g @xdevplatform/xurl
- Go: go install github.com/xdevplatform/xurl@latest
brew install --cask xdevplatform/tap/xurlWhat do you need before the agent can post for you?
You need an X developer app with OAuth 2.0 credentials. You must register this app yourself, on your machine, outside the agent session. The skill does not do registration for you.
In the X developer portal, the OAuth 2.0 redirect URI should be http://localhost:8080/callback. Once an app is registered, run the OAuth 2.0 login command. xurl stores app config and tokens in ~/.xurl.
xurl auth oauth2How do you check that xurl is working?
Run these quick checks in order. First confirm the CLI is installed, then check the auth state, then make a live request to confirm your account responds.
- Install check: xurl version
- Auth check: xurl auth status
- Live check: xurl whoami
xurl auth statusHow do you trigger the skill with natural requests?
You do not need to type xurl commands yourself. Describe the action in plain language and the agent will pick the matching command. Examples of requests that fit the skill include asking the agent to post a message, reply to a specific post, search for posts from a handle, or check your mentions.
If you have several X apps or accounts, you can ask the agent to use a particular one. The skill documents the --app and --username flags for this.
- Post "Launching our new docs today" to my X account
- Reply to post 1234567890 with "Thanks for the feedback"
- Search X for posts from @XDevelopers and show the 10 most recent
- Show my last 20 timeline posts
- Check my mentions from today
How do you use raw endpoint mode?
For X API calls that have no shortcut, the skill shows raw endpoint mode. You pass a path such as /2/users/me, choose a method with -X, send a JSON body with -d, and pick an auth type with --auth (oauth2, oauth1 or app).
Raw mode is useful for developers who already know the X API and want direct control over requests.
- GET: xurl /2/users/me
- POST JSON: xurl -X POST /2/tweets -d '{"text":"Hello world!"}'
- Choose auth: xurl --auth oauth2 /2/users/me
xurl -X POST /2/tweets -d '{"text":"Hello world!"}'What people use it for
- Drafting and publishing scheduled-style posts on your own X account from a single request
- Checking mentions and replying to specific posts without opening the X website
- Searching posts from a handle and summarising the results for a research note
- Managing bookmarks and likes for a personal reading list
- Sending direct messages or uploading a video file to a post you are preparing
Frequently asked questions
How do I install the xurl skill?
Download the skill 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. You also need the xurl CLI, which the SKILL.md says can be installed with Homebrew, npm, a shell script or Go.
What are the requirements for the xurl skill?
You need the xurl CLI installed, an X developer app with OAuth 2.0 credentials that you register yourself, and network access to the X API. xurl stores its app config and tokens in a local ~/.xurl file.
Is the xurl skill free to use?
The source material does not state pricing or licence terms for X API access. The skill itself is listed under the MIT licence. Check the X developer platform for its current access terms before you build on it.
Does the agent need my passwords or API secrets?
No. The skill tells the agent never to ask for client secrets, bearer tokens or OAuth tokens in chat. You register the app and log in on your own machine outside the agent session.
Why does xurl need an OAuth login?
Actions such as posting, liking or sending messages act on your account, so xurl uses OAuth 2.0 to authorise access. You run xurl auth oauth2 once to log in, and xurl auth status shows whether you are signed in.
What should I do if xurl commands fail?
Start with the quick checks: run xurl version to confirm the install, xurl auth status to confirm login, and xurl whoami for a live request. Make sure the redirect URI in the developer portal is http://localhost:8080/callback. Do not use --verbose in agent runs, since the skill warns it can expose auth headers.
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
Use the xurl skill if you already have an X developer app and want an agent to run routine actions on your own account from the command line. Skip it if you cannot register app credentials yourself, or if you plan to use it on accounts you do not control, since the agent can publish, delete and message on your behalf.
Download the skill