skill

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package skill loads skills, prompts that the model or the user can invoke, and renders them for an invocation.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrNotFound              = errors.New("skill not found")
	ErrModelInvocationDenied = errors.New("skill cannot be invoked by the model")
	ErrUserInvocationDenied  = errors.New("skill cannot be invoked by the user")
)

Functions

func Listing

func Listing(skills []Spec, usage map[string]float64) string

Listing fills the budget with the most used skills first but prints them sorted by name, so the text changes only when the set of skills does, not as usage scores decay. It sits in the cached prefix of every request.

func ValidName

func ValidName(name string) bool

Types

type Catalog

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

Catalog is immutable; reloading builds a new one.

func NewCatalog

func NewCatalog(specs []Spec) *Catalog

NewCatalog keeps the first skill of each name, so callers pass skills in order of precedence.

func (*Catalog) Active

func (c *Catalog) Active(cwd string) *Catalog

Active may walk the workspace to match Paths, so a conversation computes it once and offers the same skills to the user and the model.

func (*Catalog) Get

func (c *Catalog) Get(name string) (Spec, bool)

func (*Catalog) Invoke

func (c *Catalog) Invoke(ctx context.Context, in InvokeInput) (*Invocation, error)

func (*Catalog) List

func (c *Catalog) List() []Spec

type Invocation

type Invocation struct {
	Spec   Spec
	Prompt string
	Fork   bool
	Agent  string
	// AllowedTools and Model are set only for a privileged skill.
	AllowedTools []string
	Model        string
}

type InvokeInput

type InvokeInput struct {
	Name      string
	Args      string
	SessionID string
	By        Invoker
}

type Invoker

type Invoker int
const (
	ByModel Invoker = iota
	ByUser
)

type Spec

type Spec struct {
	Name        string
	Description string
	WhenToUse   string

	// FilePath is reread on every invocation unless the skill is frozen.
	// Bundled skills have none.
	FilePath string
	// BaseDir is where the skill's relative references resolve.
	BaseDir string
	// Source is "builtin", "user" or "project", shown to the user.
	Source string
	// Privileged lets the skill run its commands, allow tools and pick a
	// model. Only trusted skills get it.
	Privileged bool

	DisableModelInvocation bool
	DisableUserInvocation  bool
	ArgumentHint           string

	// Context is "fork" for a skill that runs in a sub-agent, else "inline".
	Context string
	Agent   string
	// Model overrides the model of a forked skill's sub-agent.
	Model        string
	AllowedTools []string
	// Paths, if set, activate the skill only in a workspace containing a
	// match.
	Paths []string
	// contains filtered or unexported fields
}

func Bundled

func Bundled(baseDir string) []Spec

func LoadDir

func LoadDir(dir string) ([]Spec, []error)

LoadDir loads each *.md file in dir and each subdirectory with a SKILL.md at any depth below it, named after the subdirectory. A missing dir holds no skills.

func LoadFile

func LoadFile(path, name string) (Spec, error)

LoadFile uses name unless the frontmatter sets one.

func (Spec) Forked

func (s Spec) Forked() bool

func (Spec) Freeze

func (s Spec) Freeze() (Spec, error)

Freeze snapshots the file so later edits don't change the skill. Project skills are frozen on load, so what runs is what the user trusted.

func (Spec) Privileges

func (s Spec) Privileges() []string

Privileges lists, for the user to review, what the skill does only when privileged: the commands it runs, the tools it allows and the model it picks.

type UsageTracker

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

UsageTracker persists invocation counts so the listing can favor skills used often and recently.

func NewUsageTracker

func NewUsageTracker(path string) (*UsageTracker, error)

func (*UsageTracker) Record

func (t *UsageTracker) Record(name string, at time.Time) error

func (*UsageTracker) Scores

func (t *UsageTracker) Scores(now time.Time) map[string]float64

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL