skill

package
v1.4.2 Latest Latest
Warning

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

Go to latest
Published: Aug 11, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package skill provides filesystem-based skill discovery, frontmatter parsing, and ranked search shared by CLI and MCP adapters.

Skills are directories containing a SKILL.md file with YAML frontmatter. Discovery walks the built-in ~/.agents/skills directory plus any directories configured in skills.toml, and deduplicates by skill name.

Plane: shared

Index

Constants

View Source
const (
	DefaultSearchLimit = 8
	MaxSearchLimit     = 32
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Catalog added in v1.4.2

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

Catalog is one prioritized, deduplicated set of skills shared by adapters.

func LoadCatalog added in v1.4.2

func LoadCatalog(paths []string) (Catalog, error)

LoadCatalog discovers a catalog from prioritized filesystem roots.

func NewCatalog added in v1.4.2

func NewCatalog(groups ...[]Skill) Catalog

NewCatalog merges skill groups in priority order and sorts the selected skills by their exact frontmatter names.

func (Catalog) Find added in v1.4.2

func (c Catalog) Find(query string, limit int) ([]Skill, error)

Find returns skills ranked for a natural-language query.

func (Catalog) Get added in v1.4.2

func (c Catalog) Get(name string) (Skill, error)

Get returns one skill by its exact, case-sensitive frontmatter name.

func (Catalog) List added in v1.4.2

func (c Catalog) List() []Skill

List returns the selected skills in name order.

type Config added in v1.4.2

type Config struct {
	// Global lists extra skills directories, searched for every invocation
	// (CLI and MCP).
	Global []string `toml:"global"`
}

Config controls additional skill discovery roots beyond the built-in default.

The built-in default is the .agents convention only: ~/.agents/skills. Configured entries are appended after it, in the order listed, and are therefore lower priority. A leading "~" expands to the user's home directory (done in GlobalDiscoveryPaths against the passed home).

func LoadConfig added in v1.4.2

func LoadConfig(path string) (Config, error)

LoadConfig reads skills discovery configuration from path. A missing file returns an empty Config with no error. Entries are trimmed, blank entries dropped, and paths cleaned; "~" is left for GlobalDiscoveryPaths to expand.

type DiscoveryPath added in v1.4.2

type DiscoveryPath struct {
	Dir     string
	Builtin bool
}

DiscoveryPath is one skills root directory. Builtin marks the ~/.agents/skills default; configured extras are not built-in and may legitimately be absent on a given machine (worth warning about, but not fatal).

func GlobalDiscoveryPaths added in v1.4.2

func GlobalDiscoveryPaths(home string, cfg Config) []DiscoveryPath

GlobalDiscoveryPaths returns user-global discovery paths in priority order, starting with the built-in .agents convention followed by configured extras. A leading "~" in a configured entry expands against home; when home is empty such entries are skipped rather than resolved to the current directory.

type Meta

type Meta struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description"`
	Category    string `yaml:"category"`
}

Meta holds the parsed frontmatter fields from a SKILL.md file.

func ParseFrontmatter

func ParseFrontmatter(content []byte) (Meta, []byte)

ParseFrontmatter extracts YAML frontmatter from content. On parse error, returns empty Meta and the original content (never panics).

type Skill

type Skill struct {
	Name        string
	Description string
	Category    string
	Source      string // absolute path of the discovery directory
	Path        string // absolute path to SKILL.md
	Body        string // frontmatter-stripped content
}

Skill represents a discovered skill with its metadata and source location.

func GetSkill

func GetSkill(paths []string, name string) (*Skill, error)

GetSkill returns the skill matching the given frontmatter name, using priority order. Returns an error wrapping fs.ErrNotExist if no matching skill is found.

func ListSkills

func ListSkills(paths []string) ([]Skill, error)

ListSkills walks all discovery paths and returns all skills, deduplicated by name. First-seen wins (paths earlier in the slice have higher priority). Returns skills sorted by Name.

func SearchSkills added in v1.4.2

func SearchSkills(skills []Skill, query string, limit int) ([]Skill, error)

SearchSkills validates a natural-language query and returns ranked skills that match at least one query token.

Jump to

Keyboard shortcuts

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