Building on Agent Skills

The JSON API

One endpoint serves search and browsing. Results are scored when q is present and sorted otherwise, and only indexable skills are returned — listings that cannot be traced to a live source never appear in API results.

GET https://agentskills.codes/api/v1/skills?q=pdf&limit=10

{
  "skills": [
    {
      "id": 191,
      "slug": "ui-ux-pro-max",
      "name": "ui-ux-pro-max",
      "author": "nextlevelbuilder",
      "description": "UI/UX design intelligence. 50 styles, 21 palettes…",
      "category": "Design",
      "installs": 0,
      "views": 0,
      "sourceUrl": "https://github.com/…"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Errors are JSON, always

Any failure under /api/ returns a stable envelope with a machine-readable code and a hint that says how to recover — never an HTML error page. Invalid parameters are rejected rather than silently ignored, so a bad request can't look like an empty result set.

GET https://agentskills.codes/api/v1/skills?sort=bogus    → 400

{
  "error": {
    "code": "INVALID_SORT",
    "message": "Unknown sort value 'bogus'.",
    "hint": "Use one of: popular, installs, views, name. Omit the parameter to sort by popular.",
    "docs": "https://agentskills.codes/openapi.json"
  }
}

Spec and machine-readable files

• /openapi.json — OpenAPI 3.1 description of the public API.
• /llms.txt — what this site is, the key pages, and how to use the data.
• /sitemap.xml — every canonical URL, including blog posts.
• /robots.txt — crawl rules and the sitemap location.

Markdown for agents

Skill pages and blog posts serve the same content as Markdown when a client asks for it, per RFC 9110 content negotiation. Selection is by the Accept header only — never by user agent — so browsers and search crawlers keep getting the unchanged HTML, and the Markdown variant is served noindex and no-store.

# Same URL, different representation
curl -H 'Accept: text/markdown' https://agentskills.codes/skills/pdf-to-markdown
curl -H 'Accept: text/markdown' https://agentskills.codes/blog/<slug>

# Explicit twin, for tools that cannot set headers
curl https://agentskills.codes/skills/pdf-to-markdown.md

Where negotiation is in play the HTML response carries Vary: Accept, so a shared cache can never hand a cached HTML body to an agent that asked for Markdown.

Conventions

• Dates are ISO 8601 (YYYY-MM-DD).
• Any page is also reachable as Markdown by appending .md to its URL.
• Reads are cacheable; listing responses carry s-maxage=60, stale-while-revalidate=300.
• There is no write API — the registry is curated from public sources, not user submissions.