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
SkillPathError	If filename is not a plain name inside the skill's references/ directory. Subclasses ValueError.
FileNotFoundError	If the reference file does not exist.

resolve_script

resolve_script(script_name)

Resolve a script inside the skill's scripts/ directory.

ScriptExecutor implementations should build their command from this rather than joining the name themselves. Execution policy — sandboxing, timeouts, allowed interpreters — stays the integrator's call, but which file gets run should not depend on each integrator repeating the same containment check.

Raises:

Type	Description
SkillPathError	If script_name is not a plain name inside the skill's scripts/ directory. Subclasses ValueError.
FileNotFoundError	If the script 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.

allowed_tools class-attribute instance-attribute

allowed_tools = None

Tool access patterns this skill gates (RFC §24.2).

Both frontmatter forms are accepted: a YAML list, which is what the RFC's own example uses, and a comma-separated scalar. Entries are ToolPolicy globs, so search_* covers every tool whose name starts with search_.

required_tool_names property

required_tool_names

Exact prerequisite names from the optional requires metadata.

These describe dependencies, not grants. Applications resolve skill availability against their authorized catalogue before using it.

gated_tool_names property

gated_tool_names

The patterns this skill gates, one per entry.

Accepts either frontmatter form. Returns an empty list when the field is None or blank. The entries are patterns, not names — match them with :meth:gates, never with in.

gates

gates(tool_name)

Whether this skill gates tool_name (RFC §24.2 glob semantics).

Uses the same fnmatch matching as :class:~roomkit.tools.policy.ToolPolicy, so a skill and a policy agree on what a pattern covers.

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.

listed_names property

listed_names

Names of registered skills that the prompt manifest shows.

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, strict=True)

Scan directories for subdirectories containing SKILL.md.

A malformed skill is a deployment error, not a runtime condition, so the default is to stop. Skipping it instead removes the skill from the catalogue while the agent keeps answering: the model is never told the capability is missing, and neither is anyone reading the conversation. The failure surfaces hours later as an agent that quietly cannot do something it was configured to do.

Discovery commits only once every candidate has parsed, so a strict failure leaves the registry exactly as it was rather than half filled.

Parameters:

Name	Type	Description	Default
directories	str | Path	Directories to scan. Only immediate subdirectories containing a SKILL.md are considered.	()
strict	bool	Stop on the first unreadable directory or invalid skill. Set False to log and skip each instead — appropriate when skills come from a source you do not control.	True

Returns:

Type	Description
int	The number of skills registered.

Raises:

Type	Description
SkillDiscoveryError	In strict mode, when a directory cannot be scanned or a candidate escapes it through a symlink.
SkillParseError	In strict mode, when a SKILL.md cannot be parsed.
SkillValidationError	In strict mode, when metadata is invalid.

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).

mark_unlisted

mark_unlisted(name)

Keep name activatable but out of the prompt manifest.

The third visibility state, between available and unavailable: the skill stays registered — activate_skill, get_skill() and skill_names still see it — but to_prompt_xml() and listed_names do not. For catalogues where advertising every entry would drown the ones that matter: a host can keep quiet about a skill while any path that names it (a recommender nudge, a user asking for it) still activates it, which is what lets it earn its listing back.

Unknown names are ignored — there is nothing to hide.

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". Skills marked unlisted are simply absent — activatable, but not advertised. 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: SkillError

Failed to parse SKILL.md content.

SkillValidationError

Bases: SkillError

SKILL.md metadata failed validation.