API Reference

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"

Add Skill by Name

The /skill/{name} endpoint fetches the latest version of a skill by name. Similar to npx skills add but for runtime context injection.

# Get by simple name (searches for best match)
curl "https://api.skyll.app/skill/react-best-practices"

# Get by full path (direct lookup)
curl "https://api.skyll.app/skill/vercel-labs/agent-skills/vercel-react-best-practices"
curl "https://api.skyll.app/skill/anthropics/skills/frontend-design"

# Include reference files
curl "https://api.skyll.app/skill/react-best-practices?include_references=true"

This endpoint always fetches fresh content from GitHub, ensuring you have the latest version.

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"
curl "http://localhost:8000/skill/react-best-practices"

Interactive API docs: api.skyll.app/docs

MCP Server

Built with FastMCP - a framework for building MCP servers.

Hosted MCP (Recommended)

For Claude Desktop, Cursor, or other MCP clients, add to your configuration:

{
  "mcpServers": {
    "skyll": {
      "url": "https://api.skyll.app/mcp"
    }
  }
}

No installation required - the hosted server is always up-to-date.

Tools

Tool Parameters

search_skills:

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

add_skill:

• name (string, required): Skill name or full path. Supports:
  • Simple name: "react-best-practices" (searches and returns top match)
  • Full path: "vercel-labs/agent-skills/vercel-react-best-practices"
• 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 Calls

{
  "name": "add_skill",
  "arguments": {
    "name": "react-best-practices"
  }
}

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

Self-Hosted MCP

If you prefer to run your own MCP server:

{
  "mcpServers": {
    "skyll": {
      "command": "/path/to/skyll/venv/bin/python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "/path/to/skyll"
    }
  }
}

Transport Options

stdio (default, for Claude Desktop and Cursor):

python -m src.mcp_server

HTTP (for web clients and hosted deployments):

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

SSE (legacy, for older 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