SDK Reference

Go SDK

The official Go client for SkillRouter. Idiomatic Go with context support, structured errors, and zero external dependencies.

View on GitHub

Installation

Install the SkillRouter Go SDK using go get. Requires Go 1.21 or higher.

go get github.com/skillrouter/go-sdk

Quick Start

Create a client, discover a skill, and execute it -- all with proper error handling from the start.

package main

import (
	"context"
	"fmt"
	"log"

	skillrouter "github.com/skillrouter/go-sdk"
)

func main() {
	// Initialize the client
	client, err := skillrouter.NewClient("sr_your_api_key")
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()

	// Discover the best skill for a task
	result, err := client.Discover(ctx, "Send a welcome email to new users")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Skill: %s (confidence: %.2f)\n", result.Skill.Name, result.Confidence)

	// Execute the skill
	resp, err := client.Execute(ctx, result.Skill.ID, map[string]any{
		"to":      "user@example.com",
		"subject": "Welcome!",
		"body":    "Thanks for signing up.",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Status: %s\n", resp.Status)
}

Client Initialization

Use functional options to configure the client. All options except the API key are optional.

import (
	"time"
	skillrouter "github.com/skillrouter/go-sdk"
)

// With options
client, err := skillrouter.NewClient(
	"sr_your_api_key",
	skillrouter.WithBaseURL("https://api.skillrouter.dev"),
	skillrouter.WithTimeout(30 * time.Second),
	skillrouter.WithMaxRetries(3),
)

// Or read from SKILLROUTER_API_KEY environment variable
client, err := skillrouter.NewClientFromEnv()

Core Methods

Discover(ctx, query, ...opts)

Finds the best matching skill for a natural language query. Accepts functional options for filtering.

result, err := client.Discover(ctx, "Process a credit card payment",
	skillrouter.WithCategory("payments"),
	skillrouter.WithTopK(3),
	skillrouter.WithThreshold(0.8),
)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("Best match: %s (%.2f)\n", result.Skill.ID, result.Confidence)

// Iterate over multiple matches
for _, match := range result.Matches {
	fmt.Printf("  %s: %.2f\n", match.Skill.Name, match.Confidence)
}

Execute(ctx, skillID, params)

Executes a skill with the given parameters. Parameters are passed as map[string]any.

resp, err := client.Execute(ctx, "stripe-checkout", map[string]any{
	"amount":         2999,
	"currency":       "usd",
	"customer_email": "buyer@example.com",
})
if err != nil {
	log.Fatal(err)
}

fmt.Printf("Status: %s\n", resp.Status)
fmt.Printf("Latency: %dms\n", resp.LatencyMs)

// Unmarshal data into a struct
var payment struct {
	PaymentID string `json:"payment_id"`
	Status    string `json:"status"`
}
if err := resp.UnmarshalData(&payment); err != nil {
	log.Fatal(err)
}
fmt.Printf("Payment ID: %s\n", payment.PaymentID)

ListSkills(ctx, ...opts)

Returns a paginated list of available skills with optional filters.

skills, err := client.ListSkills(ctx,
	skillrouter.WithCategory("payments"),
	skillrouter.WithProvider("stripe"),
	skillrouter.WithPage(1),
	skillrouter.WithPerPage(20),
)
if err != nil {
	log.Fatal(err)
}

for _, skill := range skills.Items {
	fmt.Printf("%s: %s\n", skill.ID, skill.Name)
}
fmt.Printf("Total: %d\n", skills.Total)

Error Handling

The SDK uses idiomatic Go error handling. Use errors.As to inspect specific error types.

import (
	"errors"
	skillrouter "github.com/skillrouter/go-sdk"
)

resp, err := client.Execute(ctx, "stripe-checkout", params)
if err != nil {
	var authErr *skillrouter.AuthenticationError
	var rateErr *skillrouter.RateLimitError
	var validErr *skillrouter.ValidationError
	var execErr *skillrouter.ExecutionError
	var notFound *skillrouter.SkillNotFoundError

	switch {
	case errors.As(err, &authErr):
		log.Fatal("Check your API key")

	case errors.As(err, &rateErr):
		log.Printf("Rate limited. Retry after %s", rateErr.RetryAfter)

	case errors.As(err, &validErr):
		for _, e := range validErr.Errors {
			log.Printf("Field %s: %s", e.Field, e.Message)
		}

	case errors.As(err, &notFound):
		log.Printf("Skill not found: %s", notFound.SkillID)

	case errors.As(err, &execErr):
		log.Printf("Execution failed: %s", execErr.Message)

	default:
		log.Printf("Unexpected error: %v", err)
	}
}

Tip: All error types implement the error interface and include an Unwrap() method for use with errors.Is and errors.As.

Next Steps

Quick Start Guide GitHub Repository