skills

Documentation

Overview

Package skills provides types and interfaces for managing ToolHive skills.

Index

• Constants
• Variables
• type BuildOptions
• type BuildResult
• type Dependency
• type InfoOptions
• type InstallOptions
• type InstallResult
• type InstallStatus
• type InstalledSkill
• type ListOptions
• type ParseResult
  • func ParseSkillMD(content []byte) (*ParseResult, error)
• type PushOptions
• type Scope
• type SkillFrontmatter
• type SkillIndex
• type SkillIndexEntry
• type SkillInfo
• type SkillMetadata
• type SkillService
• type StringOrSlice
  • func (s *StringOrSlice) UnmarshalYAML(value *yaml.Node) error
• type UninstallOptions
• type ValidationResult
  • func ValidateSkillDir(path string) (*ValidationResult, error)

Constants

const MaxCompatibilityLength = 500

MaxCompatibilityLength is the maximum allowed length for the compatibility field.

const MaxDependencies = 100

MaxDependencies is the maximum number of dependencies allowed per skill. This prevents resource exhaustion from malicious or misconfigured skills.

const MaxDescriptionLength = 1024

MaxDescriptionLength is the maximum allowed length for the description field.

const MaxFrontmatterSize = 64 * 1024 // 64KB

MaxFrontmatterSize is the maximum size of frontmatter content in bytes. This prevents YAML parsing attacks (e.g., billion laughs).

const RecommendedMaxSkillMDLines = 500

RecommendedMaxSkillMDLines is the recommended maximum number of lines in SKILL.md. Exceeding this generates a warning, not an error.

Variables

var ErrInvalidFrontmatter = errors.New("invalid frontmatter")

ErrInvalidFrontmatter indicates that the SKILL.md frontmatter is malformed.

Types

type BuildOptions

type BuildOptions struct {
	// Path is the local directory path containing the skill definition.
	Path string `json:"path"`
	// Tag is the OCI tag to use for the built artifact.
	Tag string `json:"tag,omitempty"`
}

BuildOptions configures the behavior of the Build operation.

type BuildResult

type BuildResult struct {
	// Reference is the OCI reference of the built skill artifact.
	Reference string `json:"reference"`
}

BuildResult contains the outcome of a Build operation.

type Dependency

type Dependency struct {
	Reference string `json:"reference"`
}

Dependency represents an external skill dependency (OCI reference).

type InfoOptions

type InfoOptions struct {
	// Name is the skill name to look up.
	Name string `json:"name"`
}

InfoOptions configures the behavior of the Info operation.

type InstallOptions

type InstallOptions struct {
	// Name is the skill name or OCI reference to install.
	Name string `json:"name"`
	// Version is the specific version to install. Empty means latest.
	Version string `json:"version,omitempty"`
	// Scope is the installation scope.
	Scope Scope `json:"scope,omitempty"`
}

InstallOptions configures the behavior of the Install operation.

type InstallResult

type InstallResult struct {
	// Skill is the installed skill.
	Skill InstalledSkill `json:"skill"`
}

InstallResult contains the outcome of an Install operation.

type InstallStatus

type InstallStatus string

InstallStatus represents the current status of a skill installation.

const (
	// InstallStatusInstalled indicates a skill is fully installed and ready.
	InstallStatusInstalled InstallStatus = "installed"
	// InstallStatusPending indicates a skill installation is in progress.
	InstallStatusPending InstallStatus = "pending"
	// InstallStatusFailed indicates a skill installation has failed.
	InstallStatusFailed InstallStatus = "failed"
)

type InstalledSkill

type InstalledSkill struct {
	// Metadata contains the skill's metadata.
	Metadata SkillMetadata `json:"metadata"`
	// Scope is the installation scope (user or system).
	Scope Scope `json:"scope"`
	// Status is the current installation status.
	Status InstallStatus `json:"status"`
	// InstalledAt is the timestamp when the skill was installed.
	InstalledAt time.Time `json:"installed_at"`
	// Clients is the list of client identifiers the skill is installed for.
	// TODO: Refactor client.ClientApp to a shared package so it can be used here instead of []string.
	Clients []string `json:"clients,omitempty"`
}

InstalledSkill represents a skill that has been installed locally.

type ListOptions

type ListOptions struct {
	// Scope filters results by installation scope.
	Scope Scope `json:"scope,omitempty"`
}

ListOptions configures the behavior of the List operation.

type ParseResult

type ParseResult struct {
	Name          string
	Description   string
	Version       string
	AllowedTools  []string
	License       string
	Compatibility string
	Metadata      map[string]string
	Requires      []Dependency
	Body          []byte
}

ParseResult contains the parsed contents of a SKILL.md file.

func ParseSkillMD

func ParseSkillMD(content []byte) (*ParseResult, error)

ParseSkillMD parses a SKILL.md file and extracts frontmatter and body.

type PushOptions

type PushOptions struct {
	// Reference is the OCI reference to push.
	Reference string `json:"reference"`
}

PushOptions configures the behavior of the Push operation.

type Scope

type Scope string

Scope represents the scope at which a skill is installed.

const (
	// ScopeUser indicates a skill installed for the current user.
	ScopeUser Scope = "user"
	// ScopeSystem indicates a skill installed system-wide.
	ScopeSystem Scope = "system"
)

type SkillFrontmatter

type SkillFrontmatter struct {
	Name          string            `yaml:"name"`
	Description   string            `yaml:"description"`
	Version       string            `yaml:"version,omitempty"`
	AllowedTools  StringOrSlice     `yaml:"allowed-tools,omitempty"`
	Requires      StringOrSlice     `yaml:"toolhive.requires,omitempty"`
	License       string            `yaml:"license,omitempty"`
	Compatibility string            `yaml:"compatibility,omitempty"`
	Metadata      map[string]string `yaml:"metadata,omitempty"`
}

SkillFrontmatter represents the raw YAML frontmatter from a SKILL.md file.

type SkillIndex

type SkillIndex struct {
	// Skills is the list of available skills.
	Skills []SkillIndexEntry `json:"skills"`
}

SkillIndex represents a collection of available skills from a remote index.

type SkillIndexEntry

type SkillIndexEntry struct {
	// Metadata contains the skill's metadata.
	Metadata SkillMetadata `json:"metadata"`
	// Repository is the OCI repository reference for the skill.
	Repository string `json:"repository"`
}

SkillIndexEntry represents a single skill entry in a remote skill index.

type SkillInfo

type SkillInfo struct {
	// Metadata contains the skill's metadata.
	Metadata SkillMetadata `json:"metadata"`
	// Installed indicates whether the skill is currently installed.
	Installed bool `json:"installed"`
	// InstalledSkill is set if the skill is installed.
	InstalledSkill *InstalledSkill `json:"installed_skill,omitempty"`
}

SkillInfo contains detailed information about a skill.

type SkillMetadata

type SkillMetadata struct {
	// Name is the unique name of the skill.
	Name string `json:"name"`
	// Version is the semantic version of the skill.
	Version string `json:"version"`
	// Description is a human-readable description of the skill.
	Description string `json:"description"`
	// Author is the skill author or maintainer.
	Author string `json:"author"`
	// Tags is a list of tags for categorization.
	Tags []string `json:"tags,omitempty"`
}

SkillMetadata contains metadata about a skill.

type SkillService

type SkillService interface {
	// List returns all installed skills matching the given options.
	List(ctx context.Context, opts ListOptions) ([]InstalledSkill, error)
	// Install installs a skill from a remote source.
	Install(ctx context.Context, opts InstallOptions) (*InstallResult, error)
	// Uninstall removes an installed skill.
	Uninstall(ctx context.Context, opts UninstallOptions) error
	// Info returns detailed information about a skill.
	Info(ctx context.Context, opts InfoOptions) (*SkillInfo, error)
	// Validate checks whether a skill definition is valid.
	Validate(ctx context.Context, path string) (*ValidationResult, error)
	// Build builds a skill from a local directory into an OCI artifact.
	Build(ctx context.Context, opts BuildOptions) (*BuildResult, error)
	// Push pushes a built skill artifact to a remote registry.
	Push(ctx context.Context, opts PushOptions) error
}

SkillService defines the interface for managing skills.

type StringOrSlice

type StringOrSlice []string

StringOrSlice is a custom type that can unmarshal from either a YAML string (space-delimited per spec, or comma-delimited for compatibility) or a YAML array.

func (*StringOrSlice) UnmarshalYAML

func (s *StringOrSlice) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler for StringOrSlice. Per the Agent Skills spec, allowed-tools is space-delimited, but we also support comma-delimited for compatibility with existing skills.

type UninstallOptions

type UninstallOptions struct {
	// Name is the skill name to uninstall.
	Name string `json:"name"`
	// Scope is the scope from which to uninstall.
	Scope Scope `json:"scope,omitempty"`
}

UninstallOptions configures the behavior of the Uninstall operation.

type ValidationResult

type ValidationResult struct {
	// Valid indicates whether the skill definition is valid.
	Valid bool `json:"valid"`
	// Errors is a list of validation errors, if any.
	Errors []string `json:"errors,omitempty"`
	// Warnings is a list of non-blocking validation warnings, if any.
	Warnings []string `json:"warnings,omitempty"`
}

ValidationResult contains the outcome of a Validate operation.

func ValidateSkillDir

func ValidateSkillDir(path string) (*ValidationResult, error)

ValidateSkillDir validates a skill directory at the given path. I/O errors are returned as error; validation issues are returned in ValidationResult.