Documentation
¶
Overview ¶
Package skill provides discovery and lazy loading of SKILL.md files.
A skill is a Markdown file beginning with a YAML frontmatter block:
--- name: fix-tests description: Fix failing tests in a Go project. tags: [testing, go] --- # Full instructions body...
Discovery reads only the frontmatter block; the body is loaded on demand through Catalog.LoadBody. This keeps startup cost proportional to the number of skills (a few hundred bytes each) rather than the total body size.
Index ¶
Constants ¶
const MaxDescriptionLen = 1024
MaxDescriptionLen is the maximum permitted skill description length.
const MaxNameLen = 64
MaxNameLen is the maximum permitted skill name length.
Variables ¶
var ErrNoFrontmatter = errors.New("skill: no frontmatter")
ErrNoFrontmatter is returned when a file does not begin with a `---` line.
var ErrUnterminatedFrontmatter = errors.New("skill: unterminated frontmatter")
ErrUnterminatedFrontmatter is returned when a `---` opener is not closed.
Functions ¶
This section is empty.
Types ¶
type Catalog ¶
type Catalog struct {
// contains filtered or unexported fields
}
Catalog is an immutable collection of discovered skills.
func NewCatalog ¶
NewCatalog builds a Catalog from a slice of skills, deduplicating by name (last write wins) and sorting by name for deterministic iteration.
func ScanDir ¶
ScanDir walks dir for `SKILL.md` files, parsing frontmatter from each. A non-existent or empty dir returns an empty catalog and a nil error, allowing callers to opt in to skill discovery without branching.
Files with missing/invalid frontmatter are skipped and recorded in the returned warnings slice; they do not abort the scan.
func (*Catalog) LoadBody ¶
LoadBody reads and returns the raw markdown body of the named skill — everything after the closing `---` line of the frontmatter. The file is re-opened on each call; the body is not cached.
type Frontmatter ¶
type Frontmatter struct {
Name string `yaml:"name"`
Description string `yaml:"description"`
Tags []string `yaml:"tags,omitempty"`
Version string `yaml:"version,omitempty"`
}
Frontmatter is the YAML metadata at the top of a SKILL.md file.
func ParseFrontmatter ¶
func ParseFrontmatter(r io.Reader) (Frontmatter, int64, error)
ParseFrontmatter consumes only the YAML frontmatter block from r and returns the parsed Frontmatter and the byte offset at which the body begins.
The reader is advanced exactly to the byte after the closing `---` line; the body is not read. ErrNoFrontmatter is returned if the first non-empty line is not `---`. ErrUnterminatedFrontmatter is returned if EOF is reached before a closing `---`.
func (Frontmatter) Validate ¶
func (f Frontmatter) Validate() error
Validate returns an error if required fields are missing or malformed.
type LoadSkillTool ¶
type LoadSkillTool struct {
Catalog *Catalog
}
LoadSkillTool exposes a *Catalog to the agent loop as the `load_skill` tool. The tool returns the raw markdown body of the named skill on demand, supporting the progressive-disclosure pattern: only the frontmatter summary is in the system prompt; full instructions are loaded lazily.
func (*LoadSkillTool) Description ¶
func (t *LoadSkillTool) Description() string
Description returns the LLM-facing description.
func (*LoadSkillTool) Execute ¶
func (t *LoadSkillTool) Execute(_ context.Context, params json.RawMessage) (string, error)
Execute returns the markdown body of the named skill, or an error listing the available names when the requested name is unknown.
func (*LoadSkillTool) Name ¶
func (t *LoadSkillTool) Name() string
Name returns the tool identifier.
func (*LoadSkillTool) Parallel ¶
func (t *LoadSkillTool) Parallel() bool
Parallel reports that load_skill is safe to run concurrently — it only reads files.
func (*LoadSkillTool) Schema ¶
func (t *LoadSkillTool) Schema() json.RawMessage
Schema returns the JSON schema for the tool's parameters.
type Skill ¶
type Skill struct {
// Path is the absolute filesystem path to the SKILL.md file.
Path string
// Frontmatter is the parsed YAML metadata.
Frontmatter Frontmatter
// BodyOffset is the byte offset at which the markdown body begins
// (i.e. the byte immediately after the closing `---` line).
BodyOffset int64
}
Skill describes a single discovered SKILL.md file.
func (Skill) Description ¶
Description returns the skill's frontmatter description.
Source Files