skills

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Mar 14, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// MaxNameLength is the maximum length for skill names.
	MaxNameLength = 64

	// MaxDescriptionLength is the maximum length for descriptions.
	MaxDescriptionLength = 1024

	// SkillFileName is the required filename for skill definitions.
	SkillFileName = "SKILL.md"
)

--- Constants and limits ---

Variables

View Source 
var (
	ErrMissingName        = &SkillError{Message: "skill name is required"}
	ErrNameTooLong        = &SkillError{Message: "skill name exceeds maximum length"}
	ErrMissingDescription = &SkillError{Message: "skill description is required"}
	ErrDescriptionTooLong = &SkillError{Message: "skill description exceeds maximum length"}
	ErrSkillNotFound      = &SkillError{Message: "skill not found"}
	ErrInvalidFrontmatter = &SkillError{Message: "invalid YAML frontmatter"}
	ErrMissingSkillMD     = &SkillError{Message: "SKILL.md file not found"}
)

Predefined errors

Functions

This section is empty.

Types

type FileType 

type FileType string

FileType categorizes bundled files. 

const (
	FileTypeScript    FileType = "script"    // executable scripts (scripts/)
	FileTypeReference FileType = "reference" // documentation (references/)
	FileTypeAsset     FileType = "asset"     // templates, icons, etc (assets/)
	FileTypeOther     FileType = "other"     // uncategorized files
)

type Frontmatter 

type Frontmatter struct {
	Name        string `json:"name" yaml:"name"`
	Description string `json:"description" yaml:"description"`

	// Optional fields
	Version      string   `json:"version,omitempty" yaml:"version,omitempty"`
	Author       string   `json:"author,omitempty" yaml:"author,omitempty"`
	License      string   `json:"license,omitempty" yaml:"license,omitempty"`
	AllowedTools []string `json:"allowed_tools,omitempty" yaml:"allowed_tools,omitempty"`

	// Capabilities lists the capability tags these skills provides (used for scheduler matching)
	Capabilities []string `json:"capabilities,omitempty" yaml:"capabilities,omitempty"`
}

Frontmatter represents the YAML frontmatter of a SKILL.md file.

func (*Frontmatter) Validate 

func (f *Frontmatter) Validate() error

Validate checks if the frontmatter is valid.

type Loader 

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

Loader handles discovering and loading skills from the filesystem.

func NewLoader 

func NewLoader(opts ...LoaderOption) *Loader

NewLoader creates a new skills loader with the given options.

func (*Loader) GlobalDir 

func (l *Loader) GlobalDir() string

GlobalDir returns the global skills directory path.

func (*Loader) ListSkills 

func (l *Loader) ListSkills(ctx context.Context) (string, error)

ListSkills returns a formatted list of available skills.

func (*Loader) LoadAll 

func (l *Loader) LoadAll(ctx context.Context) ([]*Skill, error)

LoadAll loads all skills from both global and project directories. Project skills take precedence over global skills with the same name.

func (*Loader) LoadMetadataOnly 

func (l *Loader) LoadMetadataOnly(ctx context.Context) ([]SkillMetadata, error)

LoadMetadataOnly loads only skill metadata for system prompt injection. This is more efficient as it doesn't load full content.

func (*Loader) LoadSkill 

func (l *Loader) LoadSkill(ctx context.Context, name string) (*Skill, error)

LoadSkill loads a specific skill by name.

func (*Loader) LoadSkillContent 

func (l *Loader) LoadSkillContent(_ context.Context, skill *Skill) (string, error)

LoadSkillContent loads the full content of a skill's SKILL.md. Use this for on-demand loading when the skill is triggered.

func (*Loader) ProjectDir 

func (l *Loader) ProjectDir() string

ProjectDir returns the project-level skills directory path.

type LoaderOption 

type LoaderOption func(*Loader)

LoaderOption configures the loader.

func WithGlobalSkillsDir 

func WithGlobalSkillsDir(dir string) LoaderOption

WithGlobalSkillsDir sets the global skills directory. Default: paths.ResolveGolemSkillsDir() (~/.echoryn/golem/skills)

func WithProjectSkillsDir 

func WithProjectSkillsDir(dir string) LoaderOption

WithProjectSkillsDir sets the project-level skills directory. Default: .echoryn/skills

type Parser 

type Parser struct{}

Parser handles parsing of SKILL.md files.

func NewParser 

func NewParser() *Parser

NewParser creates a new SKILL.md parser.

func (*Parser) ExtractSection 

func (p *Parser) ExtractSection(body, heading string) string

ExtractSection extracts a specific markdown section by heading. Heading matching is case-insensitive.

func (*Parser) ExtractTOC 

func (p *Parser) ExtractTOC(body string) string

ExtractTOC extracts all markdown headings and returns a formatted table of contents. Each heading is indented based on its level (H1 = no indent, H2 = 2 spaces, etc.).

func (*Parser) Parse 

func (p *Parser) Parse(data []byte) (*Frontmatter, string, error)

Parse parses SKILL.md content bytes and extracts frontmatter and body.

func (*Parser) ParseFile 

func (p *Parser) ParseFile(path string) (*Frontmatter, string, error)

ParseFile parses a SKILL.md file from the given path. Returns the frontmatter, markdown body, and any error.

func (*Parser) ParseMetadataOnly 

func (p *Parser) ParseMetadataOnly(path string) (*Frontmatter, error)

ParseMetadataOnly extracts only the frontmatter without loading the full body. This is more efficient for initial skill discovery.

type Registry 

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

Registry manages loaded skills and provides lookup functionality.

func NewRegistry 

func NewRegistry(loader *Loader, opts ...RegistryOption) *Registry

NewRegistry creates a new skills registry.

func (*Registry) Count 

func (r *Registry) Count() int

Count returns the number of registered skills.

func (*Registry) FindMatchingSkill 

func (r *Registry) FindMatchingSkill(query string) *SkillMetadata

FindMatchingSkill finds a skill that matches the given query using keyword scoring.

func (*Registry) GenerateSkillsInstructions 

func (r *Registry) GenerateSkillsInstructions() string

GenerateSkillsInstructions generates the <skills_instructions> XML section.

func (*Registry) GenerateSystemPromptSection 

func (r *Registry) GenerateSystemPromptSection() string

GenerateSystemPromptSection generates the <available_skills> XML section for system prompts.

func (*Registry) Get 

func (r *Registry) Get(ctx context.Context, name string) (*Skill, error)

Get retrieves a skill by name, loading it on demand if needed.

func (*Registry) GetContent 

func (r *Registry) GetContent(ctx context.Context, name string) (string, error)

GetContent retrieves the full content of a skill.

func (*Registry) GetMetadata 

func (r *Registry) GetMetadata() []SkillMetadata

GetMetadata returns all loaded skill metadata.

func (*Registry) Initialize 

func (r *Registry) Initialize(ctx context.Context) error

Initialize loads all skill metadata from configured directories.

func (*Registry) Names 

func (r *Registry) Names() []string

Names returns all registered skill names.

func (*Registry) Reload 

func (r *Registry) Reload(ctx context.Context) error

Reload refreshes the registry with updated skills from disk.

func (*Registry) StartWatching 

func (r *Registry) StartWatching(ctx context.Context) error

StartWatching begins monitoring skill directories for changes.

func (*Registry) StopWatching 

func (r *Registry) StopWatching() error

StopWatching stops monitoring skill directories.

type RegistryOption 

type RegistryOption func(*Registry)

RegistryOption configures the Registry.

func WithAutoWatch 

func WithAutoWatch(enabled bool) RegistryOption

WithAutoWatch enables automatic file watching after Initialize. When enabled, the registry will automatically reload when SKILL.md files change.

type Skill 

type Skill struct {
	// Name is the skill identifier (from YAML front matter).
	Name string `json:"name" yaml:"name"`

	// Description describes what the skill does and when to use it.
	Description string `json:"description" yaml:"description"`

	// Path is the absolute path to the skill directory.
	Path string `json:"path"`

	// Content is the full markdown body (loaded on demand).
	Content string `json:"-"`

	// Files are additional files bundled with the skill.
	Files []SkillFile `json:"files,omitempty"`

	// Source indicates where the skill was loaded from.
	Source SkillSource `json:"source"`

	// LoadedAt is when the skill was loaded.
	LoadedAt time.Time `json:"loaded_at"`
}

Skill represents a loaded skill with its metadata and content.

func (*Skill) SkillMDPath 

func (s *Skill) SkillMDPath() string

SkillMDPath returns the path to SKILL.md within the skill directory.

func (*Skill) ToMetaData 

func (s *Skill) ToMetaData() SkillMetadata

ToMetaData extracts lightweight metadata from a full skill.

type SkillError 

type SkillError struct {
	SkillPath string
	Message   string
	Err       error
}

SkillError is the base error type for skill operations.

func (*SkillError) Error 

func (e *SkillError) Error() string

func (*SkillError) Unwrap 

func (e *SkillError) Unwrap() error

type SkillFile 

type SkillFile struct {
	// RelPath is the path relative to skill directory.
	RelPath string `json:"rel_path"`

	// AbsPath is the absolute filesystem path
	AbsPath string `json:"abs_path"`

	// Type indicates the file category
	Type FileType `json:"type"`
}

SkillFile represents an additional file bundled with a skill.

type SkillMetadata 

type SkillMetadata struct {
	Name         string      `json:"name"`
	Description  string      `json:"description"`
	Source       SkillSource `json:"source"`
	Path         string      `json:"path"`
	Capabilities []string    `json:"capabilities,omitempty"`
}

SkillMetadata is the lightweight metadata loaded at startup. Only name and description are included to minimize context usage.

type SkillSource 

type SkillSource string

SkillSource indicates where a skill was loaded from. 

const (
	SourceGlobal  SkillSource = "global"  // ~/.echoryn/golem/skills/
	SourceProject SkillSource = "project" // <project>/.echoryn/skills/
	SourceBuiltin SkillSource = "builtin" // compiled into binary
)

type Watcher 

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

Watcher monitors skill directories for changes and triggers reloads.

func NewWatcher 

func NewWatcher(registry *Registry, dirs []string, opts ...WatcherOption) (*Watcher, error)

NewWatcher creates a new file system watcher for skill directories.

func (*Watcher) Start 

func (w *Watcher) Start(ctx context.Context) error

Start begins watching the configured directories. It runs in a background goroutine and returns immediately.

func (*Watcher) Stop 

func (w *Watcher) Stop() error

Stop gracefully stops the watcher.

type WatcherOption 

type WatcherOption func(watcher *Watcher)

WatcherOption configures the Watcher.

func WithDebounce 

func WithDebounce(d time.Duration) WatcherOption

WithDebounce sets the debounce duration for batching rapid file changes. Default 100ms.

Source Files

View all Source files

Directories

Path Synopsis
Package middleware provides the Skills middleware for integrating the skills system into Eino-based agents.
 Package middleware provides the Skills middleware for integrating the skills system into Eino-based agents.

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.