045 API Af2df17b

API Reference

Skyll provides three interfaces: a Python client, a REST API, and an MCP server.

All interfaces return a ranked list of skills with relevance scores (0-100), giving agents and developers multiple options to choose from. This enables dynamic filtering, custom selection logic, or letting agents pick based on context.

Python Client

The recommended way to use Skyll in Python agents. Uses the hosted API by default.

Installation

pip install skyll

Basic Usage

from skyll import Skyll

async with Skyll() as client:
    # Search for skills
    skills = await client.search("react performance", limit=5)
    
    for skill in skills:
        print(f"{skill.title}: {skill.description}")
        print(skill.content)  # Full SKILL.md content

Client Methods

Examples

from skyll import Skyll

async with Skyll() as client:
    # Basic search
    skills = await client.search("react performance", limit=5)
    
    # Get a specific skill
    skill = await client.get("anthropics/skills", "skill-creator")
    
    # Include reference files
    skills = await client.search("react native", include_references=True)
    for skill in skills:
        for ref in skill.references:
            print(f"Reference: {ref.name}")
    
    # Health check
    status = await client.health()
    print(f"API status: {status['status']}")

Using a Self-Hosted Server

async with Skyll(base_url="http://localhost:8000") as client:
    skills = await client.search("testing")

One-liner Helper

from skyll import search_skills

# Simple function for quick searches
skills = await search_skills("python testing", limit=5)

REST API

The hosted API is available at https://api.skyll.app. For self-hosted, replace with your server URL.

Endpoints

Search Parameters

Examples

# Basic search (hosted API)
curl "https://api.skyll.app/search?q=react+performance&limit=5"

# Include reference files
curl "https://api.skyll.app/search?q=react+native&limit=1&include_references=true"

# Get specific skill
curl "https://api.skyll.app/skills/anthropics/skills/skill-creator"

# POST search with JSON body
curl -X POST "https://api.skyll.app/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "react performance", "limit": 5}'

# Health check
curl "https://api.skyll.app/health"

Self-Hosted Examples

# Start your own server
uvicorn src.main:app --port 8000

# Then use localhost
curl "http://localhost:8000/search?q=react+performance&limit=5"

Interactive API docs: api.skyll.app/docs

MCP Server

Built with the official MCP Python SDK.

Tools

Tool Parameters

search_skills:

• query (string, required): Search query
• limit (int, default 10): Maximum results
• include_references (bool, default false): Include reference files

get_skill:

• source (string, required): Repository in owner/repo format
• skill_id (string, required): Skill identifier
• include_references (bool, default false): Include reference files

Example Tool Call

{
  "name": "search_skills",
  "arguments": {
    "query": "react performance optimization",
    "limit": 5,
    "include_references": true
  }
}

Transport Options

stdio (default, for Claude Desktop and Cursor):

python -m src.mcp_server

SSE (for web clients):

python -m src.mcp_server --transport sse --port 8080

Response Format

{
  "query": "react performance",
  "count": 1,
  "skills": [
    {
      "id": "react-best-practices",
      "title": "React Best Practices",
      "description": "Performance optimization for React and Next.js...",
      "version": "1.0.0",
      "allowed_tools": ["Bash", "Read", "Write"],
      "source": "vercel-labs/agent-skills",
      "refs": {
        "skills_sh": "https://skills.sh/...",
        "github": "https://github.com/...",
        "raw": "https://raw.githubusercontent.com/..."
      },
      "install_count": 1250,
      "relevance_score": 85.5,
      "content": "# React Best Practices\n\nFull markdown content...",
      "references": [
        {
          "name": "flatlist-optimization.md",
          "path": "references/flatlist-optimization.md",
          "content": "Full reference content...",
          "raw_url": "https://raw.githubusercontent.com/..."
        }
      ],
      "metadata": {}
    }
  ]
}

Skill Fields