# Skilly

Skilly is a public directory of agent skills.

## Search for agents

The public JSON search endpoint is intended for AI agents and integrations:

GET https://skilly.sh/api/v1/skills/search

Rate limits: 60 API search requests per minute, 60 server-rendered directory searches per minute, and 120 other public API reads per minute per Cloudflare location. Auth requests are limited to 10/minute, writes to 10/minute, and catalog ingestion to 5/minute. On HTTP 429, wait for the `Retry-After` seconds before retrying. Rate limits are location-local and intended for abuse prevention, not exact global quotas.

No bearer token is required. A request must include `q` or at least one field-specific parameter. URL-encode spaces, slashes, and other reserved characters.

`q` is broad search across the skill name, YAML frontmatter description, category, source repository, and full `SKILL.md` instructions. It must be at least 2 characters when provided. Multiple unquoted words in `q` use AND matching: every word must occur in at least one indexed field. Wrap words in double quotes to require an exact contiguous phrase, such as `q=%22Use%20when%20the%20user%22`. Field-specific parameters are also combined with AND.

Supported query parameters:

- `name` — skill name
- `description` — YAML frontmatter description
- `category` — catalog category
- `source` — source repository
- `instructions` — full SKILL.md instructions
- `owner` — GitHub owner filter
- `limit` — maximum results, default 50, maximum 200
- `format` — response format: `json` (default) or `text` for a plain-text result list

Examples:

https://skilly.sh/api/v1/skills/search?q=database%20migration&limit=10
https://skilly.sh/api/v1/skills/search?name=frontend&category=Development&owner=vercel-labs

Search requires no authentication and returns JSON by default. Each result includes its name, description, category, source repository, install URL, and canonical URL.

For AI agents and other clients that need text only, add the HTTP query parameter `format=text` to the search URL. The response has `Content-Type: text/plain` and lists each matching skill with its name, description, category, source, install URL, and canonical URL. `format=json` is the default; unsupported formats return a `400` error.

Example:

https://skilly.sh/api/v1/skills/search?q=database%20migration&limit=10&format=text

For the human-facing directory, query state is shareable in the URL:

https://skilly.sh/?q=typography&category=Design&sort=relevance&page=1#directory

Directory parameters are `q`, `category`, `publisher`, `sort` (`relevance` or `name`), and one-based `page`. The directory's `page` parameter is separate from the public leaderboard endpoint's zero-based pagination.

## Documentation and machine-readable contracts

- Search guide: https://skilly.sh/docs/search
- Create a skill: https://skilly.sh/docs/create
- API reference: https://skilly.sh/docs/api
- OpenAPI: https://skilly.sh/api/openapi.json