Using APITube Agent Skills#

APITube Agent Skills are small, discoverable instruction files that teach an AI agent how to authenticate, query and parse the News API — without a human wiring it up first. APITube publishes them under /.well-known/, following the Agent Skills standard, so a supporting agent can find them automatically and then call the News API correctly. There are two published skills today: apitube-news-api, for calling the API directly over HTTP, and apitube-mcp, for connecting through the hosted MCP server.

You do not install or configure an Agent Skill yourself. It is a public instruction file the agent reads. Your only setup is having an API key ready for the agent to authenticate with — see where to find and create your API key.

What are Agent Skills?#

Agent Skills are short instruction files that describe how to use a service, written for an AI agent rather than a person. Because APITube serves them from a /.well-known/ path — a standard, predictable location — an agent that supports the Agent Skills discovery standard can fetch them on its own, with no manual setup. The skill tells the agent how to authenticate, which endpoints exist, which filters matter, and what the response looks like, so the agent builds valid requests instead of guessing.

This is the discovery-and-instruction layer. It does not run your queries; it points the agent at the right way to run them — either the raw HTTP API or the hosted MCP server described below.

Which skills does APITube publish?#

APITube publishes two Agent Skills, each aimed at a different way of reaching the News API:

• apitube-news-api — how to call the News API directly over HTTP: authentication, the endpoints, the key /news/everything filters, the JSON response shape, and rate limits. Use this skill when the agent should build and send API requests itself against the base URL https://api.apitube.io/v1.
• apitube-mcp — how to connect an assistant to the hosted MCP server at https://mcp.apitube.io/ and search news in natural language, with no code and no install. This skill maps onto the APITube MCP server, whose search_news search tool and suggest ID-lookup tool the agent then drives.

In short: pick apitube-news-api when the agent writes HTTP requests, and apitube-mcp when the agent talks to an assistant that speaks the Model Context Protocol. If you are configuring a client by hand instead, follow how to use APITube in Cursor, Claude and VS Code.

How does an agent discover the skills?#

Every published skill is listed in one discovery index, which follows the Agent Skills Discovery RFC (schema version 0.2.0):

https://docs.apitube.io/.well-known/agent-skills/index.json

The index is a plain JSON file the agent fetches first. Each entry gives the skill’s name, a type of skill-md, a one-line description, the url of the skill file, and a digest — a SHA-256 hash of the skill file’s raw bytes. You can read it with a single request:

curl https://docs.apitube.io/.well-known/agent-skills/index.json

A trimmed entry looks like this:

{
  "name": "apitube-mcp",
  "type": "skill-md",
  "description": "Connect an AI assistant to APITube News via the hosted MCP server...",
  "url": "/.well-known/agent-skills/apitube-mcp/SKILL.md",
  "digest": "sha256:b587a56b..."
}

The digest matters: it is computed from the exact bytes of the served file, so an agent can hash the SKILL.md it downloads and confirm the file was not altered in transit or swapped out. If the hash matches the index, the instructions are authentic. Entries are sorted by name, and every skill is required to carry a description, so the index is always complete and predictable.

What is inside each skill file?#

Each skill is a Markdown file at the url listed in the index. You can open either one in a browser or with curl:

https://docs.apitube.io/.well-known/agent-skills/apitube-news-api/SKILL.md
https://docs.apitube.io/.well-known/agent-skills/apitube-mcp/SKILL.md

The apitube-news-api skill documents the direct HTTP path: the base URL, the three ways to pass your API key, an endpoint table (/news/everything, /news/top-headlines, /news/article, taxonomy and /suggest endpoints, /balance), the most-used /news/everything parameters, a sample JSON response, and rate limits. It is enough for an agent to authenticate and run a filtered search end to end.

The apitube-mcp skill documents the hosted MCP path: the https://mcp.apitube.io/ endpoint, the search_news search tool and the suggest ID-lookup tool, ready-made prompt templates, and how to add the server to an MCP client. MCP clients can also read the server’s capabilities from its server card at https://docs.apitube.io/.well-known/mcp/server-card.json, which lists the tools and prompts the server exposes.

Common Questions#

• Do I need to install or configure anything?
• Which API key do Agent Skills use?
• How does an agent know a skill file hasn’t changed?
• Can I read the skills myself?

Do I need to install or configure anything?#

No. Agent Skills are public instruction files APITube hosts under /.well-known/, so there is nothing to install and nothing to set up in the skill itself. An agent that supports the Agent Skills discovery standard finds them automatically. The one thing you still provide is an API key, which the agent uses to authenticate its News API or MCP requests.

Which API key do Agent Skills use?#

The same normal APITube API key you use everywhere else. The skills describe how to authenticate — for example, passing the key in an Authorization: Bearer header — but they do not contain a key. Whether the agent takes the HTTP path (apitube-news-api) or the MCP path (apitube-mcp), it authenticates with your account key, so the usage draws on the same plan and quota as your direct requests.

How does an agent know a skill file hasn’t changed?#

The discovery index stores a sha256 digest of each skill file’s raw bytes. An agent can hash the SKILL.md it downloads and compare it to the digest in index.json. A match confirms the file is exactly what APITube published; a mismatch means the file was changed and should not be trusted. This is why the index is regenerated whenever a skill changes — the digest always reflects what is actually served.

Can I read the skills myself?#

Yes. Everything is public and human-readable. Open the discovery index at https://docs.apitube.io/.well-known/agent-skills/index.json to see both skills, then open either SKILL.md at the url listed there. The apitube-news-api skill is a compact HTTP quick-start, and the apitube-mcp skill is a compact MCP quick-start — useful references even if you are wiring things up by hand rather than through an agent. For the official reference, see the APITube Agent Skills documentation.