jeevesagent.skills.skill

The Skill class — one loadable agent skill.

A Skill is a directory on disk containing a SKILL.md file plus optional supporting resources. The SKILL.md has YAML frontmatter (metadata that loads at startup) and a markdown body (loaded only when the skill is triggered).

Three flavours of “tools” a skill can ship — none required, freely mixable in one skill:

• Mode A (markdown only): the body teaches the model how to use the agent’s existing built-in tools (read, write, bash, etc.). No tool manifest, no Python imports. Pure instructions.

• Mode C (frontmatter manifest → subprocess Tool): SKILL.md’s tools: block declares a script as a typed tool. At skill load the framework wraps the script in a Tool that executes via subprocess and returns stdout. Works for ANY language — Python, bash, Node, Go.

• Mode B (tools.py auto-discovery): if a tools.py file sits in the skill folder, it’s imported at construction. Any callable decorated with @tool becomes a registered Tool when the skill is loaded. In-process, Python-only.

Every Tool ships from a skill is prefixed with the skill name (web_research__fetch rather than fetch) so multiple skills loaded simultaneously don’t collide.

Exceptions

SkillError

Raised on invalid skill construction or frontmatter.

Classes

Skill	A loadable agent skill.
SkillMetadata	Lightweight skill descriptor — what loads at startup.
ToolSpec	One subprocess-tool declaration parsed from frontmatter.

Module Contents

exception jeevesagent.skills.skill.SkillError

Bases: ValueError

Raised on invalid skill construction or frontmatter.

Initialize self. See help(type(self)) for accurate signature.

class jeevesagent.skills.skill.Skill(path: str | pathlib.Path, *, source_label: str | None = None)

A loadable agent skill.

classmethod from_text(text: str, *, source_label: str | None = None) → Skill

Build an inline skill from a SKILL.md-formatted string.

No filesystem path; bundled scripts and tools.py aren’t accessible. Useful for one-off skill definitions in code.

list_files() → list[pathlib.Path]

Enumerate every file bundled with this skill.

load_body() → str

Return the full SKILL.md body (without frontmatter).

property description: str

metadata

property name: str

path

property pending_tools: list[jeevesagent.tools.registry.Tool]

The Tool instances this skill will register on load.

Both Mode B (Python @tool from tools.py) and Mode C (subprocess wrappers from frontmatter tools: manifest) contribute to this list. Empty for pure markdown skills.

class jeevesagent.skills.skill.SkillMetadata

Lightweight skill descriptor — what loads at startup.

The body is NOT in here; it’s read on demand via Skill.load_body(). Keep this small — it lives in the system prompt for the entire agent’s lifetime.

to_catalog_line() → str

One-line catalog entry for the system prompt.

allowed_tools: list[str] | None = None

compatibility: str | None = None

declared_tool_count: int = 0

description: str

extra: dict[str, Any]

has_python_tools: bool = False

license: str | None = None

name: str

source_label: str | None = None

class jeevesagent.skills.skill.ToolSpec

One subprocess-tool declaration parsed from frontmatter.

Mode C — the user declared this script as a tool. The skill load flow turns it into a real Tool whose fn execs the script via subprocess and returns stdout.

args: dict[str, dict[str, Any]]

description: str

name: str

script: str