nodestep.middleware.skills

Skills: SKILL.md files that FilesystemSkills offers the model to load.

See Built-in middleware.

Middleware

BaseSkills

Base class for middleware that offers skills to the model.

Subclass of Middleware.

Methods

tools()

Return the skill tools.

tools() -> Iterable[Tool]

FilesystemSkills

FilesystemSkills(roots, *, nodes)

List the skills in the requests of the named model nodes and offer load_skill.

Subclass of BaseSkills.

The list is a SystemMessage inserted after the request's leading system messages; it is never stored.

Parameters

roots	Iterable[str | Path] | SkillCatalog	Roots as for SkillCatalog, or a catalog already built.
nodes	Collection[str]	model_node names whose requests get the list, e.g. {"think"} for build_react_agent. Not checked against the graph: a misspelled name gets nothing.

Raises

TypeError	If nodes is a single string.
ValueError	If nodes is empty, or a root is a file other than SKILL.md.
FileNotFoundError	If a root does not exist or holds no SKILL.md.
SkillFormatError	If a SKILL.md is not UTF-8 or has no valid frontmatter.
SkillConflictError	If two different files define the same skill name.

Methods

list_skills()

Return all skills sorted by name.

list_skills() -> list[Skill]

get(name)

Return a skill by name.

get(name) -> Skill

Parameters

name

str

Raises

SkillNotFoundError

tools()

Return the load_skill tool.

tools() -> tuple[Tool, ...]

before_model(ctx)

Add the skill catalog to the requests of the listed nodes.

before_model(ctx) -> Replacement | None

Returns

Replacement or None

The request with the catalog, or None for other nodes and an empty catalog.

Skills

SkillCatalog

SkillCatalog(roots)

Skills read from SKILL.md files when the catalog is built.

A SKILL.md starts with key: value lines between two --- lines: name and description are required, other keys are ignored, values may be quoted. Files are read as UTF-8, with or without a byte order mark.

Parameters

roots

Iterable[str | Path]

Directories searched recursively for SKILL.md files, or skill files themselves.

Raises

FileNotFoundError	If a root does not exist or holds no SKILL.md.
ValueError	If a root is a file other than SKILL.md.
SkillFormatError	If a SKILL.md is not UTF-8 or has no valid frontmatter.
SkillConflictError	If two different files define the same skill name.

Methods

list_skills()

Return all skills sorted by name.

list_skills() -> list[Skill]

get(name)

Return a skill by name.

get(name) -> Skill

Parameters

name

str

Raises

SkillNotFoundError

Skill

Skill(*, name, description, path, root_path, content)

A skill loaded from a SKILL.md file.

Attributes

name	str	The frontmatter name.
description	str	The frontmatter description, shown in the skill list.
path	Path	The SKILL.md file.
root_path	Path	The folder that holds it.
content	str	The whole file, frontmatter included.

LoadedSkill

LoadedSkill(*, name, description, content, path, primary_file)

Result of the load_skill tool.

Attributes

name	str
description	str
content	str	The whole SKILL.md, frontmatter included.
path	str	The skill's folder.
primary_file	str	Its SKILL.md file.

Errors

SkillNotFoundError

Raised when a skill name is unknown.

Subclass of NodestepError and LookupError.

SkillConflictError

Raised when two skill folders share a name.

Subclass of NodestepError.

SkillFormatError

Raised when a SKILL.md file is not UTF-8 or has no valid frontmatter.

Subclass of NodestepError.