skills

package
v0.16.21 Latest Latest
Warning

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

 Go to latest Published: Jul 6, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package skills owns the catalogue of skills shipped with sprout. The library/ subdirectory is embedded into the binary at compile time; the discovery functions in this file are the single source of truth that every higher-level consumer routes through:

  • pkg/configuration uses Builtins() to seed Config.Skills
  • pkg/agent uses ReadContent() to load a skill's body for the LLM
  • cmd/skill uses Builtins() to render `sprout skill list`

The previous arrangement kept the embed in pkg/agent and the registry in pkg/configuration with no cross-reference, so adding a skill on disk silently did nothing until a hand-written entry was also added to defaultSkills(). New skills now drop in by creating a directory under library/ with a valid SKILL.md frontmatter — nothing else.

Index

Constants

View Source 
const LegacyLogicalPath = "pkg/agent/skills"

LegacyLogicalPath is the pre-refactor location of embedded skills. Retained so the configuration prune step (which deletes config.Skills entries whose Path matches a builtin prefix but whose ID is no longer in the default set) recognises legacy paths persisted in older user configs and migrates them cleanly.

View Source 
const LogicalPath = "pkg/skills/library"

LogicalPath is the repo-relative path of the embedded library, used as the Path metadata on Builtin entries. Other layers (configuration prune logic, user-facing displays) check for this prefix to identify builtins. Exported so those callers don't hardcode a string that could go stale if the package moves.

View Source 
const OriginMetadataFile = ".sprout-origin.json"
View Source 
const SkillFileName = "SKILL.md"

SkillFileName is the file inside each skill directory whose YAML frontmatter supplies the skill's metadata. Exported so callers that resolve user/project skills from disk can reuse the same convention.

Variables

View Source 
var (
	ErrInvalidFrontmatter = errors.New("invalid skill frontmatter")
	ErrAlreadyInstalled   = errors.New("skill already installed")
	ErrNotInstalled       = errors.New("skill is not installed")
	ErrNotGitOrigin       = errors.New("skill origin is not a git repository")
	ErrGitNotAvailable    = errors.New("git binary not available on PATH")
)
View Source 
var ErrRegistryNotFound = errors.New("registry entry not found")

ErrRegistryNotFound is returned when a registry ID is not present.

Functions

func Builtins 

func Builtins() map[string]Builtin

Builtins walks the embedded library and returns one entry per skill directory whose SKILL.md frontmatter parses successfully. Directories without a SKILL.md, with malformed frontmatter, or with a missing name/description are skipped silently — the discovery test in this package asserts every shipped skill is valid, so silent skips in production runtime can only happen for skills added without going through the test gate.

func DefaultSkillsDir added in v0.16.18 

func DefaultSkillsDir() (string, error)

DefaultSkillsDir returns the canonical skills install dir. Honors SPROUT_SKILLS_DIR env override; otherwise returns <os.UserConfigDir>/sprout/skills (creating the parent sprout dir if needed).

func IDs 

func IDs() []string

IDs returns the sorted list of built-in skill IDs. Convenience for callers that just want the names (e.g. cmd/skill's list output).

func ReadContent 

func ReadContent(id string) (string, error)

ReadContent returns the full SKILL.md body for a built-in skill, including frontmatter. Callers responsible for activation (pkg/agent) pass this directly into the system prompt; the frontmatter is part of the message the LLM sees, matching the prior pkg/agent behaviour.

func RegistryOverrideForTest added in v0.16.18 

func RegistryOverrideForTest(r *Registry)

RegistryOverrideForTest allows tests to inject a registry instead of the embedded default. Pass nil to clear. Only intended for use in *_test.go.

Safe to call from parallel tests: the override is protected by a mutex. Use the defer pattern to ensure cleanup: 

RegistryOverrideForTest(fakeReg)
defer RegistryOverrideForTest(nil)

func SkillInstallDir added in v0.16.18 

func SkillInstallDir(skillID string) (string, error)

SkillInstallDir returns DefaultSkillsDir()/<skillID>. Errors from DefaultSkillsDir are returned so callers cannot silently fall back to a CWD-relative path.

func Uninstall added in v0.16.18 

func Uninstall(skillID string) error

Uninstall removes <skills_dir>/<skillID> entirely.

func ValidateFrontmatter added in v0.16.18 

func ValidateFrontmatter(fm SkillFrontmatter) error

ValidateFrontmatter ensures frontmatter is present and required fields are populated. Returns ErrInvalidFrontmatter (a sentinel error declared in install.go) when invalid.

Types

type Builtin 

type Builtin struct {
	ID          string
	Name        string
	Description string
	Path        string // logical path under the repo, e.g. pkg/skills/library/<id>
	Content     string
}

Builtin is the parsed metadata + body for a single embedded skill. Content is the entire SKILL.md including frontmatter; consumers that only want the body should strip the frontmatter themselves with a shared parser to avoid divergent interpretations of the format.

type InstallOptions added in v0.16.18 

type InstallOptions struct {
	Force bool
}

InstallOptions controls the behaviour of Install* functions.

type InstallResult added in v0.16.18 

type InstallResult struct {
	SkillID    string `json:"skill_id"`
	InstallDir string `json:"install_dir"`
	Origin     Origin `json:"origin"`
}

InstallResult describes what was installed.

func InstallFromGit added in v0.16.18 

func InstallFromGit(ctx context.Context, gitURL, ref string, opts InstallOptions) ([]InstallResult, error)

InstallFromGit clones a git repo and installs any SKILL.md skills found.

func InstallFromPath added in v0.16.18 

func InstallFromPath(srcPath string, opts InstallOptions) ([]InstallResult, error)

InstallFromPath copies a local file or directory into the skills dir.

func InstallFromRegistry added in v0.16.18 

func InstallFromRegistry(ctx context.Context, registryID string, opts InstallOptions) ([]InstallResult, error)

InstallFromRegistry installs a skill by registry ID from the embedded registry. It looks up the entry, clones the git repo (or uses a local path in test mode), extracts the skill subdirectory, and installs the found SKILL.md.

func InstallFromURL added in v0.16.18 

func InstallFromURL(ctx context.Context, url string, opts InstallOptions) ([]InstallResult, error)

InstallFromURL fetches a URL and installs the skill(s) found.

func Update added in v0.16.18 

func Update(ctx context.Context, skillID string, opts InstallOptions) ([]InstallResult, error)

Update refreshes an installed skill from its original source.

type Origin added in v0.16.18 

type Origin struct {
	Type        string    `json:"type"` // "git", "url", "path", "registry"
	URL         string    `json:"url,omitempty"`
	Path        string    `json:"path,omitempty"`
	RegistryID  string    `json:"registry_id,omitempty"`
	Ref         string    `json:"ref,omitempty"`
	CommitSHA   string    `json:"commit_sha,omitempty"`
	InstalledAt time.Time `json:"installed_at"`
}

Origin records how a skill was installed so Update knows where to refresh from.

func LoadOrigin added in v0.16.18 

func LoadOrigin(installDir string) (Origin, error)

LoadOrigin reads <installDir>/.sprout-origin.json.

type Registry added in v0.16.18 

type Registry struct {
	Version int             `json:"version"`
	Skills  []RegistryEntry `json:"skills"`
}

Registry is the decoded embedded registry.

func LoadRegistry added in v0.16.18 

func LoadRegistry() (*Registry, error)

LoadRegistry returns the embedded registry, decoded once.

func (*Registry) LookupByID added in v0.16.18 

func (r *Registry) LookupByID(id string) (*RegistryEntry, error)

LookupByID returns the registry entry for the given ID, or ErrRegistryNotFound.

type RegistryEntry added in v0.16.18 

type RegistryEntry struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	GitURL      string `json:"git_url"`
	GitRef      string `json:"git_ref"`
	PathInRepo  string `json:"path_in_repo"`
}

RegistryEntry is a single starter skill in the embedded registry.

type SkillFrontmatter added in v0.16.18 

type SkillFrontmatter struct {
	Name        string
	Description string
}

SkillFrontmatter is the typed view of a SKILL.md YAML frontmatter block. Both Name and Description are required and non-empty for a skill to be considered installable.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.