skill

README

Go Skill Discovery Library

A high-performance, token-efficient discovery system for LLMs.

Overview

This library provides a minimalist, SQL-based mechanism for LLMs to discover and invoke tools ("skills"). It is designed to minimize token usage in the initial system prompt by providing a compact index and allowing the LLM to query for details on demand.

Features

• Token-Efficient Index: GetIndex() returns a highly compact string (e.g., files(read,write), net(ping)) for the initial context.
• SQL-Based Discovery: LLMs can query the catalog view to retrieve detailed parameter schemas only when needed.
• Idempotent Registration: Register() handles upserts and auto-provisions categories.
• Minimalist Schema: Uses cats, skills, params tables and a catalog view.

Usage

Installation

go get github.com/tinywasm/skill

Initialization

Initialize the store with any *sql.DB connection (e.g., modernc.org/sqlite).

package main

import (
	"context"
	"database/sql"
	"fmt"
	"log"

	"github.com/tinywasm/skill"
	_ "modernc.org/sqlite"
)

func main() {
	db, _ := sql.Open("sqlite", ":memory:") // or file path
	store := skill.NewStore(db)

	// Initialize schema
	if _, err := db.Exec(store.GetSchemaDescription()); err != nil {
		log.Fatal(err)
	}
}

Registering Skills

ctx := context.Background()

mySkill := skill.Skill{
    Category: "weather",
    Name:     "check",
    Info:     "Get current weather",
    Parameters: []skill.Parameter{
        {Name: "city", Type: "string", Info: "City name", Required: true},
    },
}

if err := store.Register(ctx, mySkill); err != nil {
    log.Fatal(err)
}

LLM Integration

1. Initial Context

Inject the compact index and instructions into your system prompt.

index, _ := store.GetIndex(ctx)
// index example: "weather(check), files(read,write)"

systemPrompt := fmt.Sprintf(skill.LLMInstruction, index)

The skill.LLMInstruction constant provides the standard prompt:

"Available: [INDEX]. Query catalog table for args schema. Example: SELECT args FROM catalog WHERE name='read';"

2. Skill Discovery

When the LLM needs to use a tool, it can query the catalog view or you can use Search() programmatically.

// Programmatic search
skills, _ := store.Search(ctx, "weather")

3. Execution

The LLM can query for the arguments schema directly:

SELECT args FROM catalog WHERE name='check';

Returns JSON: [{"n":"city","t":"string","r":true,"d":"City name"}]

Schema

• cats: id, name (unique)
• skills: id, cat_id, name (unique), info
• params: id, skill_id, name, type, info, req
• catalog (VIEW): cat, name, info, args (JSON array of parameters)

Documentation

Index

• Constants
• type Parameter
• type Skill
• type Store
  • func NewStore(db *sql.DB) *Store
  • func (s *Store) GetIndex(ctx context.Context) (string, error)
  • func (s *Store) GetSchemaDescription() string
  • func (s *Store) Register(ctx context.Context, skill Skill) error
  • func (s *Store) Search(ctx context.Context, query string) ([]Skill, error)

Constants

const LLMInstruction = "Available: %s. Query catalog table for args schema. Example: SELECT args FROM catalog WHERE name='read';"

LLMInstruction is the prompt template for LLMs.

Types

type Parameter

type Parameter struct {
	Name     string `json:"n"` // Name
	Type     string `json:"t"` // Type
	Info     string `json:"d"` // Description/Info
	Required bool   `json:"r"` // Required
}

Parameter defines an argument for a Skill. JSON tags match the compact format used in the 'catalog' view to save tokens.

type Skill

type Skill struct {
	Name       string      `json:"name"`       // Matches 'name' in catalog
	Category   string      `json:"category"`   // Matches 'cat' in catalog (mapped)
	Info       string      `json:"info"`       // Matches 'info' in catalog
	Parameters []Parameter `json:"parameters"` // Matches 'args' in catalog (mapped)
}

Skill represents a tool available to the LLM.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store provides access to the skill database.

func NewStore

func NewStore(db *sql.DB) *Store

NewStore creates a new Store with the given database connection.

func (*Store) GetIndex

func (s *Store) GetIndex(ctx context.Context) (string, error)

GetIndex returns a compact string representation of available skills. Format: cat1(skill1,skill2), cat2(skill3)

func (*Store) GetSchemaDescription

func (s *Store) GetSchemaDescription() string

GetSchemaDescription returns the SQL DDL commands to create the database schema.

func (*Store) Register

func (s *Store) Register(ctx context.Context, skill Skill) error

Register adds a new skill or updates an existing one. It is idempotent, auto-creates categories, upserts the skill, and replaces parameters.

func (*Store) Search

func (s *Store) Search(ctx context.Context, query string) ([]Skill, error)

Search queries the catalog view for skills matching the query. It maps the JSON 'args' column to the Skill.Parameters field.