loader

package
v1.6.3 Latest Latest
Warning

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

 Go to latest Published: Sep 14, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package skill provides types and utilities for loading and managing agent skills. Skills follow the Anthropic Agent Skills pattern - folders containing a SKILL.md file with YAML frontmatter and markdown instructions that agents can discover and load dynamically.

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"
)

Registry 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 Frontmatter 

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

	// Optional fields
	AllowedTools []string `yaml:"allowed-tools,omitempty"`
	Version      string   `yaml:"version,omitempty"`
	Author       string   `yaml:"author,omitempty"`
	License      string   `yaml:"license,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 filesystem.

func NewLoader 

func NewLoader(opts ...LoaderOption) *Loader

NewLoader creates a new skills loader with the given options.

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(ctx 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.

type LoaderOption 

type LoaderOption func(*Loader)

LoaderOption configures the Loader.

func WithProjectSkillsDir 

func WithProjectSkillsDir(dir string) LoaderOption

WithProjectSkillsDir sets the project-level skills directory. Default: .chat-agent/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. Useful for getting specific parts of skill instructions.

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 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.

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. This uses simple keyword matching for skill selection.

func (*Registry) GenerateSkillsInstructions 

func (r *Registry) GenerateSkillsInstructions() string

GenerateSkillsInstructions generates instructions for using skills.

func (*Registry) GenerateSystemPromptSection 

func (r *Registry) GenerateSystemPromptSection() string

GenerateSystemPromptSection generates the skills 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 skills from configured directories.

func (*Registry) Names 

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

Names returns all registered skill names.

type RegistryOption 

type RegistryOption func(*Registry)

RegistryOption configures the Registry.

type Skill 

type Skill struct {
	// Name is the skill identifier (from YAML frontmatter)
	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 content (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 metadata from a full skill.

type SkillError 

type SkillError struct {
	SkillPath string
	Message   string
	Err       error
}

Error types for skill validation.

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 SkillFileType `json:"type"`
}

SkillFile represents an additional file bundled with a skill.

type SkillFileType 

type SkillFileType string

SkillFileType categorizes bundled files. 

const (
	// FileTypeScript for executable scripts (scripts/)
	FileTypeScript SkillFileType = "script"

	// FileTypeReference for documentation (references/)
	FileTypeReference SkillFileType = "reference"

	// FileTypeAsset for templates, icons, etc (assets/)
	FileTypeAsset SkillFileType = "asset"

	// FileTypeOther for uncategorized files
	FileTypeOther SkillFileType = "other"
)

type SkillMetadata 

type SkillMetadata struct {
	Name        string      `json:"name"`
	Description string      `json:"description"`
	Source      SkillSource `json:"source"`
	Path        string      `json:"path"`
}

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 for ~/.chat-agent/skills/
	SourceGlobal SkillSource = "global"

	// SourceProject for .chat-agent/skills/
	SourceProject SkillSource = "project"

	// SourceBuiltin for built-in skills
	SourceBuiltin SkillSource = "builtin"

	// SourcePlugin for plugin-provided skills
	SourcePlugin SkillSource = "plugin"
)

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.