skilzy 0.1.1

Official Python SDK and CLI for the Skilzy AI Skills Registry.

Skilzy Python SDK & CLI

The official Python SDK and command-line interface for interacting with the Skilzy AI Skills Registry.

This toolkit allows developers and AI agents to seamlessly discover, install, manage, and publish reusable skills through both a powerful CLI and a clean Python API.

---

🚀 Quick Start

Installation

pip install skilzy

CLI Usage

# Search for skills
skilzy search "pdf"

# Install a skill
skilzy install skilzy-admin/pdf-pro

# List installed skills
skilzy list

Python API Usage

import skilzy

# Search for skills
results = skilzy.search("pdf")

# Install a skill
skilzy.install("skilzy-admin/pdf-pro", overwrite=True)

# List installed skills
skilzy.list_skills()

---

📚 Table of Contents

• Installation
• Python SDK (Programmatic API)
  • Basic Usage
  • Available Functions
  • Error Handling
• CLI Reference
  • General Commands
  • Publishing & Account Management
• Examples

---

🐍 Python SDK (Programmatic API)

The Skilzy SDK provides a clean, Pythonic interface for all registry operations.

Basic Usage

Simply import the skilzy module to access all functionality:

import skilzy

# All functions are available directly on the module
skilzy.search("automation")
skilzy.install("author/skill-name")
skilzy.list_skills()

Available Functions

Discovery & Search

skilzy.search(query, author=None, keywords=None, sort_by="relevance", page=1, limit=10)

Search for skills in the registry.

import skilzy

# Simple search
results = skilzy.search("pdf")

# Advanced search with filters
results = skilzy.search(
    query="data processing",
    author="skilzy-admin",
    keywords=["csv", "excel"],
    limit=20
)

Returns: List of skill dictionaries

---

Installation & Management

skilzy.init(project_root=None)

Initialize a new skilzy.json tracking file in the current directory.

import skilzy

skilzy.init()

Returns: Dict with status and file path

---

skilzy.install(skill_name, path=None, overwrite=False, cat=False, insecure=False, project_root=None)

Download and install a skill.

import skilzy

# Basic installation
skilzy.install("skilzy-admin/pdf-pro")

# Install with custom options
skilzy.install(
    "skilzy-admin/pdf-pro",
    path="custom/path",
    overwrite=True,
    cat=True  # Print SKILL.md after install
)

Parameters:

• skill_name (str): Full skill name in format 'author/skill-name'
• path (str, optional): Custom installation path
• overwrite (bool): Replace existing installation if True
• cat (bool): Print SKILL.md content after installation
• insecure (bool): Disable SSL verification (use with caution)
• project_root (Path, optional): Project root directory

Returns: Dict with installation details

Raises:

• ValueError: Invalid skill name format
• FileExistsError: Directory exists and overwrite=False
• SkilzyError: API request failed

---

skilzy.list_skills(project_root=None)

List all installed skills tracked in skilzy.json.

import skilzy

installed = skilzy.list_skills()
# Prints a formatted table and returns dict of skills

Returns: Dict of installed skills with metadata

---

skilzy.remove_skill(skill_name, force=False, project_root=None)

Remove a skill and update tracking file.

import skilzy

# Interactive removal (prompts for confirmation)
skilzy.remove_skill("pdf-pro")

# Force removal (no confirmation)
skilzy.remove_skill("author/skill-name", force=True)

Parameters:

• skill_name (str): Name with or without author (e.g., 'pdf-pro' or 'author/pdf-pro')
• force (bool): Skip confirmation prompt if True

Returns: Dict with status message

---

skilzy.sync_skills(force=False, insecure=False, project_root=None)

Install all skills listed in skilzy.json (similar to npm install).

import skilzy

# Sync all skills
result = skilzy.sync_skills()

# Force reinstall all skills
result = skilzy.sync_skills(force=True)

print(f"Synced: {result['success_count']}")
print(f"Skipped: {result['skip_count']}")
print(f"Errors: {result['error_count']}")

Returns: Dict with sync summary (success_count, skip_count, error_count)

---

Authentication & Publishing

skilzy.login(api_key)

Save your API key for authenticated operations.

import skilzy

skilzy.login("sk_live_your_api_key_here")

Returns: Dict with status message

---

skilzy.publish(package_path, api_key=None)

Publish a new or updated skill to the registry.

import skilzy

# Publish a packaged skill
response = skilzy.publish("dist/my-skill.zip")

print(f"Published: {response['skill']} v{response['version']}")
print(f"Status: {response['status']}")

Returns: Dict with publish response (skill, version, status)

Raises:

• FileNotFoundError: Package file not found
• SkilzyAuthenticationError: Not authenticated

---

skilzy.me_whoami()

Validate the currently configured API key.

import skilzy

try:
    result = skilzy.me_whoami()
    print(f"Valid key: {result['key_prefix']}")
except skilzy.SkilzyAuthenticationError:
    print("Invalid API key")

Returns: Dict with validation status and key prefix

---

skilzy.me_skills(api_key=None)

List all skills you have published to the registry.

import skilzy

my_skills = skilzy.me_skills()
# Prints a table and returns list of your skills

Returns: List of skill dictionaries with metadata

---

Error Handling

The SDK uses specific exception types for different error scenarios:

import skilzy

try:
    skilzy.install("invalid-skill-name")
except skilzy.SkilzyAuthenticationError:
    print("Authentication failed - run skilzy.login() first")
except skilzy.SkilzyNotFound:
    print("Skill not found in registry")
except skilzy.SkilzyError as e:
    print(f"API error: {e}")
except ValueError as e:
    print(f"Invalid input: {e}")
except FileExistsError as e:
    print(f"File conflict: {e}")

Available Exception Classes:

• SkilzyError - Base exception for all SDK errors
• SkilzyAuthenticationError - 401 authentication failures
• SkilzyNotFound - 404 resource not found
• SkilzyPermissionError - 403 forbidden
• SkilzyConflictError - 409 conflicts
• SkilzyAPIError - General API errors

---

🖥️ CLI Reference

General Commands

skilzy init

Initialize a new skilzy.json tracking file in the current directory.

skilzy init

---

skilzy search <query>

Search for skills in the registry.

skilzy search "pdf"
skilzy search "automation" --author skilzy-admin
skilzy search "data" --keywords csv,excel

Options:

• --author <name> - Filter by author's username
• --keywords <k1,k2> - Comma-separated keywords

---

skilzy install <author/skill-name>

Download and install a skill into the local ./skills directory.

skilzy install skilzy-admin/pdf-pro
skilzy install skilzy-admin/pdf-pro --overwrite
skilzy install skilzy-admin/pdf-pro --cat
skilzy install skilzy-admin/pdf-pro --path custom/location

Options:

• --path <custom-path> - Install to a specific directory
• --overwrite - Overwrite destination if it exists
• --cat - Print the skill's SKILL.md content after installation
• --insecure - Disable SSL certificate verification

---

skilzy list

List all skills currently installed in the local ./skills directory.

skilzy list

---

skilzy remove <skill-name>

Remove a skill from the local installation.

skilzy remove pdf-pro
skilzy remove my-skill --force

Options:

• --force - Skip confirmation prompt

---

skilzy sync

Install all skills listed in skilzy.json (similar to npm install).

skilzy sync
skilzy sync --force

Options:

• --force - Reinstall all skills even if they exist
• --insecure - Disable SSL verification

---

Publishing & Account Management

skilzy login

Securely save your API key for authenticated commands.

skilzy login
skilzy login --api-key "sk_live_your_key_here"

Options:

• --api-key <key> - Provide the API key directly (otherwise prompted)

---

skilzy publish <path/to/package.skill>

Publish a new or updated skill to the registry. Requires authentication.

skilzy publish dist/my-skill.zip

---

skilzy me whoami

Validate the currently configured API key.

skilzy me whoami

---

skilzy me skills

List all skills you have published, showing version and review status.

skilzy me skills

---

📖 Examples

Example 1: Automated Skill Installation Script

import skilzy

# Initialize tracking
skilzy.init()

# Install multiple skills
skills_to_install = [
    "skilzy-admin/pdf-pro",
    "skilzy-admin/web-scraper",
]

for skill in skills_to_install:
    try:
        result = skilzy.install(skill, overwrite=True)
        print(f"✓ Installed {result['skill']} v{result['version']}")
    except skilzy.SkilzyError as e:
        print(f"✗ Failed to install {skill}: {e}")

# List what was installed
print("
Installed skills:")
skilzy.list_skills()

Example 2: Search and Interactive Install

import skilzy

# Search for PDF-related skills
results = skilzy.search("pdf", limit=5)

if results:
    print("Available PDF skills:")
    for i, skill in enumerate(results, 1):
        print(f"{i}. {skill['author']}/{skill['name']} - {skill['description']}")
    
    choice = input("
Enter number to install (or 'q' to quit): ")
    if choice.isdigit():
        selected = results[int(choice) - 1]
        skill_name = f"{selected['author']}/{selected['name']}"
        skilzy.install(skill_name)

Example 3: Sync Skills Across Environments

import skilzy

# On machine 1: Install skills normally
skilzy.install("author/skill-1")
skilzy.install("author/skill-2")
# This creates skilzy.json with all dependencies

# Commit skilzy.json to version control

# On machine 2: Just sync
result = skilzy.sync_skills()
print(f"Synced {result['success_count']} skills successfully")

Example 4: Publishing Workflow

import skilzy

# Authenticate
skilzy.login("sk_live_your_api_key")

# Publish your skill
try:
    response = skilzy.publish("dist/my-awesome-skill.zip")
    print(f"✓ Published {response['skill']} v{response['version']}")
    print(f"  Status: {response['status']}")
except skilzy.SkilzyAuthenticationError:
    print("Authentication failed. Check your API key.")
except skilzy.SkilzyConflictError:
    print("This version already exists. Bump your version number.")

# Check your published skills
my_skills = skilzy.me_skills()

---

🔧 Advanced Usage

Using the Low-Level Client

For more control, you can use the SkilzyClient class directly:

from skilzy import SkilzyClient, SkilzyError

# Create client with custom settings
client = SkilzyClient(
    api_key="your_key",
    base_url="https://api.skilzy.dev",
    verify_ssl=True
)

try:
    # Search
    results = client.search_skills(q="automation", limit=10)
    
    # Get skill details
    details = client.get_skill_details(author="skilzy-admin", skill_name="pdf-pro")
    
    # Get specific version
    version = client.get_skill_version(
        author="skilzy-admin",
        skill_name="pdf-pro",
        version="1.0.0"
    )
    
    # Download
    client.download_skill(
        author="skilzy-admin",
        skill_name="pdf-pro",
        version="1.0.0",
        output_path="downloads/pdf-pro.skill"
    )
except SkilzyError as e:
    print(f"Error: {e}")

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Homepage: https://github.com/skilzy/skilzy-python
• Issues: https://github.com/skilzy/skilzy-python/issues
• PyPI: https://pypi.org/project/skilzy/
• Registry: https://skilzy.ai

---

💡 Need Help?

• 📖 Check the documentation
• 🐛 Report bugs on GitHub Issues