skills

Documentation

Overview

Package skills discovers user-defined skills (SKILL.md files) and surfaces them to the chat agent in three ways:

• Advertise: a lightweight catalog (name + description) is composed into the system prompt via Augment, so the model knows which skills exist.
• Expand: when the user's message mentions a skill by `$name`, Expand pulls that skill's full body into the turn.
• ExpandInvocation: when the user invokes `/name args`, ExpandInvocation turns the skill body plus args into the agent turn.

Like projectctx, this is a layered capability gated by a feature flag (features.skills) and wired at the chat surface — the core agent loop is untouched.

Index

• func Augment(base string, sk []Skill) string
• func Expand(input string, sk []Skill) (string, []string)
• func ExpandInvocation(s Skill, args string) string
• type Skill
  • func Load(cwd string) ([]Skill, error)

Functions

func Augment

func Augment(base string, sk []Skill) string

Augment appends a catalog of available skills (name + description only) to a base system prompt, so the model is aware of them. Returns base unchanged when there are no skills.

func Expand

func Expand(input string, sk []Skill) (string, []string)

Expand scans input for `$name` references to known skills and returns the input prefixed with the body of each referenced skill (in order of first mention, each at most once), plus the names applied. When no known skill is referenced it returns input unchanged and a nil slice — an unrecognized `$foo` is left alone.

func ExpandInvocation

func ExpandInvocation(s Skill, args string) string

ExpandInvocation renders one slash-invoked skill body with optional trailing arguments. The skill body is always included, and args are appended in a labelled section so the model can distinguish workflow instructions from the user's task-specific input.

Types

type Skill

type Skill struct {
	Name        string // invocation name (lowercased); referenced as $name or /name
	Description string // one-line summary, shown in the advertised catalog
	Body        string // full instructions, expanded when invoked
	Path        string // source SKILL.md path
}

Skill is one discovered skill: how it's invoked, what it's for, and the body that gets expanded into a turn when invoked.

func Load

func Load(cwd string) ([]Skill, error)

Load discovers skills for a session rooted at cwd. It looks in:

• ~/.neo/skills/<name>/SKILL.md user-global
• <repo-or-cwd>/.neo/skills/<name>/SKILL.md project (overrides global)

A skill's invocation name is its frontmatter `name`, falling back to the directory name. Project skills override global ones of the same name. Missing directories are skipped; only a genuine read/parse error is returned.