/skill JSON endpoint

A dynamic API endpoint that returns structured JSON about your product's capabilities, audience and pricing.

What is the /skill endpoint?

While skill.md is a static file, the /skill endpoint is a live API route that returns structured JSON about your product. AI agents can query it programmatically to get up-to-date information without having to parse your HTML or markdown.

This is the dynamic counterpart to skill.md. It can return real-time data like current pricing, available features, API status, and supported integrations — things that change frequently and would be a hassle to keep updated in a static file.

Why does it matter?

Modern agents from OpenAI, Anthropic, and Perplexity are designed to interact with structured APIs, not just scrape pages. When an agent can call your /skill endpoint, it gets precise, current data — not a stale cache of your marketing page.

When a user asks what is the best tool for X, the AI can pull live data from your endpoint to give an accurate, current recommendation rather than relying on what was in its training set six months ago.

What should it return?

The endpoint should return a JSON response with a consistent structure describing your product. There is no official schema yet, but the de-facto convention looks like this:

{
  "name": "acme-crm",
  "description": "Lightweight CRM for small sales teams",
  "capabilities": [
    "Contact and deal management",
    "Pipeline visualization",
    "Email integration"
  ],
  "categories": ["CRM", "Sales", "Productivity"],
  "audience": ["Small businesses", "Startups"],
  "pricing": {
    "free_tier": true,
    "starting_price": "$12/user/month"
  },
  "urls": {
    "homepage": "https://acmecrm.com",
    "docs": "https://docs.acmecrm.com",
    "pricing": "https://acmecrm.com/pricing"
  }
}

How to implement

Next.js

// app/skill/route.ts
import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({
    name: "your-product",
    description: "What your product does",
    capabilities: ["Feature 1", "Feature 2"],
  });
}

Express

app.get("/skill", (req, res) => {
  res.json({
    name: "your-product",
    description: "What your product does",
    capabilities: ["Feature 1", "Feature 2"],
  });
});

Best practices

— Return Content-Type: application/json.
— Keep response times under 500ms. Agents time out on slow endpoints.
— Use consistent field names: name, description, capabilities, urls.
— Support CORS so browser-based agents can query it.
— Do not require authentication. /skill must be public.