SKILL.md explained: the Agent Skills format, X's own skill, and a Twitter (X) API skill you can install

The specification is short, and worth reading in the original at agentskills.io/specification. A skill is a directory that contains, at minimum, a SKILL.md file. The file is YAML frontmatter followed by Markdown. The directory may also hold scripts/ (code the agent can run), references/ (documents the agent reads on demand) and assets/ (templates, images, data files), plus anything else you like.

The body has no required structure. The spec recommends step-by-step instructions, examples of inputs and outputs, and common edge cases, and warns that the agent loads the entire file once it decides to activate the skill, so long material belongs in references/ files linked by relative path, one level deep.

Progressive disclosure is why skills scale. The spec describes three stages. At startup the agent loads only name and description of every installed skill, about 100 tokens each. When a task matches a description, it loads the full body, which the spec recommends keeping under 5,000 tokens and under 500 lines. Files in scripts/, references/ and assets/ are read only when the body sends the agent there. A machine can therefore keep fifty skills installed for the price of a short paragraph of context, and pay for a skill only when it uses it.

Who reads the format. The agentskills.io home page lists the clients that support it; the list includes Claude Code, Claude, ChatGPT and Codex, Cursor, Gemini CLI, GitHub Copilot, VS Code, OpenCode, OpenHands, Goose, Amp, Letta, Roo Code, Kiro, Factory, JetBrains Junie, Hermes Agent and OpenClaw. The standard was developed by Anthropic, released openly, and takes contributions on GitHub under agentskills/agentskills, which also hosts skills-ref, a reference validator: skills-ref validate ./my-skill checks the frontmatter and the naming rules.

Not to be confused with. AGENTS.md and CLAUDE.md are always-on project instructions, loaded every session; a SKILL.md is loaded on demand. llms.txt is an index of documentation for crawlers and agents, not instructions. An MCP server exposes tools over a protocol; a skill is plain text that may tell the agent to call such tools, or to run curl. The skills.md and skillsmd.dev sites you will see in the search results are registries and explainers built around the same file format.

Each agent reads skills from its own directory; the skills CLI published by vercel-labs on GitHub knows the paths and copies a skill into them. Its README documents these locations for the four agents most readers of this page use (it supports many more).

What npx skills add accepts. Per the README: GitHub shorthand (owner/repo), a full GitHub, GitLab or Azure Repos URL, a URL to a sub-folder of a repository (.../tree/main/skills/<name>), a git SSH URL, a local path, and a direct download URL that points at a single valid SKILL.md file or at a .zip, .tar, .tar.gz or .tgz archive. Inside a repository it looks for SKILL.md files in the root, in skills/ and in agent-specific folders. -g installs globally instead of into the current project, -y skips the prompts, -a <agent> targets one agent, -s <skill> picks one skill from a repository with several, and npx skills find <query> searches a public index.

Claude Code specifics. The Claude Code documentation (code.claude.com/docs/en/skills) adds that the directory name becomes a slash command (~/.claude/skills/deploy/ gives /deploy), that Claude also invokes a skill automatically when a request matches its description, and that disable-model-invocation: true turns the automatic part off. Claude Code extends the standard with fields such as context: fork, agent, paths, argument-hint and dynamic shell injection; the docs state that only name, description, license, compatibility, metadata and allowed-tools travel to other products, so a skill meant to be portable should stay inside those six.

Manual install is a copy. A skill is files, so mkdir plus curl -o into the right directory is a complete installation; nothing registers it. Deleting the directory uninstalls it. The commands below show both routes for the twitterapi.io skill published on this page.

X added a skill.md page to its developer documentation under Agent Resources, next to llms.txt and its MCP server. The page describes the file as "a structured capability summary that describes what AI agents can do with the X API", following the agentskills.io specification, and gives one install command: npx skills add https://docs.x.com. The CLI finds the file through X's discovery endpoint, docs.x.com/.well-known/agent-skills/index.json, which lists a single skill named x with the file at /.well-known/agent-skills/x/skill.md and a SHA-256 digest. The same text is served at docs.x.com/skill.md. We fetched it this session: 235 lines, 9,926 bytes, roughly 2,482 tokens once an agent loads it, comfortably inside the spec's 5,000-token recommendation.

Frontmatter. name: x; a description that starts "Use when building integrations with X (formerly Twitter), accessing posts, users, trends, and real-time data; managing authentication and API requests; handling pagination and rate limits; or troubleshooting API errors and response codes"; and metadata with mintlify-proj: x and version: "1.0". No license, compatibility or allowed-tools.

Body. Nine sections: Product Summary, When to Use, Quick Reference, Decision Guidance, Workflow, Common Gotchas, Verification Checklist and Resources. The Quick Reference is where the substance is: an authentication table (bearer token for app-only public reads, OAuth 1.0a user context, OAuth 2.0 authorization code with scopes, Basic auth for Enterprise), eleven endpoints (GET /2/users/by/username/{username}, GET /2/users/{id}, GET /2/tweets/search/recent, GET /2/tweets/{id}, GET /2/users/{id}/tweets, POST /2/tweets, DELETE /2/tweets/{id}, POST /2/users/{id}/likes, POST /2/users/{id}/following, GET /2/tweets/search/stream, POST /2/tweets/search/stream/rules), the tweet.fields and expansions parameters, max_results plus pagination_token with meta.next_token, and the three x-rate-limit-* headers.

What it tells the agent to do. Create an app at console.x.com, accept the developer agreement, store the bearer token or OAuth credentials in environment variables, always add fields and expansions (the file's first gotcha is that posts come back with only id and text by default), stop paginating when next_token is absent, parse the errors array rather than a single error, back off on 429 using x-rate-limit-reset, reconnect streams, and URL-encode spaces as %20.

What it does not contain. Prices. The Product Summary says only that "the API uses pay-per-usage pricing with no commitments"; the numbers live on docs.x.com/x-api/getting-started/pricing: $0.005 per post read, $0.010 per user read, $0.010 per follower or following read, $0.015 per post created ($0.200 with a URL), capped at 3 million post reads per monthly billing cycle with Enterprise above that. An agent following X's skill will not know that a 100-post search page costs $0.50 unless you tell it, which is one of the reasons the twitterapi.io skill below puts its prices in the body.

Below is the complete file we publish at twitterapi.io/skills/twitterapi-io/SKILL.md (177 lines, 8,948 bytes, about 2,237 tokens). It follows the specification literally: name equals the folder name twitterapi-io, the description says both what and when, and the only optional fields used are the four that travel to every client (license, compatibility, metadata). Everything an agent needs to make a correct, cheap call is in the body; there is no references/ folder yet, because the body stays under half the spec's line budget.

Design choices, and why. The description names the concrete tasks (profile, recent posts, search, mentions, followers, posts by ID) so that an agent's matcher fires on the words a user would use. The cost section comes before the endpoint table because an agent that loops over pages should know the price of a page before it starts; the spec's own description advice ("include specific keywords") applies to cost too. The six reads are a table of path, required parameters and where the items sit in the response, because that last column is where generic LLM knowledge fails: last_tweets nests under data.tweets, search and mentions return a top-level tweets, followers return followers with snake_case fields. The error section leads with the shape that bites: HTTP 200 with status: "error" and a msg. And the trimming section exists because of the numbers in the next part of this page.

On writes. The file mentions the write actions only in a final section that starts "only on explicit request", and carries the caveats verbatim: writes run through a logged-in session (/twitter/user_login_v2, $0.10, with a proxy you supply), each action is $0.002, every action acts as that X account, which X can rate-limit, lock or suspend, and calls are billed per HTTP 200 response. An agent that reads only the first screen of the skill will never see a write path, which is the right default.

Both files are valid Agent Skills and both are small enough to load whole. They differ in what the agent must have before the first call, in how much the agent is told, and in what each read costs. Prices are from the X API pay-per-usage page on docs.x.com and from twitterapi.io/pricing.

Neither file replaces the other. If your agent must act as a specific X account with X's own guarantees, or needs the filtered stream, X's skill is the one to install and the OAuth table in it is accurate. If your agent needs to read public X data at scale, from any account, without an app review and at a price it can be told in advance, the twitterapi.io skill is the shorter path. Many setups will have both installed; the descriptions do not overlap enough to confuse a matcher, because X's starts with "building integrations with X" and ours with "read public X (Twitter) data through the twitterapi.io REST API with a plain API key".

A skill is cheap to hold (2,237 tokens when active) but what it causes the agent to fetch is not. We ran each of the six reads against 10 organization accounts (@vercel, @github, @Docker, @CloudflareDev, @OpenAIDevs, @nvidia, @NASA, @stripe, @supabase, @AnthropicAI) through a rate-limited client: one profile, two timeline pages, one mentions page, one from:<account> search page, one followers page and one /twitter/tweets batch of the 20 IDs from the first timeline page, 70 calls in all, zero errors. For every response we recorded the compact-JSON size in bytes, divided by four as the usual token approximation, then applied the trimming rule from the skill (9 tweet fields, 9 profile fields, 5 follower fields) and measured again.

A page of posts is a chapter of a book. The median 20-post timeline page was 128,177 bytes, about 32,044 tokens, and the largest single response in the run (245,639 bytes, a /twitter/tweets batch) was about 61,410 tokens. Across the 1,000 tweets the run returned, the average tweet object was 6,261 bytes raw, about 1,565 tokens, because every tweet carries its full author profile, entities, media objects and any quoted or reposted tweet in full. Trimmed to the skill's nine fields the same tweet is 448 bytes, about 112 tokens.

Trimming removed 90.1% of the bytes. The whole run was 7,441,992 bytes raw (1,860,498 tokens) and 737,285 bytes trimmed (184,321 tokens). The reduction is largest where the author object repeats most, posts by ID (94.2%) and timelines (93.4%), and smallest for profiles (74.5%) and follower rows (75.5%), which are already flat. Mentions trimmed less than timelines (87.6%) because mentions from smaller accounts carry smaller author objects and fewer media attachments to begin with.

One account, the whole skill, once. An agent that runs all six reads for a single account (seven calls, with two timeline pages) ingests about 685,559 bytes raw, roughly 171,390 tokens, which is more than many models' entire context window, for what is a modest question. With the trimming rule it is about 18,030 tokens. That difference, not the API price, is the main reason the skill tells the agent to fetch one page, trim it, and only then decide whether to fetch another.

Latency. Median wall-clock across all 70 calls was 2,238 ms, measured from the moment the client's rate-limit lock released to the parsed body, so it excludes our own pacing. Profiles were fastest (1,108 ms), the 20-ID batch slowest (3,417 ms). For an agent this means a six-read session (seven calls) takes about 16 seconds of API time at the medians; an agent that paginates deep into followers will spend most of its time waiting, so the skill tells it to estimate before looping.

Credits are known exactly from the published prices: tweet endpoints bill 15 credits per tweet returned with a 15-credit minimum per request, profiles 18 credits, follower pages 1 to 3 credits per row depending on the page tier, and $1 buys 100,000 credits. For the official X API we priced the same items at the pay-per-usage rate card on docs.x.com: $0.005 per post read, $0.010 per user read, $0.010 per follower read. Both columns price the items each call actually returned; neither includes a subscription.

Followers decide the bill on the X side. Of the $25.10 the study would have cost at the X rate card, $20.00 is the 2,000 follower rows at $0.010 each; the 1,000 posts are $5.00 and the ten profiles $0.10. On twitterapi.io the order flips: a follower row is 1 to 3 credits and a tweet is 15, so an agent's cost profile inverts: here, a deep follower crawl is the smaller item and a deep timeline crawl is what to estimate first. For 1,000 posts the two rate cards are $5.00 and $0.15, about 33x apart.

The per-request minimum matters for agents. An agent that searches for something rare and gets zero results still pays 15 credits ($0.00015) on twitterapi.io, and a 1-post result costs the same 15 credits as the minimum. That floor is why the skill tells the agent to make searches specific (from:, lang:, -filter:replies) rather than issuing many near-empty probes; at 20 results a page the floor is irrelevant, at 0 or 1 it is the whole bill. Subscription plans with bonus credits are listed on the pricing page; the per-item prices above are what the skill quotes to the agent.

Make name equal the folder, and keep it boring. The validator rejects uppercase, leading or double hyphens and a name that differs from the directory. twitterapi-io installs the same way on every client; a clever name does not.

Write the description for the matcher, not for a human. Agents decide whether to load your skill from this one field, with about 100 tokens of budget. List the concrete tasks a user would phrase (profile, recent posts, search, followers) and the distinguishing condition (API key, no OAuth). The spec's own good example does exactly this for PDFs.

Put the response shape in the body, not a link to it. The field names and the nesting (data.tweets versus tweets versus followers) are what an agent cannot guess, and the body is loaded whole, so this is the surest place to prevent a wrong call. Save references/ for long material such as a full search-operator list.

Put prices and rate limits in the body too. X's skill omits them and defers to a docs page the agent may never fetch. Ours quotes 15 credits per tweet, the 15-credit minimum, 18 per profile and the request-rate tiers, and asks the agent to estimate before fetching more than 10 pages. Measured, the six reads for one account are $0.0172 to $0.0212; a skill that says so lets the agent tell the user before spending.

Prescribe a trimming rule. This is the lesson of the numbers: a 20-post page is about 32,044 tokens raw and about 2,181 trimmed. Without an instruction, an agent will paste the raw JSON into its context and run out of room after a few pages. Name the fields to keep and say "fetch one page, trim, then decide".

Lead with the error shape that is not an HTTP error. A 200 with status: "error" and msg: "user not found" is the case agents mishandle most; put it first, with the data: null consequence.

Keep writes behind an explicit request. If the API can act as a user account, say so late in the file, state the price and the account risk plainly, and make the default path read-only in the agent's behavior without claiming the API is. The spec has no field for this; the ordering of your sections is the mechanism.

Version in metadata, validate, then publish at a stable URL. metadata.version lets an agent or a human see which revision is installed; skills-ref validate catches frontmatter mistakes; a stable HTTPS URL to the single file is enough for npx skills add and for curl. If you want the file discoverable the way X's is, add a .well-known/agent-skills/index.json that lists it with a digest, per the discovery schema at schemas.agentskills.io.

Question: what does an agent that follows the twitterapi.io SKILL.md pay per call, in context (bytes and approximate tokens as returned and after the skill's trimming rule), in wall-clock, and in credits at the twitterapi.io rate card, and what would the same items cost at the official X API pay-per-usage rate card.

Accounts and calls: 10 public organization accounts, @vercel, @github, @Docker, @CloudflareDev, @OpenAIDevs, @nvidia, @NASA, @stripe, @supabase, @AnthropicAI. For each: /twitter/user/info, two pages of /twitter/user/last_tweets (default, replies excluded), one page of /twitter/user/mentions, one page of /twitter/tweet/advanced_search with query=from:<account> and queryType=Latest, one page of /twitter/user/followers, and one /twitter/tweets call with the 20 IDs from the first timeline page. 70 requests, 1,000 tweets, 2,000 follower rows, 10 profiles, collected in 2026 through a rate-limited client; 0 errors.

Measurement: size is the UTF-8 length of the response serialized as compact JSON; tokens are bytes divided by four, the common rule of thumb, which understates real tokenizer counts for JSON by a margin that varies by model, so treat the token figures as relative, not exact. Trimmed size applies the exact field lists in the skill (tweets: id, createdAt, text, url, author.userName, likeCount, retweetCount, replyCount, viewCount; profiles: nine fields; follower rows: five). Wall-clock runs from the release of the client's rate-limit lock to the parsed body. Credits follow the published prices; follower pages are shown as the 1-to-3-credit range because the tier is per page. X API prices are the pay-per-usage rate card on docs.x.com applied to the same item counts.

What the sample cannot show: medians over 10 large organization accounts; small accounts with short descriptions and no media would produce smaller raw pages and lower trim ratios. Latency was measured from one location on one day and will vary. We did not measure token counts with a real tokenizer, and we did not run the skill inside an agent harness to count the tokens the agent spent reasoning over the data; the figures are what the agent would ingest, not what it would do with it. The npx skills add direct-URL install was taken from the CLI's README and is not verified end to end until the file is live at the published URL.

Privacy: aggregates only. Profiles, timelines, from: searches and ID batches belong to the named organization accounts and are kept compressed with the study. Mentions and follower pages contain private individuals; those pages were kept only long enough to measure size and timing and were not stored with the study, and no text, handle or ID from them appears on this page.