Search the catalog
with query parameters.
Use a shareable browser URL for people, or call the public JSON endpoint when an agent needs to discover skills programmatically.
Two URLs, two useful workflows.
/api/v1/skills/search and receive JSON skill summaries. Human directoryUse /?q=... to share a browser search with filters and pagination.The API is the stable integration surface for agents. A search request must include q or at least one field-specific parameter. The browser directory keeps its query and filter state in the URL, so a result set can be bookmarked or shared. Public API search is limited to 30 requests per minute per Cloudflare location; the server-rendered directory search has a 60 requests per minute budget. Retry a 429 response after the seconds in Retry-After.
Target the part of a skill you care about.
| Parameter | Searches | Example |
|---|---|---|
q | All indexed fields: name, description, category, source, and full instructions. Multiple unquoted words must all match somewhere in the skill; wrap words in double quotes to require an exact contiguous phrase. Minimum 2 characters when provided. | q=%22Use%20when%20the%20user%22 |
name | Skill name. | name=frontend |
description | YAML frontmatter description. | description=image%20generation |
category | Catalog category. | category=Design |
source | Source repository. | source=anthropics%2Fskills |
instructions | Full SKILL.md instructions. | instructions=security%20audit |
owner | GitHub owner. This is an additional filter and applies to GitHub-backed skills. | owner=anthropics |
limit | Maximum results. Defaults to 50; accepted range is 1–200. | limit=10 |
format | Response format: json (default) or text for a plain-text result list. | format=text |
Field-specific parameters are combined with AND: name=frontend&category=Development only returns skills matching both filters. A broad q can be combined with field filters too.
Copy a request into an agent tool.
curl 'https://skilly.sh/api/v1/skills/search?q=%22Use%20when%20the%20user%22&limit=10'curl 'https://skilly.sh/api/v1/skills/search?name=frontend&category=Development&owner=vercel-labs'curl 'https://skilly.sh/api/v1/skills/search?q=database%20migration&limit=10&format=text'const params = new URLSearchParams({
q: 'security audit',
category: 'Development',
limit: '10',
})
const response = await fetch(
'https://skilly.sh/api/v1/skills/search?' + params,
)
const { data } = await response.json() Use URLSearchParams instead of concatenating unescaped user input. It encodes spaces, slashes, and other reserved characters correctly.
Link someone directly to a browser search.
https://skilly.sh/?q=typography&category=Design&sort=relevance&page=1#directory| Parameter | Values | Purpose |
|---|---|---|
q | Search text | Search names, descriptions, instructions, repositories, and categories. |
category | Catalog category | Filter the directory to one category. |
publisher | Repository, such as anthropics/skills | Filter to one source repository. |
sort | relevance or name | Choose result ordering. |
page | 1-based number | Open a particular page of directory results. |
The directory uses page=1 for its first page. This is separate from the leaderboard endpoint, where page is zero-indexed. The public search API returns up to limit results and does not use directory pagination.
Handle the result envelope consistently.
{
"data": [
{
"name": "frontend-design",
"description": "...",
"category": "Design",
"source": "anthropics/skills",
"url": "https://skills.sh/anthropics/skills/frontend-design"
}
],
"query": "frontend",
"searchType": "fuzzy",
"count": 1,
"durationMs": 3
}Search responses are JSON by default and contain result summaries, including each skill’s canonical URL and install URL. Add format=text when an AI agent or other text-only client needs a plain-text result list instead. Fetch the public skill detail endpoint from the API reference when an integration needs the complete SKILL.md content.
{ "error": "invalid_query", "message": "..." }. A missing query returns 400; search itself does not require authentication.