System Overview

Architecture

Skyll is designed as a modular, extensible system for skill discovery.

System Overview

┌─────────────────────────────────────────────────────────────────┐
│                        Skyll                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐    ┌───────────────────┐    ┌──────────────┐ │
│  │   REST API   │───▶│ SkillSearchService │◀───│  MCP Server  │ │
│  │  (FastAPI)   │    │   (Core Engine)    │    │  (FastMCP)   │ │
│  │  Port 8000   │    │                    │    │  stdio/SSE   │ │
│  └──────────────┘    └─────────┬──────────┘    └──────────────┘ │
│                                │                                │
│                    ┌───────────┴───────────┐                   │
│                    ▼                       ▼                   │
│         ┌─────────────────┐    ┌─────────────────────┐         │
│         │  Skill Sources  │    │  GitHubClient       │         │
│         │  (search APIs)  │    │  (content fetcher)  │         │
│         └─────────────────┘    └──────────┬──────────┘         │
│                                           │                    │
│                               ┌───────────┴───────────┐        │
│                               ▼                       ▼        │
│                    ┌─────────────────┐    ┌─────────────────┐  │
│                    │  CacheBackend   │    │  SkillParser    │  │
│                    │  (pluggable)    │    │  (YAML+MD)      │  │
│                    └─────────────────┘    └─────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Core Components

SkillSearchService (src/core/service.py)

The central orchestrator that:

• Manages skill sources
• Coordinates parallel searches
• Deduplicates results
• Fetches content via GitHub client
• Applies ranking

Skill Sources (src/sources/)

Pluggable sources for skill discovery:

• SkillsShSource: Queries skills.sh API
• SkillRegistrySource: Reads local registry file

See Sources for adding custom sources.

GitHubClient (src/clients/github.py)

Fetches SKILL.md content from GitHub:

• Uses GitHub Tree API for efficient file location
• Handles branch detection (main/master)
• Fetches reference files
• Caches repository trees

Ranker (src/ranking/)

Computes relevance scores:

• RelevanceRanker: Default multi-signal ranker
• HybridRanker: Placeholder for future hybrid approach
• SemanticRanker: Placeholder for embedding-based ranking

See Ranking for algorithm details.

CacheBackend (src/cache/)

Pluggable caching layer:

• InMemoryCache: Default, TTL-based
• Extensible for Redis, Memcached, etc.

SkillParser (src/core/parser.py)

Parses SKILL.md files:

• Extracts YAML frontmatter
• Parses markdown content
• Returns structured data

Request Flow

1. Request arrives (REST or MCP)
2. Search sources in parallel
3. Deduplicate by owner/repo/skill-id
4. Fetch content from GitHub (with caching)
5. Parse YAML frontmatter and markdown
6. Rank by relevance score
7. Return structured JSON

Extending Skyll

Custom Cache Backend

from src.cache.base import CacheBackend

class RedisCache(CacheBackend):
    def __init__(self, redis_url: str):
        import redis.asyncio as redis
        self.redis = redis.from_url(redis_url)
    
    async def get(self, key: str):
        data = await self.redis.get(key)
        return json.loads(data) if data else None
    
    async def set(self, key: str, value, ttl: int = None):
        await self.redis.set(key, json.dumps(value), ex=ttl)
    
    async def delete(self, key: str):
        await self.redis.delete(key)
    
    async def clear(self):
        await self.redis.flushdb()

Custom Ranker

from src.ranking.base import Ranker

class SemanticRanker(Ranker):
    def __init__(self):
        from sentence_transformers import SentenceTransformer
        self.model = SentenceTransformer('all-MiniLM-L6-v2')
    
    def rank(self, skills, query="", include_references=False):
        query_embedding = self.model.encode(query)
        
        for skill in skills:
            text = f"{skill.id} {skill.description or ''}"
            skill_embedding = self.model.encode(text)
            similarity = cosine_similarity(query_embedding, skill_embedding)
            skill.relevance_score = similarity * 100
        
        return sorted(skills, key=lambda s: s.relevance_score, reverse=True)

Custom Skill Source

See Sources for the full guide.

Directory Structure

src/
├── api/
│   └── routes.py          # FastAPI REST endpoints
├── cache/
│   ├── base.py            # CacheBackend protocol
│   └── memory.py          # InMemoryCache implementation
├── clients/
│   ├── github.py          # GitHub content fetcher
│   └── skillssh.py        # skills.sh API client
├── core/
│   ├── models.py          # Pydantic models
│   ├── parser.py          # SKILL.md parser
│   └── service.py         # Main service orchestrator
├── ranking/
│   ├── base.py            # Ranker protocol
│   ├── relevance.py       # RelevanceRanker
│   ├── hybrid.py          # Placeholder
│   └── semantic.py        # Placeholder
├── sources/
│   ├── base.py            # SkillSource protocol
│   ├── skillssh.py        # skills.sh source
│   └── registry.py        # Local registry source
├── main.py                # FastAPI app
└── mcp_server.py          # MCP server

Configuration

MCP Server

Built with FastMCP:

• Hosted endpoint: https://api.skyll.app/mcp - no installation required
• stdio transport: For Claude Desktop, Cursor, and local agents
• HTTP transport: For web-based MCP clients and hosted deployments (recommended)
• SSE transport: Legacy support for older web clients
• Tools: search_skills, add_skill, get_skill, get_cache_stats

The add_skill tool provides a simplified interface for fetching skills by name, similar to npx skills add but for runtime context injection.