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.

unavailable_skills `property` ¶

unavailable_skills

Mapping of unavailable skill name -> reason.

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.

mark_unavailable ¶

mark_unavailable(name, reason)

Record a skill that exists but cannot be used in this context.

The skill leaves the available set entirely — skill_names, all_metadata() and get_skill() no longer see it — and only surfaces through unavailable_skills, the prompt manifest and the skill-tool error paths, so callers can say WHY it is missing instead of leaving a silent gap (e.g. a requires gate dropping a skill whose tools are not granted in this execution context).

get_unavailable_reason ¶

get_unavailable_reason(name)

Reason a skill is unavailable in this context, or None.

all_metadata ¶

all_metadata()

Return metadata for all registered skills.

to_prompt_xml ¶

to_prompt_xml()

Generate spec-compliant XML block.

Skills marked unavailable are listed in a separate <unavailable_skills> block with their reason, so the model can explain the gap instead of guessing at a name that will answer "not found". 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 ¶