# Agent Skills OS API

A small public REST API over the skill library. Search for a skill, read its full instructions, or ask in plain language which one fits. No key, no sign-up, JSON in and out. The machine-readable description is [/openapi.json](https://skills.rakibulism.space/openapi.json) (OpenAPI 3.1).

## Overview

| Operation | Request | Returns |
| --- | --- | --- |
| `listSkills` | `GET /api/skills?q=&limit=` | Skills matching the query, best first (or all of them) |
| `getSkill` | `GET /api/skills/{name}` | One skill with its full SKILL.md and usage snippets |
| `askSkills` | `POST /api/ask` | A short answer plus cards for the skills it means |

- **Base URL:** `https://skills.rakibulism.space`
- **Authentication:** none. The read endpoints allow cross-origin requests (`Access-Control-Allow-Origin: *`).
- **Format:** JSON with UTF-8. Every error is JSON too (see [Errors](#errors)).
- **Limits:** `POST /api/ask` allows about 12 questions a minute per client. The read endpoints are cached for a few minutes and have no fixed limit.

## When to use it

- An agent needs instructions for a task (a UI review, an accessibility audit) and wants to check whether a ready-made skill exists: call `listSkills` with a few keywords.
- A tool wants to load a skill at runtime without installing the npm package: call `getSkill` and use the `markdown` field as the system prompt.
- A user asks a fuzzy question ("how do I use this with LangChain?"): call `askSkills` and show its answer and cards.

If you write JavaScript or TypeScript and can install a package, the [npm package](https://skills.rakibulism.space/docs) is faster and works offline. For shell scripts, use the [CLI](https://skills.rakibulism.space/docs/cli).

## Search or list skills

`GET /api/skills` returns every skill sorted by name. Add `q` to keep only skills whose name, description, tags or text contain every word, best match first.

```sh
curl "https://skills.rakibulism.space/api/skills?q=ui&limit=5"
```

```json
{
  "query": "ui",
  "total": 1,
  "count": 1,
  "skills": [
    {
      "name": "super-ui",
      "title": "super-ui",
      "description": "…",
      "version": "0.1.0",
      "tags": ["design", "ui"],
      "url": "https://skills.rakibulism.space/skills/super-ui",
      "markdownUrl": "https://skills.rakibulism.space/skills/super-ui.md",
      "apiUrl": "https://skills.rakibulism.space/api/skills/super-ui"
    }
  ]
}
```

| Parameter | Type | Meaning |
| --- | --- | --- |
| `q` | string, up to 200 characters | Keywords for the task. Optional. |
| `limit` | integer, 1 to 100 | Most skills to return. Defaults to 100. |

## Get one skill

`GET /api/skills/{name}` returns the same fields plus `markdown` (the whole SKILL.md), `usage` snippets and `sourceUrl`.

```sh
curl https://skills.rakibulism.space/api/skills/super-ui
```

Only need the file? Request [/skills/super-ui.md](https://skills.rakibulism.space/skills/super-ui.md) directly, or send `Accept: text/markdown` to the skill page.

## Ask a question

`POST /api/ask` with a JSON body. The answer is grounded in the skills search ranks highest, and cards point at skills, install commands or usage snippets the site can render.

```sh
curl -X POST https://skills.rakibulism.space/api/ask \
  -H "Content-Type: application/json" \
  -d '{"question": "Which skill reviews UI?"}'
```

```json
{
  "answer": "super-ui is the closest skill …",
  "cards": [{ "type": "skill", "slug": "super-ui" }],
  "followups": ["How do I use it with LangChain?"]
}
```

## Errors

Errors use normal HTTP status codes and always return the same JSON shape, so an agent can read what went wrong and what to do next.

```json
{
  "error": "There is no skill named \"nope\".",
  "code": "skill_not_found",
  "hint": "GET /api/skills?q=<keywords> to find the right name.",
  "docs": "https://skills.rakibulism.space/docs/api"
}
```

| Status | code | What to do |
| --- | --- | --- |
| 400 | `invalid_name`, `invalid_limit`, `query_too_long`, `missing_question` | Fix the request as the hint says. |
| 404 | `skill_not_found`, `not_found` | Search with `listSkills`, or check the path against `/openapi.json`. |
| 405 | `method_not_allowed` | Use the method in the `Allow` header. |
| 429 | `rate_limited`, `ai_busy` | Wait for `Retry-After` seconds, or use `listSkills`. |
| 502, 503, 504 | `ai_unavailable`, `empty_answer`, `index_unavailable`, `skill_file_unavailable`, `not_configured`, `ai_timeout` | Try again shortly. |

## Markdown for agents

Every page on this site has a Markdown version. Send `Accept: text/markdown` to any page URL and you get Markdown with `Content-Type: text/markdown` and `Vary: Accept`; browsers keep getting HTML. You can also add `.md` to a path, for example [/docs.md](https://skills.rakibulism.space/docs.md), or use [/index.md](https://skills.rakibulism.space/index.md) for the home page.

```sh
curl -H "Accept: text/markdown" https://skills.rakibulism.space/
```

Start from [/llms.txt](https://skills.rakibulism.space/llms.txt) for a map of the site written for language models, and [/sitemap.xml](https://skills.rakibulism.space/sitemap.xml) for every page.

---

Page: https://skills.rakibulism.space/docs/api · Site guide for agents: https://skills.rakibulism.space/llms.txt
