Back to Documentation
Getting Started

Your First Skill Call

This tutorial walks you through installing the SDK, discovering skills, executing them, and handling responses. By the end, you will have a working integration with SkillRouter.

Choose your language:
1

Install the SDK

Install the official SkillRouter SDK for your language using your preferred package manager.

Terminal
pip install skillrouter
Requires Python 3.8+. Also available via conda: conda install -c conda-forge skillrouter
2

Discover Skills

Use sr.discover() to find the best skill for a given task. The discovery engine uses vector similarity search to match your natural language query against the skill registry.

discover.py
from skillrouter import SkillRouter

sr = SkillRouter()  # Reads SKILLROUTER_API_KEY from env

# Discover skills matching a natural language query
results = sr.discover("send a Slack message")

for skill in results.skills:
    print(f"{skill.name} (score: {skill.relevance_score:.2f})")
    print(f"  Provider: {skill.provider}")
    print(f"  Parameters: {[p.name for p in skill.parameters]}")
    print()

How discovery works

The discover() method converts your query into a vector embedding and searches against all registered skills. Results are ranked by relevance score (0.0 to 1.0) and include metadata like the provider, required parameters, and estimated latency.

3

Execute a Skill

Once you have identified the right skill, call sr.execute() with the skill ID and required parameters. SkillRouter handles the underlying API calls, authentication with the third-party provider, and retries.

execute.py
# Execute a specific skill by ID
result = sr.execute(
    skill_id="slack_send_message",
    params={
        "channel": "#general",
        "text": "Hello from SkillRouter!"
    }
)

print(f"Success: {result.success}")
print(f"Status: {result.status}")
print(f"Latency: {result.latency_ms}ms")
print(f"Data: {result.data}")

Response Fields

  • success — Boolean result
  • status — HTTP-like status
  • data — Provider response
  • latency_ms — Execution time

Execution Features

  • Auto-retry on failure
  • Provider auth handled
  • Request validation
  • Execution logging
4

Handle Responses and Errors

The SDK provides typed exceptions for common error scenarios. Always wrap execution calls in error handling to gracefully manage failures.

errors.py
from skillrouter import SkillRouter
from skillrouter.exceptions import (
    SkillNotFoundError,
    ExecutionError,
    AuthenticationError,
    RateLimitError,
)

sr = SkillRouter()

try:
    result = sr.execute(
        skill_id="slack_send_message",
        params={"channel": "#general", "text": "Hello!"}
    )
    print(f"Message sent: {result.data}")

except AuthenticationError:
    print("Invalid API key. Check your SKILLROUTER_API_KEY.")

except SkillNotFoundError as e:
    print(f"Skill not found: {e.skill_id}")

except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")

except ExecutionError as e:
    print(f"Execution failed: {e.message}")
    print(f"Error code: {e.code}")
    print(f"Execution ID: {e.execution_id}")  # Useful for debugging

Execution IDs

Every execution returns an execution_id. Save this for debugging — you can look up execution details, logs, and traces in your dashboard or via the API.

Full Working Example

Here is a complete end-to-end example that discovers a skill, inspects its parameters, and executes it with proper error handling.

full_example.py
from skillrouter import SkillRouter
from skillrouter.exceptions import ExecutionError

sr = SkillRouter()  # Uses SKILLROUTER_API_KEY env var

# Step 1: Discover the best skill for your task
results = sr.discover("send an email")
best_skill = results.skills[0]
print(f"Using skill: {best_skill.name} ({best_skill.id})")

# Step 2: Inspect required parameters
for param in best_skill.parameters:
    required = " (required)" if param.required else ""
    print(f"  {param.name}: {param.type}{required}")

# Step 3: Execute with parameters
try:
    result = sr.execute(
        skill_id=best_skill.id,
        params={
            "to": "team@example.com",
            "subject": "Weekly Report",
            "body": "Here is the weekly report from our AI agent.",
        }
    )

    if result.success:
        print(f"Email sent successfully in {result.latency_ms}ms")
        print(f"Message ID: {result.data['message_id']}")
    else:
        print(f"Execution returned failure: {result.status}")

except ExecutionError as e:
    print(f"Failed: {e.message} (code: {e.code})")

Next Steps

Skill Discovery

Advanced discovery patterns

Skillsets & MCPs

Combine skills into workflows