---

Skyll

Skyll is a REST API and MCP server that lets any AI agent search for and learn agent skills at runtime. It aggregates skills from multiple sources, fetches the full SKILL.md content from GitHub, and returns structured JSON ready for context injection.

Why use Skyll?

Agent skills (SKILL.md files) are a powerful way to extend what AI agents can do, but today they only work with a handful of tools like Claude Code and Cursor. Skills require manual installation before a session, which means developers need to know in advance which skills they will need.

Skyll democratizes access to skills. Any agent, framework, or tool can discover and learn skills on demand. No pre-installation. No human intervention. Agents explore, choose based on context, and use skills autonomously.

{
  "query": "react performance",
  "count": 1,
  "skills": [
    {
      "id": "react-best-practices",
      "title": "React Best Practices",
      "source": "vercel/ai-skills",
      "relevance_score": 85.5,
      "install_count": 1250,
      "content": "# React Best Practices\n\n## Performance\n..."
    }
  ]
}

Why options matter: The ranked list surfaces popular and relevant skills, letting agents choose based on user requests, task context, or what's trending. It's about giving agents freedom to discover.

Features

• 🔍 Multi-Source Search: Query skills.sh, community registry, and more
• 📄 Full Content: Returns complete SKILL.md with parsed metadata
• 📎 References: Optionally fetch additional docs from references/ directories
• 📊 Relevance Ranking: Scored 0-100 based on content, query match, and popularity
• 🔄 Deduplication: Automatic deduplication across sources
• ⚡ Cached: Aggressive caching to respect GitHub rate limits
• 🔌 Dual Interface: REST API + MCP Server
• 🔧 Extensible: Easy to add new skill sources and ranking strategies

Quick Start

Install with pip

The recommended way to use Skyll in your agents:

pip install skyll

from skyll import Skyll

async with Skyll() as client:
    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

Uses the hosted API at api.skyll.app by default - no server setup required.

REST API

For other languages or direct integration, call the API directly:

# Search for skills
curl "https://api.skyll.app/search?q=react+performance&limit=5"

# Get a specific skill by name (always fetches latest version)
curl "https://api.skyll.app/skill/react-best-practices"

# Get by full path
curl "https://api.skyll.app/skill/vercel-labs/agent-skills/vercel-react-best-practices"

The /skill/{name} endpoint is similar to npx skills add - it returns the latest version of a skill, ensuring your agents always have up-to-date instructions.

Interactive docs: api.skyll.app/docs

Self-Hosted

Run your own Skyll server for full control:

# Clone and install
git clone https://github.com/assafelovic/skyll.git
cd skyll
pip install -e ".[server]"

# Optional: Add GitHub token for higher rate limits
echo "GITHUB_TOKEN=ghp_your_token" > .env

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

# Search for skills
curl "http://localhost:8000/search?q=react+performance&limit=5"

Point the Python client to your server:

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

Demo UI

Open web/index.html in your browser for an interactive demo, or run the full landing page:

cd web/landing
npm install
npm run dev
# Open http://localhost:3000

MCP Server

Skyll provides a hosted MCP server at api.skyll.app/mcp - no installation required.

Hosted MCP (Recommended)

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

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

That's it! The hosted server provides the following MCP tools:

Tool	Description
search_skills	Search for skills by natural language query
add_skill	Get a skill by name (like npx skills add)
get_skill	Get a specific skill by source/id
get_cache_stats	Get cache statistics

The add_skill tool is the simplest way for agents to learn skills:

# Simple name - searches and returns best match
add_skill("react-best-practices")

# Full path - direct lookup
add_skill("vercel-labs/agent-skills/vercel-react-best-practices")

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"
    }
  }
}

Or run standalone:

python -m src.mcp_server                           # stdio (default)
python -m src.mcp_server --transport http --port 8080  # HTTP
python -m src.mcp_server --transport sse --port 8080   # SSE (legacy)

Configuration

Variable	Description	Default
GITHUB_TOKEN	GitHub PAT for higher rate limits (create one)	None
CACHE_TTL	Cache TTL in seconds	86400
ENABLE_REGISTRY	Enable community registry	true

Use Cases

Web Research: User asks "Find the latest news on AI agents" → Agent searches for tavily-search → Uses Tavily's LLM-optimized search API to fetch real-time web results.

Deep Research: User needs a comprehensive market analysis → Agent discovers gpt-researcher → Runs autonomous multi-step research with citations and detailed reports.

Testing Workflows: User says "Add tests for this feature" → Agent finds test-driven-development → Follows TDD workflow: write tests first, then implement.

Building Integrations: User wants to connect their app to external APIs → Agent learns mcp-builder → Creates Model Context Protocol servers following best practices.

Documentation

Doc	Description
API Reference	REST endpoints, MCP tools, response format
Ranking Algorithm	How skills are scored and ranked
Skill Sources	Available sources and adding new ones
References	Fetching additional skill documentation
Architecture	System design and extending Skyll

For a web-friendly version, visit skyll.app/docs.

Contributing Skills

Add your skill to the community registry! Edit registry/SKILLS.md:

- your-skill-id | your-username/your-repo | path/to/skill | What your skill does

Then submit a PR. Requirements:

• Valid SKILL.md following the Agent Skills Spec
• Keep descriptions under 80 characters

What are Agent Skills?

Agent skills are markdown files (SKILL.md) that teach AI coding agents how to complete specific tasks. They follow the Agent Skills specification and work with 27+ AI agents. Learn more at skills.sh.

License

Apache-2.0 License. See LICENSE for details.

---

Built for autonomous agents • skyll.app • api.skyll.app • Discord