Documentation
¶
Overview ¶
Package skills loads file-backed skills and exposes them to a coding agent.
A skill is a directory named after the skill, containing a SKILL.md file with YAML frontmatter (name and description) and a Markdown body. Only the name and description enter the model's context up front; the body is injected on demand when the model calls the skill tool (see Registry.Tool). This keeps the initial context small while letting the model pull full instructions for the task at hand.
Skills are discovered from two roots: a user root that applies everywhere and a project root scoped to one workspace. A project skill overrides a user skill of the same name. Loading is decoupled from the agent: callers resolve the two roots and pass them to Load, then hand the resulting skills to the session.
Index ¶
- Constants
- func FormatActivatedContext(s Skill) string
- func IsExplicitInvocationText(text string) bool
- func Load(opts LoadOptions) (*Registry, []Diagnostic)
- func LoadFor(workspace string) (*Registry, []Diagnostic)
- func Roots(workspace string) (userDir, projectDir string)
- type Delta
- type Diagnostic
- type DynamicRegistry
- type LoadOptions
- type Registry
- func (r *Registry) DisplayExplicitInvocation(text string) string
- func (r *Registry) ExplicitInvocationSkill(text string) (Skill, bool)
- func (r *Registry) Len() int
- func (r *Registry) List() []Skill
- func (r *Registry) Lookup(name string) (Skill, bool)
- func (r *Registry) ResolveExplicitInvocation(text string) (loaded string, matched bool, err error)
- func (r *Registry) Revision() string
- func (r *Registry) Tool() agent.AgentTool
- type Skill
- type Source
Constants ¶
const ToolName = "skill"
ToolName is the advertised name of the skill-loading tool.
Variables ¶
This section is empty.
Functions ¶
func FormatActivatedContext ¶ added in v0.6.7
FormatActivatedContext renders the immutable Skill snapshot that remains in model context after activation, even when the tool result or explicit invocation that loaded it is later compacted out of conversation history.
func IsExplicitInvocationText ¶
IsExplicitInvocationText reports whether a text block was generated by ResolveExplicitInvocation. UI/history projections omit these blocks.
func Load ¶
func Load(opts LoadOptions) (*Registry, []Diagnostic)
Load discovers skills under the configured roots and returns a Registry. Project skills override user skills of the same name. Malformed or misnamed skills are skipped and reported as diagnostics rather than failing the load, so one bad skill does not hide the rest.
func LoadFor ¶
func LoadFor(workspace string) (*Registry, []Diagnostic)
LoadFor discovers the skills visible to one workspace, using Roots. Diagnostics are returned for a caller that surfaces them; an agent that only needs the usable skills can ignore them.
func Roots ¶
Roots returns the two roots skills are discovered from: the user-level root that applies everywhere, and the workspace root that overrides it. Either is empty when it does not apply — no home directory, or no workspace given — which Load treats as "skip that root".
The convention lives here, with the loader that consumes it, so an agent assembling its skills and a UI listing them can never disagree about where skills come from.
Types ¶
type Delta ¶
Delta describes the semantic change between two resolved registries. Added and Updated retain full Skill values so the caller can advertise their current discovery metadata. Removed contains stable names.
type Diagnostic ¶
type Diagnostic struct {
// Path is the SKILL.md (or directory) the problem concerns.
Path string
// Message explains why the skill was skipped.
Message string
}
Diagnostic reports a skill that could not be loaded, so the caller can surface the problem without failing the whole load.
type DynamicRegistry ¶
type DynamicRegistry struct {
// contains filtered or unexported fields
}
DynamicRegistry exposes one snapshot-aware Skill tool while atomically replacing the immutable Registry consulted by tool calls. The engine controls whether that tool is advertised for the current snapshot.
func NewDynamicRegistry ¶
func NewDynamicRegistry(initial *Registry) *DynamicRegistry
func (*DynamicRegistry) List ¶
func (d *DynamicRegistry) List() []Skill
func (*DynamicRegistry) Replace ¶
func (d *DynamicRegistry) Replace(next *Registry)
Replace atomically publishes next. A nil registry means an empty snapshot.
func (*DynamicRegistry) Snapshot ¶
func (d *DynamicRegistry) Snapshot() *Registry
Snapshot returns the current immutable registry.
func (*DynamicRegistry) Tool ¶
func (d *DynamicRegistry) Tool() agent.AgentTool
Tool returns a stable tool whose execution reads the registry snapshot that is current at call time.
type LoadOptions ¶
type LoadOptions struct {
// UserDir is the user-level skills root, applied to every workspace.
UserDir string
// ProjectDir is the workspace-scoped skills root. A skill here overrides a
// user skill of the same name.
ProjectDir string
}
LoadOptions names the two roots skills are discovered from. Either may be empty to skip that root. Both should be absolute paths to a skills directory, e.g. ~/.agents/skills and <workspace>/.agents/skills.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is an immutable, name-indexed set of loaded skills. It is built by Load and read concurrently; it is never mutated after construction.
func NewRegistry ¶
NewRegistry builds a Registry from an explicit set of skills, for callers that assemble or filter skills themselves rather than loading from disk. On a name collision the last skill wins.
func (*Registry) DisplayExplicitInvocation ¶ added in v0.6.4
DisplayExplicitInvocation converts an explicit invocation into a durable Markdown reference to its SKILL.md file. The UI can render the reference as a rich token while copying it remains useful plain text.
func (*Registry) ExplicitInvocationSkill ¶ added in v0.6.7
ExplicitInvocationSkill returns the exact Skill snapshot selected by a durable product-generated reference.
func (*Registry) ResolveExplicitInvocation ¶ added in v0.6.7
ResolveExplicitInvocation recognizes a product-generated SKILL.md reference and resolves it against the registry. The returned block follows the visible user text in the same message.
func (*Registry) Revision ¶
Revision fingerprints the complete resolved registry, including skill bodies and source paths. A body-only edit therefore advances the revision even when its model-visible name and description do not change.
func (*Registry) Tool ¶
Tool returns the agent tool that loads a skill's body on demand. The returned tool only reads registered skills; it makes no workspace changes, so callers should advertise it as read-only. On an unknown name it returns an error naming the valid skills, so the model corrects rather than guesses.
type Skill ¶
type Skill struct {
// Name is the stable identifier, equal to the skill's directory name. It is
// used for lookup and in the model-visible listing.
Name string
// Description is the model-visible note on when to use the skill. Required.
Description string
// License identifies the license applied to the skill when provided.
License string
// Compatibility describes environment requirements when provided.
Compatibility string
// Metadata contains standard extension metadata from the SKILL.md frontmatter.
Metadata map[string]string
// AllowedTools is the experimental, space-separated standard field. Or
// preserves it but does not use it to bypass the normal permission policy.
AllowedTools string
// Content is the SKILL.md body, injected verbatim when the skill is invoked.
// It is not part of the initial context.
Content string
// Dir is the absolute path to the skill's directory. Relative references in
// Content resolve from this directory.
Dir string
// Path is the absolute path to the SKILL.md file, for diagnostics.
Path string
// Source records which root the skill came from.
Source Source
}
Skill is one loaded skill: the metadata advertised to the model plus the body injected when the skill is invoked.
Source Files