Skills¶

Agent skills framework for structured tool definitions. See the Agent Skills guide for usage examples.

Core¶

Skill `dataclass` ¶

Skill(metadata, instructions, path)

Full skill definition including instructions body.

list_scripts ¶

list_scripts()

List script filenames in the skill's scripts/ directory.

list_references ¶

list_references()

List reference filenames in the skill's references/ directory.

read_reference ¶

read_reference(filename)

Read a reference file by name.

Raises:

Type	Description
`ValueError`	If filename contains path traversal characters.
`FileNotFoundError`	If the reference file does not exist.

SkillMetadata `dataclass` ¶

SkillMetadata(name, description, license=None, compatibility=None, allowed_tools=None, extra_metadata=dict())

Lightweight metadata parsed from SKILL.md frontmatter.

gated_tool_names `property` ¶

gated_tool_names

Parse allowed_tools into a list of tool names.

The allowed_tools field is a comma-separated string. Returns an empty list when the field is None or blank.

ScriptResult ¶

Bases: BaseModel

Result of executing a skill script.

SkillRegistry ¶

SkillRegistry()

Discover, load, and manage Agent Skills.

Lightweight metadata is parsed on discover/register. Full skill instructions are loaded lazily on first get_skill() call and cached for subsequent access.

skill_names `property` ¶

skill_names

Names of all registered skills.

skill_count `property` ¶

skill_count

Number of registered skills.

discover ¶

discover(*directories)

Scan directories for subdirectories containing SKILL.md.

Returns the number of newly discovered skills. Invalid skills are warned and skipped.

register ¶

register(skill_dir)

Register a single skill directory.

Parses frontmatter only (lightweight). Replaces any existing skill with the same name.

Raises:

Type	Description
`SkillParseError`	If SKILL.md cannot be found or parsed.
`SkillValidationError`	If metadata fails validation.

get_metadata ¶

get_metadata(name)

Get metadata for a skill by name.

get_skill ¶

get_skill(name)

Get full skill (with instructions), loading lazily if needed.

all_metadata ¶

all_metadata()

Return metadata for all registered skills.

to_prompt_xml ¶

to_prompt_xml()

Generate spec-compliant XML block.

Content is HTML-escaped to prevent injection.

ScriptExecutor ¶

Bases: ABC

Execute skill scripts with integrator-defined policy.

No default implementation is provided — the execution policy (sandboxing, timeouts, allowed interpreters) is always the integrator's responsibility.

execute `abstractmethod` `async` ¶

execute(skill, script_name, arguments=None)

Run a script from a skill's scripts/ directory.

Parameters:

Name	Type	Description	Default
`skill`	`Skill`	The skill that owns the script.	required
`script_name`	`str`	Filename of the script to run.	required
`arguments`	`dict[str, str] \| None`	Optional key-value arguments to pass.	`None`

Returns:

Type	Description
`ScriptResult`	Result of the script execution.

close `async` ¶

close()

Release resources. Override in subclasses that hold connections.

Exceptions¶

SkillParseError ¶

Bases: Exception

Failed to parse SKILL.md content.

SkillValidationError ¶