skill

Documentation

Overview

Package skill implements Agent Skills for the harness: folders of instructions (SKILL.md) plus optional bundled resources, loaded by the agent ON DEMAND instead of stuffed into the system prompt — progressive disclosure (see ../../docs/specs/SKILLS.md). The format is the open Agent Skills spec (https://agentskills.io/specification) verbatim, so skills written for Claude Code / Codex / Gemini CLI load here unmodified.

The package is deliberately an orchestration-layer feature: the loop never changes. Discovery happens before agent.Run, and the whole runtime surface is ONE extra tool (Tool) whose description carries the Level-1 listing.

Index

• Constants
• func LoadForUser(ctx context.Context, sb sandbox.Sandbox, s *Skill) (string, error)
• func ProjectDir(root string) string
• func Tool(skills []*Skill, sb sandbox.Sandbox, ctxWindow int) agent.Tool
• func UserDir() string
• type Skill
  • func Discover(src Sources) (skills []*Skill, warnings []string)
  • func Load(dir string) (s *Skill, warnings []string, err error)
• type Sources

Constants

const (
	// StageDir is where a skill's bundled files land inside the sandbox, as a
	// project-root-relative path: StageDir/<name>/<resource>. One predictable
	// place, stated in the load header, so the model never hunts for scripts.
	StageDir = ".skills"
)

Functions

func LoadForUser

func LoadForUser(ctx context.Context, sb sandbox.Sandbox, s *Skill) (string, error)

LoadForUser force-loads one skill at the USER's explicit request (the TUI's /skills picker) rather than the model's: it stages the skill's bundled files and returns the same instructions text the `skill` tool would return, for the front-end to inject ahead of the next user message. The enabled/disabled LISTING state is deliberately not consulted — an explicit pick loads regardless of whether the model can see the skill listed. Caveat: the `skill` tool keeps its own per-run dedup state, so a model that later calls skill(<name>) anyway receives the body a second time.

func ProjectDir

func ProjectDir(root string) string

ProjectDir is the repo-local skills layer for a given project root, at the vendor-neutral .agents/skills path (the one Codex and Gemini CLI also scan). Callers on an UNTRUSTED run must pass "" instead: a skill body is standing instructions injected into the agent's context, and a hostile checkout must not get that power (docs/specs/SKILLS.md §D3).

func Tool

func Tool(skills []*Skill, sb sandbox.Sandbox, ctxWindow int) agent.Tool

Tool builds the single `skill` meta-tool over the discovered set. Its description carries the Level-1 listing (every skill's name + description); invoking it returns the skill's full SKILL.md body (Level 2) and lazily stages its bundled files into the sandbox at .skills/<name>/ so the agent's ordinary read_file/run tools cover Level 3. The handler runs HOST-side (the go_doc precedent): skill folders are operator configuration, not workspace content — the sandbox only ever receives a staged COPY.

ctxWindow is the model's context window in tokens (0 = unknown), used only to budget the listing. Callers with an empty skill set should not install the tool at all, keeping skill-free runs byte-identical to today.

func UserDir

func UserDir() string

UserDir is the operator-level skills layer shared by every binary that wires skills: $XDG_CONFIG_HOME/driver-os/skills (the same $XDG/driver-os convention the council corpus uses). Empty when the config dir can't be resolved — Discover treats that as an absent layer.

Types

type Skill

type Skill struct {
	Name        string            // == the folder's base name (spec requirement)
	Description string            // what it does AND when to use it — the sole trigger signal
	Dir         string            // absolute host path of the skill folder
	Body        string            // SKILL.md content below the frontmatter
	Meta        map[string]string // passthrough: license, compatibility, metadata.*
	Resources   []string          // slash-relative paths of bundled files, sorted
}

Skill is one parsed, validated skill folder.

func Discover

func Discover(src Sources) (skills []*Skill, warnings []string)

Discover loads every valid skill across the source layers and returns the merged, name-sorted set plus human-readable warnings (invalid skills, collisions, oversize findings). It never fails: no sources, no skills.

func Load

func Load(dir string) (s *Skill, warnings []string, err error)

Load parses and validates one skill folder. A spec-invalid folder returns a nil Skill and a reason — callers warn and SKIP, they never fail the run (Gemini CLI semantics: a broken skill is a degraded mode, not a crash). warnings carries non-fatal findings (oversized body, skipped resources).

type Sources

type Sources struct {
	UserDir    string   // e.g. $XDG_CONFIG_HOME/driver-os/skills
	ProjectDir string   // e.g. <root>/.agents/skills; "" when untrusted
	Explicit   []string // -skills entries: parent dirs OR single skill folders
}

Sources names the three discovery layers, in precedence order: an explicit -skills entry beats a project skill beats a user skill on a name collision (the more deliberate choice wins). An empty field skips that layer — callers set ProjectDir to "" on an -untrusted run, because a cloned repo must not inject standing instructions (docs/specs/SKILLS.md §D3).