skyll 0.1.0

Skill discovery for AI agents - search and retrieve agent skills on demand

Installation • Quick Start • API Reference • Self-Hosted • MCP Server • Documentation

---

Skyll

Skill discovery for AI agents. Search and retrieve agent skills on demand with a simple Python client.

pip install skyll

from skyll import Skyll

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

Why Skyll?

Agent skills (SKILL.md files) are a powerful way to extend what AI agents can do, but today they require manual installation before a session. Developers need to know in advance which skills they'll need.

Skyll changes that. Any agent can discover and retrieve skills on demand. No pre-installation. No human intervention. Agents explore, choose based on context, and use skills autonomously.

Installation

# Client only (recommended for most users)
pip install skyll

# With server for self-hosting
pip install skyll[server]

Quick Start

Using the Client

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}")
        print(f"   Source: {skill.source}")
        print(f"   Installs: {skill.install_count:,}")
        print(f"   Score: {skill.relevance_score:.1f}")
        
        if skill.content:
            print(f"   Content: {len(skill.content):,} chars")

One-liner

from skyll import search_skills

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

Get a Specific Skill

async with Skyll() as client:
    skill = await client.get("anthropics/skills", "skill-creator")
    if skill:
        print(skill.content)

Include References

Some skills have additional documentation in references/ directories:

async with Skyll() as client:
    skills = await client.search("react", include_references=True)
    
    for skill in skills:
        for ref in skill.references:
            print(f"📎 {ref.name}: {len(ref.content)} chars")

API Reference

Skyll Client

Skyll(
    base_url="https://api.skyll.app",  # API endpoint
    timeout=30.0,                       # Request timeout in seconds
)

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

Skill Model

skill.id                # Skill identifier
skill.title             # Display name
skill.description       # What the skill does
skill.source            # GitHub owner/repo
skill.content           # Full SKILL.md markdown
skill.install_count     # Installs from skills.sh
skill.relevance_score   # Ranking score (0-100)
skill.references        # List of reference files
skill.refs.github       # GitHub URL
skill.refs.skills_sh    # skills.sh URL

REST API

The hosted API is available at https://api.skyll.app:

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

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

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

Interactive docs: api.skyll.app/docs

Self-Hosted

Run your own Skyll server:

# 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

Then point your client to it:

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

Configuration

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

MCP Server

For Claude Desktop, Cursor, or other MCP clients:

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

Use Cases

Web Research: Agent searches for tavily-search → Uses Tavily's LLM-optimized search API for real-time web results.

Deep Research: Agent discovers gpt-researcher → Runs autonomous multi-step research with citations.

Testing Workflows: Agent finds test-driven-development → Follows TDD workflow: write tests first, then implement.

Building Integrations: Agent retrieves mcp-builder → Creates MCP servers following best practices.

Features

• 🔍 Multi-Source Search: Query skills.sh, community registry, and more
• 📄 Full Content: Returns complete SKILL.md with parsed metadata
• 📎 References: Fetch additional docs from references/ directories
• 📊 Relevance Ranking: Scored by content match and popularity
• ⚡ Cached: 24-hour cache to respect GitHub rate limits
• 🔌 Dual Interface: Python client + REST API + MCP Server

Documentation

Doc	Description
API Reference	REST endpoints, response format
Ranking Algorithm	How skills are scored
Skill Sources	Available sources
Architecture	System design

Web docs: 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

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