Skills

Skill primitives for structured, reusable subagent capabilities.

Skill

Wraps an agent skill — either from a SKILL.md file or inline content.

instructions property

instructions: str

Full skill instructions — SKILL.md body without frontmatter.

name property

name: str

Skill name from frontmatter or inline content.

path class-attribute instance-attribute

path: Path | None = None

Path to the skill directory containing a SKILL.md file.

summary property

summary: str

Short description from frontmatter or inline content. Used in skill index.

discover classmethod

discover(directory: Path | str) -> list[Self]

Recursively discover all skills in a directory.

Each subdirectory containing a SKILL.md file is loaded via from_dir, including full frontmatter validation.

Parameters:

Name	Type	Description	Default
directory	Path | str	Root directory to search. All subdirectories containing a SKILL.md file are loaded as skills.	required

from_content classmethod

from_content(
    name: str, instructions: str, summary: str | None = None
) -> Self

Create an inline skill without a filesystem path.

Useful for tests, dynamically generated skills, or skills embedded directly in code. Bypasses frontmatter parsing entirely.

Parameters:

Name	Type	Description	Default
name	str	Unique skill identifier.	required
instructions	str	Full skill instructions in Markdown.	required
summary	str | None	Short description shown in the skill index. Defaults to the first non-empty line of instructions.	None

from_dir classmethod

from_dir(path: Path | str) -> Self

Load a skill from a directory on disk.

Validates that the directory exists and the SKILL.md frontmatter contains the required name and description fields.

Parameters:

Name	Type	Description	Default
path	Path | str	Path to a skill directory containing a SKILL.md file with valid YAML frontmatter. The frontmatter name field must match the directory name.	required

Raises:

Type	Description
ValueError	If the path does not exist, frontmatter is missing or malformed, or the name field does not match the directory name.
FileNotFoundError	If no SKILL.md file is found in the directory.

Skill Registry

format_all_instructions

format_all_instructions() -> str

Inject all skill instructions at once (for smaller skill sets).

format_index

format_index() -> str

Short index injected into system prompt so the agent knows what's available.