{"openapi":"3.0.3","info":{"title":"Skilly API","version":"1.0.0","description":"Programmatic access to the Skilly agent-skill catalog. The endpoint contract mirrors the skills.sh API."},"servers":[{"url":"https://skilly.sh"}],"paths":{"/api/v1/skills":{"get":{"operationId":"list-skills","summary":"Browse the skill leaderboard.","description":"Returns a paginated list of indexed skills. Pages are zero-indexed and installs are sorted highest-first by the upstream-compatible catalog view.","parameters":[{"name":"view","in":"query","required":false,"description":"Ranking view: all-time, trending, or hot.","schema":{"type":"string"},"example":"all-time"},{"name":"page","in":"query","required":false,"description":"Zero-indexed page number.","schema":{"type":"integer"},"example":0},{"name":"per_page","in":"query","required":false,"description":"Results per page, from 1 to 500.","schema":{"type":"integer"},"example":20}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListResponse"}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Skill or audit not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Configured request budget and window."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/search":{"get":{"operationId":"search-skills","summary":"Search names, descriptions, categories, sources, and instructions.","description":"Publicly searches the indexed skill catalog. Use q for a broad full-text search, or use name, description, category, source, type, and instructions to target specific fields. Field parameters are combined with AND. JSON is returned by default; set format=text for a text/plain result that is convenient for AI agents and other text-only clients.","parameters":[{"name":"q","in":"query","required":false,"description":"Broad full-text search across all indexed fields. Unquoted words use AND matching; double-quoted text requires an exact contiguous phrase. Minimum 2 characters when provided.","schema":{"type":"string"},"example":"\"react native\""},{"name":"name","in":"query","required":false,"description":"Match the skill name.","schema":{"type":"string"},"example":"algorithmic"},{"name":"description","in":"query","required":false,"description":"Match the YAML frontmatter description.","schema":{"type":"string"},"example":"image generation"},{"name":"category","in":"query","required":false,"description":"Match any functional catalog category.","schema":{"type":"string"},"example":"frontend"},{"name":"source","in":"query","required":false,"description":"Match the source repository.","schema":{"type":"string"},"example":"anthropics/skills"},{"name":"type","in":"query","required":false,"description":"Match the upstream provenance: official or community.","schema":{"type":"string"},"example":"official"},{"name":"instructions","in":"query","required":false,"description":"Match the full SKILL.md instructions.","schema":{"type":"string"},"example":"security audit"},{"name":"limit","in":"query","required":false,"description":"Maximum results, from 1 to 200.","schema":{"type":"integer"},"example":5},{"name":"owner","in":"query","required":false,"description":"Restrict results to a GitHub owner.","schema":{"type":"string"},"example":"anthropics"},{"name":"format","in":"query","required":false,"description":"Response format. JSON is the default; text returns a plain-text result list for AI agents and text-only clients.","schema":{"type":"string","enum":["json","text"]},"example":"text"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}},"text/plain":{"schema":{"type":"string"},"description":"Available when format=text."}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Skill or audit not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Configured request budget and window."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/curated":{"get":{"operationId":"curated-skills","summary":"Get the Editor’s picks.","description":"Returns the skills selected by the Skilly team in the same envelope as skills.sh.","parameters":[],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CuratedResponse"}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Skill or audit not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Configured request budget and window."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/{source}/{skill}":{"get":{"operationId":"skill-detail","summary":"Fetch metadata and the complete SKILL.md file.","description":"Use the id from a list or search response. For GitHub sources, source is the owner/repository path; for well-known sources, source is the provider domain.","parameters":[{"name":"source","in":"path","required":true,"description":"The source repository, such as anthropics/skills.","schema":{"type":"string"},"example":"anthropics/skills"},{"name":"skill","in":"path","required":true,"description":"The URL-safe skill slug.","schema":{"type":"string"},"example":"algorithmic-art"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailResponse"}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Skill or audit not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Configured request budget and window."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/skills/audit/{source}/{skill}":{"get":{"operationId":"security-audit","summary":"Fetch available third-party security audits.","description":"Returns all available provider audits for a skill. This endpoint is public; a skill with no available audit returns 404.","parameters":[{"name":"source","in":"path","required":true,"description":"The source repository, such as anthropics/skills.","schema":{"type":"string"},"example":"anthropics/skills"},{"name":"skill","in":"path","required":true,"description":"The URL-safe skill slug.","schema":{"type":"string"},"example":"algorithmic-art"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditResponse"}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Skill or audit not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Retry after the number of seconds in the Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Configured request budget and window."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Skill":{"type":"object","required":["id","slug","name","description","category","categories","source","installs","sourceType","installUrl","url"],"properties":{"id":{"type":"string","example":"anthropics/skills/algorithmic-art"},"slug":{"type":"string","example":"algorithmic-art"},"name":{"type":"string","example":"algorithmic-art"},"description":{"type":"string","example":"Create generative art with code."},"short_description":{"type":"string","example":"Create generative visuals with code."},"category":{"type":"string","example":"design"},"categories":{"type":"array","items":{"type":"string"},"example":["design","frontend"]},"type":{"type":"string","enum":["official","community"],"example":"official"},"editorsPick":{"type":"boolean","example":true},"source":{"type":"string","example":"anthropics/skills"},"installs":{"type":"integer","minimum":0,"example":24531},"sourceType":{"type":"string","enum":["github","well-known"]},"installUrl":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"isDuplicate":{"type":"boolean"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"perPage":{"type":"integer"},"total":{"type":"integer"},"hasMore":{"type":"boolean"}}},"ListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"SearchResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}},"query":{"type":"string"},"searchType":{"type":"string","enum":["fuzzy","semantic"]},"count":{"type":"integer"},"durationMs":{"type":"integer"}}},"CuratedResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Skill"}},"totalOwners":{"type":"integer"},"totalSkills":{"type":"integer"},"generatedAt":{"type":"string","format":"date-time"}}},"DetailResponse":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"slug":{"type":"string"},"installs":{"type":"integer"},"hash":{"type":["string","null"]},"files":{"type":["array","null"],"items":{"type":"object","properties":{"path":{"type":"string"},"contents":{"type":"string"}}}}}},"AuditResponse":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string"},"slug":{"type":"string"},"audits":{"type":"array"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}