skills#

Utilities for reading, writing and inspecting Agent Skill files.

A skill is a directory that contains, at minimum, a SKILL.md file made up of YAML frontmatter followed by a Markdown body. In addition to SKILL.md a skill may bundle supporting resources, conventionally grouped under scripts/, references/ and assets/ (any other files/directories are allowed too).

The format follows the Agent Skills specification: https://agentskills.io/specification

Design notes#

Resource files (everything besides SKILL.md) are discovered and tracked as paths relative to the skill root, but their contents are not loaded eagerly. This mirrors the spec’s progressive-disclosure model and avoids pulling large reference files into memory. Use Skill.list_resources() and Skill.read_resource() to access them on demand.
The skill is keyed off its directory (not the SKILL.md file directly), because the spec requires name to match the parent directory name.

Functions

`filter_skills`(skills[, languages_include, ...])	Filter skills by their `languages` and `tags` metadata.
`load_skills`(directory[, validate])	Load every skill found directly under `directory`.

Classes

`Skill`(frontmatter, body, root, resources)	An Agent Skill loaded from (or destined for) a directory on disk.
`SkillFrontmatter`(name, description, license, ...)	Structured representation of the `SKILL.md` YAML frontmatter.
`SkillLibrary`([skills])	A collection of skills discovered under one or more root directories.

Exceptions

SkillError

Raised when a skill cannot be parsed, validated or written.

exception kernelfoundry.algorithm.utils.skills.SkillError[source]#: Raised when a skill cannot be parsed, validated or written.

class kernelfoundry.algorithm.utils.skills.SkillFrontmatter(name: str, description: str, license: str | None = None, compatibility: str | None = None, metadata: ~typing.Dict[str, ~typing.Any] = <factory>, allowed_tools: str | None = None, extra: ~typing.Dict[str, ~typing.Any] = <factory>)[source]#

Structured representation of the SKILL.md YAML frontmatter.

Only name and description are required by the specification. The remaining fields are optional and default to empty/None. extra captures any non-standard frontmatter keys so they survive a load/save round-trip.

name: str#

description: str#

license: str | None = None#

compatibility: str | None = None#

metadata: Dict[str, Any]#

allowed_tools: str | None = None#

extra: Dict[str, Any]#

classmethod from_dict(data: Dict[str, Any]) → SkillFrontmatter[source]#

to_dict() → Dict[str, Any][source]#: Render the frontmatter back to an ordered mapping for YAML output.

validate(expected_name: str | None = None) → None[source]#

Validate the frontmatter against the specification constraints.

Parameters:: expected_name – If given (typically the skill directory name), the name field must match it.
Raises:: SkillError – if any constraint is violated.

__init__(name: str, description: str, license: str | None = None, compatibility: str | None = None, metadata: ~typing.Dict[str, ~typing.Any] = <factory>, allowed_tools: str | None = None, extra: ~typing.Dict[str, ~typing.Any] = <factory>) → None#

class kernelfoundry.algorithm.utils.skills.Skill(frontmatter: ~kernelfoundry.algorithm.utils.skills.SkillFrontmatter, body: str = '', root: ~pathlib.Path | None = None, resources: ~typing.List[~pathlib.Path] = <factory>)[source]#

An Agent Skill loaded from (or destined for) a directory on disk.

frontmatter#

Parsed SKILL.md frontmatter.

Type:: kernelfoundry.algorithm.utils.skills.SkillFrontmatter

body#

Markdown body of SKILL.md (everything after the frontmatter).

Type:: str

root#

Directory the skill was loaded from, if any.

Type:: pathlib.Path | None

resources#

Resource file paths relative to root, excluding SKILL.md. Discovered lazily on load; contents are not read.

Type:: List[pathlib.Path]

frontmatter: SkillFrontmatter#

body: str = ''#

root: Path | None = None#

resources: List[Path]#

property name: str#

property description: str#

property metadata: Dict[str, Any]#

get_metadata(key: str, default: Any | None = None) → Any[source]#: Return a single value from the frontmatter metadata mapping.

classmethod parse(text: str) → Skill[source]#: Parse the raw text of a SKILL.md file into frontmatter + body.

classmethod load(path: str | Path, validate: bool = True, discover_resources: bool = True) → Skill[source]#

Load a skill from a directory or directly from a SKILL.md file.

Parameters:

path – Either the skill directory or the SKILL.md file inside it.
validate – Validate frontmatter against the spec after loading.
discover_resources – Scan the skill directory for bundled resource files (everything besides SKILL.md).

Returns:

The loaded Skill.

list_resources(subdir: str | None = None) → List[Path][source]#

List tracked resource paths, optionally filtered to a subdirectory.

Parameters:: subdir – e.g. "scripts", "references" or "assets".

resource_path(relative: str | Path) → Path[source]#: Return the absolute path to a bundled resource.

read_resource(relative: str | Path, binary: bool = False)[source]#

Read a bundled resource file on demand.

Parameters:

relative – Path relative to the skill root (e.g. scripts/run.py).
binary – Read bytes instead of text.

render() → str[source]#: Render the skill back to SKILL.md text (frontmatter + body).

save(path: str | Path, validate: bool = True, copy_resources: bool = True) → Path[source]#

Write the skill to path (a directory) and return the skill root.

Parameters:

path – Target skill directory. Created if it does not exist.
validate – Validate frontmatter before writing.
copy_resources – Copy tracked resource files from the original root into the target directory. Ignored when the target is the same as the source.

Returns:

The skill root directory that was written.

__init__(frontmatter: ~kernelfoundry.algorithm.utils.skills.SkillFrontmatter, body: str = '', root: ~pathlib.Path | None = None, resources: ~typing.List[~pathlib.Path] = <factory>) → None#

kernelfoundry.algorithm.utils.skills.load_skills(directory: str | Path, validate: bool = True) → List[Skill][source]#

Load every skill found directly under directory.

A subdirectory is treated as a skill if it contains a SKILL.md file.

kernelfoundry.algorithm.utils.skills.filter_skills(skills: Iterable[Skill], languages_include: Iterable[str] | None = None, languages_exclude: Iterable[str] | None = None, tags_include: Iterable[str] | None = None, tags_exclude: Iterable[str] | None = None) → List[Skill][source]#

Filter skills by their languages and tags metadata.

For each key (languages, tags) the include/exclude lists are applied independently and a skill must satisfy all provided constraints:

*_include: keep the skill only if it has at least one of these values for the key. An empty/None include list imposes no constraint.
*_exclude: drop the skill if it has any of these values for the key.

Parameters:

skills – Skills to filter.
languages_include – Keep skills whose metadata['languages'] contains any of these values.
languages_exclude – Drop skills whose metadata['languages'] contains any of these values.
tags_include – Keep skills whose metadata['tags'] contains any of these values.
tags_exclude – Drop skills whose metadata['tags'] contains any of these values.

Returns:

The list of skills that pass every constraint.

class kernelfoundry.algorithm.utils.skills.SkillLibrary(skills: Iterable[Skill] | None = None)[source]#

A collection of skills discovered under one or more root directories.

Skills are found by recursively scanning for SKILL.md files, so nested layouts such as skills/opencl/opencl-gemm/SKILL.md are supported.

__init__(skills: Iterable[Skill] | None = None)[source]#

classmethod load(root: str | Path, validate: bool = True) → SkillLibrary[source]#: Recursively load every skill under root into a library.

get(name: str) → Skill | None[source]#: Return the skill with the given name, or None.

filter(languages_include: Iterable[str] | None = None, languages_exclude: Iterable[str] | None = None, tags_include: Iterable[str] | None = None, tags_exclude: Iterable[str] | None = None) → List[Skill][source]#

Filter the library’s skills by languages and tags metadata.

See filter_skills() for the include/exclude semantics.