Skip to content

api.md

Latest commit

 

History

History
308 lines (237 loc) · 8.22 KB

api.md

File metadata and controls

308 lines (237 loc) · 8.22 KB

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

Method Description
search(query, limit=10, include_content=True, include_references=False) Search for skills
get(source, skill_id, include_references=False) Get a specific skill
health() Check API health status

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

Method Endpoint Description
GET /search?q={query} Search skills
POST /search Search skills (JSON body)
GET /skill/{name} Get skill by name (latest version)
GET /skills/{source}/{skill_id} Get specific skill by source/ID
POST /mcp/ MCP server endpoint
GET /health Health check
GET /docs OpenAPI documentation

Search Parameters

Parameter Type Default Description
q string required Search query
limit int 10 Maximum results (1-50)
include_content bool true Fetch full SKILL.md content
include_references bool false Include reference files

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 Description
search_skills Search for skills by query
add_skill Get a skill by name (like npx skills add)
get_skill Get a specific skill by source and ID
get_cache_stats Get cache hit/miss statistics

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

Field Type Description
id string Unique skill identifier
title string Human-readable title
description string Skill description from YAML frontmatter
version string Skill version
allowed_tools array Tools the skill is allowed to use
source string GitHub repository (owner/repo)
refs object URLs for skills.sh, GitHub, and raw content
install_count int Number of installations from skills.sh
relevance_score float 0-100 relevance score (see Ranking)
content string Full SKILL.md markdown content
references array Additional reference files (when requested)
metadata object Additional metadata from YAML frontmatter