Documentation
¶
Overview ¶
Package skills discovers SKILL.md files in a project and exposes each one to an agentloop run as a retrievable document.
The model learns a skill EXISTS from a one-line entry in the system prompt and from skillList(); it pulls the full instructions with skillGet(name) when it decides the skill applies. Bodies never sit in the prompt otherwise, which is the point — a project can carry a dozen detailed skills without any of them costing context until one is actually used.
This differs from the CLI convention the package was ported from, where a skill is expanded into the turn only when the USER types $name or /name. Here the agent retrieves its own skills mid-run, which fits a loop whose whole design is pulling detail on demand rather than front-loading it.
Like projectctx, this is layered: nothing in the core imports it. An application opts in by loading skills and adding the packs to its SandboxBuilder.
sk, err := skills.Load(cwd) // err is advisory; sk may be usable caps := append(agentloop.DefaultCapabilities(client, ""), skills.Capabilities(sk)...)
Index ¶
Constants ¶
const DefaultDir = ".agentloop/skills"
DefaultDir is the project-relative directory searched for skill directories when Loader.Dir is empty.
const DefaultMaxBytes = 256 * 1024
DefaultMaxBytes caps one skill body when Loader.MaxBytes is zero. A body is only ever fetched on demand, so this is generous compared with projectctx's cap on files that ride along in every prompt.
const FileName = "SKILL.md"
FileName is the file that defines a skill inside its directory.
Variables ¶
This section is empty.
Functions ¶
func Capabilities ¶
func Capabilities(sk []Skill) []agentloop.Capability
Capabilities wraps discovered skills as agentloop Capabilities, one per skill, ready to append to the slice a DefaultSandboxBuilder gets.
One capability each rather than one for all of them is deliberate: Capability.Name is what a per-session allowlist (BuildContext.EnabledCapabilities) matches on, so this is what lets an application enable a skill for one session and not another.
func Packs ¶
Packs turns discovered skills into sandbox packs, one per skill.
Each pack installs no JS functions. It contributes a single catalog line to the system prompt and registers its body as the help entry for its name, which is what makes skillGet(name) return the full instructions. Keeping the body out of the Prompt is the whole design: the model pays for a skill's detail only when it asks for it.
Types ¶
type Loader ¶
type Loader struct {
// Dir is the skills directory, relative to the project root. Empty
// uses DefaultDir. An absolute path is used as-is, for an
// application that keeps skills outside the checkout.
Dir string
// GlobalDir is an optional user-global skills directory, loaded
// first so a project skill of the same name overrides it. Empty
// means none — same reasoning as projectctx.Loader.GlobalDir: a
// library should not read $HOME unless asked.
GlobalDir string
// MaxBytes caps one skill body. Zero uses DefaultMaxBytes;
// negative disables truncation.
MaxBytes int
}
Loader discovers skills. The zero value is usable and searches <project root>/.agentloop/skills.
func (Loader) Load ¶
Load discovers skills for a session rooted at cwd. Each immediate subdirectory of the skills directory that contains a FileName becomes one skill, named by its frontmatter `name` or, failing that, the directory name. Project skills override global ones of the same name, and the result is sorted by name.
The error is advisory in the same way projectctx.Load's is: skills that parsed cleanly come back alongside it, so one malformed SKILL.md costs the run that skill rather than all of them.
type Skill ¶
type Skill struct {
// Name is the retrieval name: skillGet(Name). Lowercased, and
// restricted to characters that read cleanly as an identifier.
Name string
// Description is the one-line summary shown in the prompt catalog
// and in skillList(). Falls back to the body's opening line when
// the frontmatter omits it.
Description string
// Body is the full instruction text, minus frontmatter.
Body string
// Path is the absolute source path, for the application's logs.
Path string
}
Skill is one discovered SKILL.md.
Source Files