skills

Documentation

Overview

Package skills implements discovery of Agent Skills. A skill is a folder containing a SKILL.md whose YAML frontmatter (name, description) is parsed at startup; the body is read lazily by the model via the Read tool.

The on-disk format intentionally matches the contract shared by the standard, so a folder authored for any of them drops in unchanged.

Index

• func ExpandShorthand(input string) string
• func Uninstall(name, destBase string) (string, error)
• type GitHubLocation
  • func ParseGitHubTreeURL(rawURL string) (*GitHubLocation, error)
• type Installer
  • func NewInstaller() *Installer
  • func (i *Installer) InstallFromGitHub(ctx context.Context, rawURL, destBase string, overwrite bool) (string, error)
• type Service
  • func New(cfg *config.Config) *Service
  • func (s *Service) Errors() []domain.SkillLoadError
  • func (s *Service) List() []domain.Skill
  • func (s *Service) Load(_ context.Context) error

Functions

func ExpandShorthand

func ExpandShorthand(input string) string

ExpandShorthand turns shorthand install targets into full GitHub tree URLs. Accepted forms:

• "<skill>" → https://github.com/inference-gateway/skills/tree/main/skills/<skill>
• "<org>/<skill>" → https://github.com/<org>/skills/tree/main/skills/<skill>
• any http(s):// URL → returned unchanged

Anything else (3+ slash-separated segments, empty segments, etc.) is returned unchanged so ParseGitHubTreeURL produces its existing error.

func Uninstall

func Uninstall(name, destBase string) (string, error)

Uninstall removes the skill folder named `name` from `destBase`. The name must match the on-disk skill-name regex (lowercase letters, digits and hyphens) so callers can't smuggle in path-traversal payloads like `../`. Returns an error if the folder doesn't exist or isn't a directory.

Types

type GitHubLocation

type GitHubLocation struct {
	Owner string
	Repo  string
	Ref   string
	Path  string
}

GitHubLocation identifies a directory inside a public GitHub repository, parsed out of a /tree/<ref>/<path> URL.

func ParseGitHubTreeURL

func ParseGitHubTreeURL(rawURL string) (*GitHubLocation, error)

ParseGitHubTreeURL accepts URLs of the form

https://github.com/<owner>/<repo>/tree/<ref>/<path-to-skill>

Refs containing a literal "/" (e.g. "feature/foo" branches) are not supported; pass the URL of a tag or single-segment branch instead.

type Installer

type Installer struct {
	Client  *http.Client
	APIBase string
	RawBase string
}

Installer downloads a skill folder from a public GitHub repo into a local destination directory.

func NewInstaller

func NewInstaller() *Installer

NewInstaller returns an Installer pointed at github.com with a 30s HTTP timeout. Tests substitute APIBase / RawBase to point at httptest.Server.

func (*Installer) InstallFromGitHub

func (i *Installer) InstallFromGitHub(ctx context.Context, rawURL, destBase string, overwrite bool) (string, error)

InstallFromGitHub downloads the skill folder at rawURL into <destBase>/<dirname>/, where dirname is the last path segment of the repo URL. Existing folders are rejected unless overwrite is true.

The downloaded folder is post-validated with loadSkill — if frontmatter fails the spec checks, the folder is removed and the validation error is returned. There is never a half-installed state.

Returns the absolute path of the installed skill on success.

type Service

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

Service discovers SKILL.md files and exposes the parsed metadata. Loading is gated by config.AgentSkillsConfig — when disabled the scan is skipped entirely so there is zero token / IO cost.

func New

func New(cfg *config.Config) *Service

New returns a Service bound to cfg. Call Load to populate the skill list.

func (*Service) Errors

func (s *Service) Errors() []domain.SkillLoadError

Errors returns a defensive copy of validation failures from the last Load.

func (*Service) List

func (s *Service) List() []domain.Skill

List returns a defensive copy of the loaded skills.

func (*Service) Load

func (s *Service) Load(_ context.Context) error

Load scans both project and user-global skill directories, parses frontmatter, validates each skill, and populates the in-memory list. When skills are disabled in config the call is a no-op and returns nil.