Documentation
¶
Overview ¶
Package skill provides registerable capability bundles for jess agents, wired via jess.WithSkills and vendor-free (no agentcore types in its API).
A Skill is a unit of behavior an agent can opt into: a name and description (the agent sees both in its system prompt), a system-prompt contribution (instructions about how/when to use the skill), and zero-or-more tool implementations (the actual callable surface).
Skills are not a replacement for tools — they're a way to bundle a tool or set of tools with the instructions the model needs to use them well. A "web research" skill might contribute a system prompt block ("When asked to research something, follow up with a web_search then summarize three sources") plus a web_search tool. The model sees both together; the host hasn't had to custom-prompt for each tool.
Loading model:
- Direct registration: a Set is a collection of Skills; Set.Add appends. Hosts build Sets programmatically when skills come from in-process Go code.
- Filesystem loading: NewFilesystemLoader walks a directory looking for SKILL.md files (layout mirrors Claude Code's skill plugins — markdown frontmatter declares name + description + tools, body becomes the system-prompt contribution). A loader returns a Set the host hands to jess.
Integration:
- Hand a Set to an agent via jess.WithSkills(set). jess converts the Set's system prompts and tools into the harness inside its anti-corruption layer; this package itself stays vendor-free (no agentcore types in its API).
Hosts that want runtime add/remove (a /skill add command, say) keep their own Set and rebuild the Agent on change. Hot-loading without rebuild is out of scope for v0 — agentcore doesn't yet expose runtime tool re-registration.
Status: pre-1.0; the in-memory Set and the SKILL.md filesystem loader are shipped. API may change before v1.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FilesystemLoader ¶
type FilesystemLoader struct {
// contains filtered or unexported fields
}
FilesystemLoader walks a directory tree for SKILL.md files, parses each one into a Skill, and aggregates them into a Set.
Layout (mirrors Claude Code's skill plugins for portability):
root/
cooking/
SKILL.md <- frontmatter + body
research/
SKILL.md
helper.md <- ignored (only files named SKILL.md count)
Frontmatter is a leading YAML-ish block delimited by lines consisting only of "---". A minimal parser handles the subset real skills use: top-level scalars (name, description) and nothing nested. Skills needing richer frontmatter (lists, maps) would parse failures into a logged warning + skip the skill; this v0 doesn't pull in a YAML dep.
FilesystemLoader doesn't load tools — the SKILL.md frontmatter names tools, but registering implementations is the host's job (tools are Go code, not data files). Hosts that want to wire named tools to implementations can map after Load.
func NewFilesystemLoader ¶
func NewFilesystemLoader(root string) (*FilesystemLoader, error)
NewFilesystemLoader returns a loader rooted at the given path. Empty root is rejected — most accidental misuses pass "" and would otherwise walk the working directory.
func (*FilesystemLoader) Load ¶
func (l *FilesystemLoader) Load(ctx context.Context) (*Set, error)
Load walks the filesystem and returns a Set containing every successfully-parsed SKILL.md. Parse errors on individual files produce a warning written via fmt.Fprintln(os.Stderr, ...) and the skill is skipped — a single malformed SKILL.md should not block the rest. Aggregate fatal errors (missing root) return as the second return value.
func (*FilesystemLoader) SetFS ¶
func (l *FilesystemLoader) SetFS(fsys fs.FS)
SetFS swaps the filesystem the loader walks. Test-only — production callers use the path-based constructor.
type Loader ¶
Loader is the discovery interface. Implementations might walk a filesystem (NewFilesystemLoader), call out to a registry, or generate skills procedurally. Load is one-shot; hosts that want incremental loading wrap a Loader and manage their own Set.
type Set ¶
type Set struct {
// contains filtered or unexported fields
}
Set is a collection of skills keyed by Name. Construct with NewSet, mutate with Add / Remove, and hand to an agent via jess.WithSkills. Safe for concurrent use.
func NewSet ¶
func NewSet() *Set
NewSet returns an empty Set. Hosts that load skills from disk (NewFilesystemLoader, etc.) construct a Set internally and return it.
func (*Set) Add ¶
Add registers s. Returns an error if a Skill with the same Name is already in the Set — callers that intend to replace should Remove first. Empty Name is rejected; nothing else is validated.
func (*Set) Get ¶
Get returns the skill with the given name and a boolean indicating presence. The returned Skill is a copy; modifying it does not affect the Set.
type Skill ¶
type Skill struct {
Name string
Description string
SystemPrompt string
// Tools is the slice of agent tools this skill contributes.
// Typed as `any` here to keep this package vendor-free: jess's
// anti-corruption layer type-asserts each entry to jess/tool.Tool
// when it wires the Set into an agent. Entries that don't
// implement tool.Tool are ignored.
Tools []any
}
Skill is one capability bundle. The shape is deliberately minimal — real complexity goes into the Tools and the SystemPrompt content, not metadata.
A Skill is identified by Name (unique within a Set) and described by Description (one-line summary the agent sees in its system prompt's skill index). SystemPrompt is a multi-paragraph instruction the model receives when the skill is active; this is where "use this skill when…" guidance lives. Tools is the callable surface contributed when the skill is active.
All fields except Name are optional. A skill can be pure instructions (no tools), pure tools (no extra system prompt), or both.
Source Files