Skip to content
Back to search

skyll

A tool for autonomous agents like OpenClaw to discover and learn skills autonomously

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/assafelovic--skyll/badge.svg)](/listings/assafelovic--skyll)

HTML

<a href="/listings/assafelovic--skyll"><img src="/api/listings/assafelovic--skyll/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 265 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="web/public/logo.png" alt="Skyll" width="120" height="120">
  3. </p>
  4. <p align="center">
  5. <a href="https://pypi.org/project/skyll/"><img src="https://img.shields.io/pypi/v/skyll?style=flat&color=7ed957&labelColor=1a1a1a&logo=pypi&logoColor=white" alt="PyPI"></a>
  6. <a href="https://skills.sh/assafelovic/skyll/skyll"><img src="https://img.shields.io/badge/Claude_Skill-skyll-ff6b6b?style=flat&labelColor=1a1a1a&logo=anthropic&logoColor=white" alt="Claude Skill"></a>
  7. <a href="https://skyll.app/docs"><img src="https://img.shields.io/badge/Docs-skyll.app-87ceeb?style=flat&labelColor=1a1a1a&logo=readthedocs&logoColor=white" alt="Docs"></a>
  8. <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-ffb3d9?style=flat&labelColor=1a1a1a" alt="MCP"></a>
  9. <a href="https://discord.gg/CxdMdfZS"><img src="https://img.shields.io/badge/Discord-join-5865F2?style=flat&labelColor=1a1a1a&logo=discord&logoColor=white" alt="Discord"></a>
  10. </p>
  11. <p align="center">
  12. <a href="#skyll">Skyll</a> •
  13. <a href="#why-use-skyll">Why use Skyll?</a> •
  14. <a href="#features">Features</a> •
  15. <a href="#quick-start">Quick Start</a> •
  16. <a href="#mcp-server">MCP Server</a> •
  17. <a href="#use-cases">Use Cases</a> •
  18. <a href="#documentation">Documentation</a> •
  19. <a href="#contributing-skills">Contributing</a>
  20. </p>
  21. ---
  22. # Skyll
  23. 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.
  24. ## Why use Skyll?
  25. 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.
  26. 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.
  27. ```json
  28. {
  29. "query": "react performance",
  30. "count": 1,
  31. "skills": [
  32. {
  33. "id": "react-best-practices",
  34. "title": "React Best Practices",
  35. "source": "vercel/ai-skills",
  36. "relevance_score": 85.5,
  37. "install_count": 1250,
  38. "content": "# React Best Practices\n\n## Performance\n..."
  39. }
  40. ]
  41. }
  42. ```
  43. **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.
  44. ## Features
  45. - 🔍 **Multi-Source Search**: Query [skills.sh](https://skills.sh), community registry, and more
  46. - 📄 **Full Content**: Returns complete SKILL.md with parsed metadata
  47. - 📎 **References**: Optionally fetch additional docs from `references/` directories
  48. - 📊 **Relevance Ranking**: Scored 0-100 based on content, query match, and popularity
  49. - 🔄 **Deduplication**: Automatic deduplication across sources
  50. - ⚡ **Cached**: Aggressive caching to respect GitHub rate limits
  51. - 🔌 **Dual Interface**: REST API + MCP Server
  52. - 🔧 **Extensible**: Easy to add new skill sources and ranking strategies
  53. ## Quick Start
  54. ### Install with pip
  55. The recommended way to use Skyll in your agents:
  56. ```bash
  57. pip install skyll
  58. ```
  59. ```python
  60. from skyll import Skyll
  61. async with Skyll() as client:
  62. skills = await client.search("react performance", limit=5)
  63. for skill in skills:
  64. print(f"{skill.title}: {skill.description}")
  65. print(skill.content) # Full SKILL.md content
  66. ```
  67. Uses the hosted API at `api.skyll.app` by default - no server setup required.
  68. ### REST API
  69. For other languages or direct integration, call the API directly:
  70. ```bash
  71. # Search for skills
  72. curl "https://api.skyll.app/search?q=react+performance&limit=5"
  73. # Get a specific skill by name (always fetches latest version)
  74. curl "https://api.skyll.app/skill/react-best-practices"
  75. # Get by full path
  76. curl "https://api.skyll.app/skill/vercel-labs/agent-skills/vercel-react-best-practices"
  77. ```
  78. 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.
  79. Interactive docs: [api.skyll.app/docs](https://api.skyll.app/docs)
  80. ### Self-Hosted
  81. Run your own Skyll server for full control:
  82. ```bash
  83. # Clone and install
  84. git clone https://github.com/assafelovic/skyll.git
  85. cd skyll
  86. pip install -e ".[server]"
  87. # Optional: Add GitHub token for higher rate limits
  88. echo "GITHUB_TOKEN=ghp_your_token" > .env
  89. # Start the server
  90. uvicorn src.main:app --port 8000
  91. ```
  92. ```bash
  93. # Search for skills
  94. curl "http://localhost:8000/search?q=react+performance&limit=5"
  95. ```
  96. Point the Python client to your server:
  97. ```python
  98. async with Skyll(base_url="http://localhost:8000") as client:
  99. skills = await client.search("testing")
  100. ```
  101. #### Demo UI
  102. <img width="800" alt="Skyll Demo" src="https://github.com/user-attachments/assets/7aed6627-b365-41d5-adf1-2bc4bdcdc8b9" />
  103. Open `web/index.html` in your browser for an interactive demo, or run the full landing page:
  104. ```bash
  105. cd web/landing
  106. npm install
  107. npm run dev
  108. # Open http://localhost:3000
  109. ```
  110. ## MCP Server
  111. Skyll provides a hosted MCP server at `api.skyll.app/mcp` - no installation required.
  112. ### Hosted MCP (Recommended)
  113. For Claude Desktop, Cursor, or other MCP clients, add to your configuration:
  114. ```json
  115. {
  116. "mcpServers": {
  117. "skyll": {
  118. "url": "https://api.skyll.app/mcp"
  119. }
  120. }
  121. }
  122. ```
  123. That's it! The hosted server provides the following MCP tools:
  124. | Tool | Description |
  125. |------|-------------|
  126. | `search_skills` | Search for skills by natural language query |
  127. | `add_skill` | Get a skill by name (like `npx skills add`) |
  128. | `get_skill` | Get a specific skill by source/id |
  129. | `get_cache_stats` | Get cache statistics |
  130. The `add_skill` tool is the simplest way for agents to learn skills:
  131. ```python
  132. # Simple name - searches and returns best match
  133. add_skill("react-best-practices")
  134. # Full path - direct lookup
  135. add_skill("vercel-labs/agent-skills/vercel-react-best-practices")
  136. ```
  137. ### Self-Hosted MCP
  138. If you prefer to run your own MCP server:
  139. ```json
  140. {
  141. "mcpServers": {
  142. "skyll": {
  143. "command": "/path/to/skyll/venv/bin/python",
  144. "args": ["-m", "src.mcp_server"],
  145. "cwd": "/path/to/skyll"
  146. }
  147. }
  148. }
  149. ```
  150. Or run standalone:
  151. ```bash
  152. python -m src.mcp_server # stdio (default)
  153. python -m src.mcp_server --transport http --port 8080 # HTTP
  154. python -m src.mcp_server --transport sse --port 8080 # SSE (legacy)
  155. ```
  156. ## Configuration
  157. | Variable | Description | Default |
  158. |----------|-------------|---------|
  159. | `GITHUB_TOKEN` | GitHub PAT for higher rate limits ([create one](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)) | None |
  160. | `CACHE_TTL` | Cache TTL in seconds | 86400 |
  161. | `ENABLE_REGISTRY` | Enable community registry | true |
  162. ## Use Cases
  163. **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.
  164. **Deep Research**: User needs a comprehensive market analysis → Agent discovers `gpt-researcher` → Runs autonomous multi-step research with citations and detailed reports.
  165. **Testing Workflows**: User says "Add tests for this feature" → Agent finds `test-driven-development` → Follows TDD workflow: write tests first, then implement.
  166. **Building Integrations**: User wants to connect their app to external APIs → Agent learns `mcp-builder` → Creates Model Context Protocol servers following best practices.
  167. ## Documentation
  168. | Doc | Description |
  169. |-----|-------------|
  170. | [API Reference](./docs/api.md) | REST endpoints, MCP tools, response format |
  171. | [Ranking Algorithm](./docs/ranking.md) | How skills are scored and ranked |
  172. | [Skill Sources](./docs/sources.md) | Available sources and adding new ones |
  173. | [References](./docs/references.md) | Fetching additional skill documentation |
  174. | [Architecture](./docs/architecture.md) | System design and extending Skyll |
  175. For a web-friendly version, visit [skyll.app/docs](https://skyll.app/docs).
  176. ## Contributing Skills
  177. Add your skill to the community registry! Edit [`registry/SKILLS.md`](./registry/SKILLS.md):
  178. ```markdown
  179. - your-skill-id | your-username/your-repo | path/to/skill | What your skill does
  180. ```
  181. Then submit a PR. Requirements:
  182. - Valid `SKILL.md` following the [Agent Skills Spec](https://agentskills.io)
  183. - Keep descriptions under 80 characters
  184. ## What are Agent Skills?
  185. Agent skills are markdown files (SKILL.md) that teach AI coding agents how to complete specific tasks. They follow the [Agent Skills specification](https://agentskills.io) and work with 27+ AI agents. Learn more at [skills.sh](https://skills.sh).
  186. ## License
  187. Apache-2.0 License. See [LICENSE](LICENSE) for details.
  188. ---
  189. <p align="center">
  190. Built for autonomous agents • <a href="https://skyll.app">skyll.app</a> • <a href="https://api.skyll.app">api.skyll.app</a> • <a href="https://discord.gg/CxdMdfZS">Discord</a>
  191. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.