Agent Skills index

What is the Agent Skills index (/.well-known/agent-skills/index.json)?

The Agent Skills index is a structured JSON manifest that enumerates the discrete, stateless capabilities your site exposes to AI agents. Published at /.well-known/agent-skills/index.json, it describes what jobs an agent can ask your service to perform—search a catalog, convert a file, validate an address—without forcing the agent to parse a full OpenAPI spec or negotiate a persistent MCP session. Think of it as a curated, human-and-machine-readable menu of "things you can do here," designed to sit between a raw API schema and a full protocol handshake.

The specification lives at agent-skills.org and defines a straightforward schema: a version string, provider metadata, a last-updated timestamp, and an array of skills. Each skill includes a name, description, HTTP endpoint, method, authentication requirements, input and output schemas (JSON Schema dialect), and optionally a rate limit. The design philosophy is explicit: use Agent Skills for stateless function calls the agent can chain together; use the Model Context Protocol when you need richer, session-aware interactions like streaming or multi-turn state.

Why does the Agent Skills index matter for AI agents and agentic workflows?

When ChatGPT, Claude, or a coding assistant like Cursor encounters your site, it has three ways to figure out what it can do: scrape and guess, parse a 5,000-line OpenAPI spec, or read a purpose-built index. Agent Skills solves the cold-start problem. An agent can fetch /.well-known/agent-skills/index.json, find "convert_markdown_to_pdf" or "validate_shipping_address," inspect the input schema, and execute the call—all without human handholding or brittle prompt engineering. This matters most for agentic commerce flows (checkout, booking, subscription changes) and citation workflows where the agent needs to do something on behalf of the user, not just retrieve a web page.

The business outcome is higher agent install rates and fewer failed automations. If your competitor publishes an Agent Skills index and you don't, Claude will route a user's "order me a pizza" request to the service that tells it how to place an order. You also reduce false positives from Web Application Firewalls: agents hitting documented, schema-validated endpoints with correct payloads look less like scrapers and more like legitimate API clients. In early 2025, we're seeing observability platforms and SaaS tools adopt Agent Skills to let agents invoke webhooks, trigger reports, and modify configurations without forcing users to copy-paste API keys into a chat window.

Is publishing an Agent Skills index required, recommended, or optional?

This check is optional for most sites. If you're purely informational—a blog, marketing site, or documentation portal—Agent Skills adds little value; agents can already read your pages via HTML or llms.txt. The calculus changes if you expose transactional capabilities (payments, reservations, data mutations) or specialized utilities (image resizing, syntax validation, unit conversion) that agents might chain into workflows. In those cases, publishing an Agent Skills index becomes a competitive differentiator: you're signaling "we're ready to be a node in an agent's execution graph."

What the Agent Skills specification says

The Agent Skills specification defines a JSON object with the following structure:

• version (required): Semantic version of the schema, currently "1.0".
• provider (required): An object with name and optionally url and contact.
• updated (required): ISO 8601 timestamp of the last index update.
• skills (required): An array of skill objects, each containing:
  • name (required): Machine-readable identifier (e.g., convert_currency).
  • description (required): Human-readable sentence explaining what it does.
  • endpoint (required): Full URL or path.
  • method (required): HTTP verb (GET, POST, etc.).
  • auth (required): Authentication scheme (none, apikey, oauth2, bearer).
  • input_schema (required): JSON Schema describing the request payload or query parameters.
  • output_schema (required): JSON Schema describing the response.
  • rate_limit (optional): Object with requests, period (e.g., { "requests": 100, "period": "minute" }).

The spec was proposed by the Agent Skills Working Group (an informal coalition including API platform vendors and AI research labs) in Q4 2024; it is not yet an IETF or W3C standard but has adoption momentum among agent tooling providers.

{
  "version": "1.0",
  "provider": {
    "name": "Acme API",
    "url": "https://api.acme.com"
  },
  "updated": "2025-01-15T10:00:00Z",
  "skills": [
    {
      "name": "validate_email",
      "description": "Check if an email address is deliverable",
      "endpoint": "/v1/validate/email",
      "method": "POST",
      "auth": "apikey",
      "input_schema": {
        "type": "object",
        "properties": {
          "email": { "type": "string", "format": "email" }
        },
        "required": ["email"]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "valid": { "type": "boolean" },
          "reason": { "type": "string" }
        }
      },
      "rate_limit": { "requests": 1000, "period": "hour" }
    }
  ]
}

What a good Agent Skills index looks like

Companies like Stripe, Twilio, and workflow automation platforms are early exemplars, though Agent Skills adoption is still nascent (Q1 2025). A strong index balances completeness with focus: include only skills an agent can execute without multi-step human verification.

Example: A hypothetical deployment for a geocoding service might look like this:

{
  "version": "1.0",
  "provider": { "name": "GeoAPI", "url": "https://geoapi.example" },
  "updated": "2025-02-10T14:22:00Z",
  "skills": [
    {
      "name": "geocode_address",
      "description": "Convert a street address to latitude/longitude",
      "endpoint": "/geocode",
      "method": "GET",
      "auth": "none",
      "input_schema": {
        "type": "object",
        "properties": {
          "address": { "type": "string" }
        },
        "required": ["address"]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "lat": { "type": "number" },
          "lng": { "type": "number" }
        }
      }
    }
  ]
}

Look for clear naming (geocode_address, not doGeocode), realistic rate limits, and schemas tight enough that an agent won't hallucinate required fields.

How do I add an Agent Skills index to my site or SaaS platform?

1. Audit your API surface. List stateless endpoints agents might chain (validation, conversion, lookup). Exclude anything requiring OAuth dance or persistent sessions—those belong in MCP.

2. Draft the JSON. Start with the minimal example above; add one skill per discrete capability. Use JSON Schema Draft 7 or later for input/output.

3. Serve it at /.well-known/agent-skills/index.json. In Next.js, create public/.well-known/agent-skills/index.json. On Cloudflare Workers:

   export default {
     async fetch(request, env) {
       const url = new URL(request.url);
       if (url.pathname === '/.well-known/agent-skills/index.json') {
         return new Response(JSON.stringify({
           version: "1.0",
           provider: { name: "My API" },
           updated: new Date().toISOString(),
           skills: [/* your skills */]
         }), { headers: { 'Content-Type': 'application/json' } });
       }
       // ... rest of your worker
     }
   };
   

4. Set cache headers. Cache-Control: public, max-age=3600 is reasonable; agents will refetch hourly.

5. Version your index. Bump updated when you add or change skills. Agents may cache based on that timestamp.

How can I test my Agent Skills index implementation?

curl -i https://yoursite.com/.well-known/agent-skills/index.json

You should see 200 OK, Content-Type: application/json, and valid JSON matching the schema. Or just run a free scan and we'll check this for you alongside 30+ other agent-readiness signals.

Frequently asked questions

Do I need both an Agent Skills index and the Model Context Protocol (MCP)?

No. Use the Agent Skills index for stateless, one-shot function calls like currency conversion or address validation. Use MCP when you need persistent sessions, streaming data, or multi-turn state. Many sites will only need one; API-heavy platforms might expose both to cover different agent interaction patterns.

Will publishing /.well-known/agent-skills/index.json expose my internal API keys or credentials?

No. The Agent Skills index describes how agents authenticate (via the auth field: none, apikey, oauth2, bearer) but never includes actual keys or tokens. Agents must obtain credentials through your normal OAuth flow, registration portal, or user-provided API keys—just like any other API client.

Can e-commerce sites use the Agent Skills index to let agents complete purchases?

Yes. Expose skills like add_to_cart, apply_coupon, or checkout with clear input schemas (product ID, quantity, payment token). Ensure your auth field requires strong authentication and rate-limit sensitive endpoints. Agents can then chain these skills to execute transactional flows on behalf of authenticated users.

How does the Agent Skills index compare to OpenAPI/Swagger for agent discovery?

Agent Skills is a curated, agent-first subset. OpenAPI specs often include hundreds of endpoints with internal admin routes, legacy versions, and verbose schemas. The Agent Skills index highlights only the stateless, agent-safe functions you want LLMs to call, reducing token overhead and improving agent success rates during cold-start discovery.

Is the Agent Skills specification an official IETF or W3C standard?

Not yet. The spec was proposed by the Agent Skills Working Group in Q4 2024 and has momentum among agent tooling providers and API platforms. It is not an IETF RFC or W3C Recommendation as of Q1 2025, but early adopters are treating it as a de facto standard for agentic capability discovery.

Can I deploy an Agent Skills index on a Next.js or Vercel site?

Yes. Create a route at app/.well-known/agent-skills/index.json/route.ts (App Router) or pages/.well-known/agent-skills/index.json.ts (Pages Router) that returns your JSON with Content-Type: application/json. On Vercel, ensure .well-known paths aren't blocked by middleware. Test with curl https://yourdomain/.well-known/agent-skills/index.json.

Should SaaS developer documentation sites publish an Agent Skills index?

Yes, if your platform exposes webhooks, report generation, or configuration APIs that agents might invoke. For example, an observability SaaS could list skills like create_alert, query_metrics, or trigger_report. This lets agents automate workflows ("show me last week's error spike") without forcing users to write custom scripts.

What JSON Schema dialect should I use for input_schema and output_schema in the Agent Skills index?

The specification recommends JSON Schema Draft 2020-12 or later. Use standard keywords like type, properties, required, format, and enum. Keep schemas concise: agents parse them during discovery, so verbose definitions increase latency. Reference the JSON Schema documentation for dialect details and validator tooling.