Documentation
¶
Overview ¶
Package skill loads and parses flat-file skill definitions. Skills are markdown files with TOML frontmatter enclosed in +++ delimiters. They are text-only — no code is executed. Their content is injected into the agent's system prompt so the LLM knows what skills are available.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var AllowedSubdirs = []string{"references", "templates", "scripts"}
AllowedSubdirs lists the permitted subdirectory prefixes within a skill directory.
Functions ¶
func BuildPromptSection ¶
BuildPromptSection assembles a list of skills into a formatted system-prompt section. Returns an empty string if skills is empty.
func ScanSubFiles ¶ added in v0.36.0
ScanSubFiles walks allowed subdirectories within a skill directory and returns sorted relative paths to all regular files found.
func ValidateSubpath ¶ added in v0.36.0
ValidateSubpath validates and resolves a relative file path within a skill directory. It ensures the path is under an allowed subdirectory and cannot escape the skill directory.
Types ¶
type MatchContext ¶
type MatchContext struct {
MessageText string // the user's message
SkillName string // set when a schedule fires for a specific skill
}
MatchContext carries the per-message information needed to decide which skills apply.
type Skill ¶
type Skill struct {
Name string
Description string
Version string
Triggers []string // raw trigger strings from frontmatter — informational only
ParsedTriggers []Trigger // parsed at load time; the sole input to MatchSkills
Requires SkillRequires
Body string // markdown body — everything after the closing +++
Source string // file path, for logging/debugging
// MaxToolRounds optionally lowers the engine's per-turn tool-round budget
// for turns this skill explicitly drives (a scheduled run, or a lone
// command match). The unit is *rounds*, not calls — one round may fan out
// to many parallel tool calls, matching the agent-level max_tool_rounds
// knob it tightens. 0 means unset (the agent/engine budget applies), and
// the cap only ever lowers that budget: an operator's agent-level ceiling
// is never widened by a skill, which the agent itself can author.
MaxToolRounds int
// SubFileNames lists relative paths to sub-files within a subdirectory-form
// skill (e.g. "references/oauth.md", "templates/greeting.txt"). Sorted.
// Empty for flat-file skills.
SubFileNames []string
// Dir is the skill directory path. Non-empty only for subdirectory-form
// skills (containing SKILL.md). Empty for flat-file skills.
Dir string
}
Skill represents a loaded skill file.
func LoadDir ¶
LoadDir scans dir for skill files and returns all valid ones. It looks for:
- Top-level *.md files
- Subdirectories containing a SKILL.md file
A non-existent directory is not an error — it returns an empty slice (safe for fresh installs). Files that fail to parse are logged as warnings and skipped; other valid files in the directory are still loaded.
func MatchSkills ¶
func MatchSkills(skills []Skill, ctx MatchContext) []Skill
MatchSkills returns the subset of skills that should be injected for this message. Skills with no triggers are always included. Otherwise, a skill is included if any of its triggers match the context.
Matching keys off ParsedTriggers, never the raw Triggers strings. Every Skill reaching this function is expected to have come from ParseFile, which fills ParsedTriggers whenever Triggers is non-empty (and rejects the skill outright if a trigger fails to parse). A hand-built Skill that sets Triggers but leaves ParsedTriggers nil therefore looks trigger-less and is injected into *every* message — construct such values with skill/skilltest rather than a bare literal. See TestMatchSkills_RawTriggersAreNotHonoured.
func MergeSkills ¶
MergeSkills combines global and agent-specific skills. Agent-specific skills override global skills with the same name. Skills without a matching name in the other set are included as-is.
type SkillRequires ¶
type SkillRequires struct {
Tools []string `toml:"tools"`
}
SkillRequires lists optional capabilities a skill depends on.
type Trigger ¶
type Trigger struct {
Type TriggerType
Raw string // original string, e.g. "command:briefing"
Command string // lowercase command name, for TriggerCommand only
}
Trigger is a parsed trigger specification from a skill's frontmatter.
func ParseTrigger ¶
ParseTrigger parses a raw trigger string like "command:briefing" into a Trigger.
func ParseTriggers ¶
ParseTriggers parses a slice of raw trigger strings. Returns an error if any trigger is invalid.
type TriggerType ¶
type TriggerType int
TriggerType classifies how a skill is activated.
const ( // TriggerCommand activates on a user command like "/briefing" or "!briefing". TriggerCommand TriggerType = iota // TriggerSchedule activates when the scheduler fires for the matching skill. TriggerSchedule )
Source Files
Directories