calute.extensions.skills

calute.extensions.skills#

Skill discovery and management for Calute.

Skills are self-contained instruction packages defined by SKILL.md files. Each skill provides metadata, instructions, and optional resource references that can be injected into agent prompts on demand.

Skill directory layout:

skills/
├── web_research/
│   └── SKILL.md
├── code_review/
│   └── SKILL.md
└── data_analysis/
    ├── SKILL.md
    └── templates/
        └── report.md

SKILL.md format (YAML frontmatter + markdown body):

---
name: web_research
description: Search the web and synthesize findings
version: "1.0"
tags: [research, web]
resources:
  - templates/query.md
---

# Web Research Skill

Instructions for conducting web research...

class calute.extensions.skills.Skill(metadata: SkillMetadata, instructions: str, source_path: Path, resources_dir: pathlib.Path | None = None)[source]#

Bases: object

A fully loaded skill consisting of metadata, instructions, and resource references.

metadata#

The SkillMetadata parsed from the SKILL.md frontmatter.

Type: calute.extensions.skills.SkillMetadata

instructions#

The markdown body of the SKILL.md file, containing the instructions to be injected into the agent prompt.

Type: str

source_path#

The filesystem path to the SKILL.md file this skill was loaded from.

Type: pathlib.Path

resources_dir#

The directory containing supplementary resource files, or None if no resources are declared.

Type: pathlib.Path | None

instructions: str#

metadata: SkillMetadata#

property name: str#

Return the skill’s unique name from its metadata.

Returns: The skill name string.

resources_dir: pathlib.Path | None = None#

source_path: Path#

to_prompt_section() → str[source]#

Format the skill as a markdown section for injection into a system prompt.

Produces a section with a ## Skill: <name> heading, an optional description line, and the full instruction body.

Returns: A markdown-formatted string ready to be appended to a system prompt.

class calute.extensions.skills.SkillMetadata(name: str, description: str = '', version: str = '1.0', tags: list[str] = <factory>, resources: list[str] = <factory>, author: str = '', dependencies: list[str] = <factory>, required_tools: list[str] = <factory>)[source]#

Bases: object

Parsed metadata from the YAML frontmatter of a SKILL.md file.

name#

A unique identifier for the skill (e.g., "web_research").

Type: str

description#

A short human-readable description of what the skill does.

Type: str

version#

A version string for the skill (default "1.0").

Type: str

tags#

Freeform tags used for search and categorization (e.g., ["research", "web"]).

Type: list[str]

resources#

Relative paths to supplementary files (templates, data) located alongside the SKILL.md file.

Type: list[str]

author#

The name or handle of the skill author.

Type: str

dependencies#

Names of other skills that must be loaded before this skill can function.

Type: list[str]

required_tools#

Names of tools (from the plugin registry) that this skill expects to be available at runtime.

Type: list[str]

author: str = ''#

dependencies: list[str]#

description: str = ''#

name: str#

required_tools: list[str]#

resources: list[str]#

tags: list[str]#

version: str = '1.0'#

class calute.extensions.skills.SkillRegistry[source]#

Bases: object

Discovers, indexes, and provides skills for prompt injection.

The registry scans one or more directories for SKILL.md files, parses them, and stores the resulting Skill objects for later retrieval by name, tag, or free-text search.

_skills#: Internal mapping of skill name to Skill instance.

Example

>>> registry = SkillRegistry()
>>> registry.discover("./skills")
>>> skill = registry.get("web_research")
>>> print(skill.to_prompt_section())

build_skills_index() → str[source]#

Build a compact plain-text index of all registered skills.

The index lists each skill’s name, description, and tags on a single indented line, suitable for injection into a system prompt so the agent knows which skills are available.

Returns: A multi-line string listing available skills, or an empty string if no skills are registered.

discover(*directories: str | pathlib.Path) → list[str][source]#

Recursively scan directories for SKILL.md files and register them.

Each directory is walked recursively. When a SKILL.md file is found it is parsed and registered under its metadata name. Duplicate skill names are skipped (first-discovered wins).

Parameters: *directories – One or more directory paths to scan. Non-existent directories are logged as warnings and skipped.
Returns: A list of skill names that were newly registered during this discovery pass.

get(name: str) → calute.extensions.skills.Skill | None[source]#

Look up a registered skill by name.

Parameters: name – The skill name to look up.
Returns: The Skill instance, or None if not found.

get_all() → list[calute.extensions.skills.Skill][source]#

Return all registered skills.

Returns: A list of all Skill instances currently registered.

register(skill: Skill) → None[source]#

Manually register a pre-built Skill instance.

Overwrites any existing skill with the same name.

Parameters: skill – The Skill to register.

search(query: str = '', tags: list[str] | None = None) → list[calute.extensions.skills.Skill][source]#

Search skills by free-text query and/or tag matching.

When query is provided, skills whose name or description contains the query (case-insensitive) are included. When tags is provided, skills that have at least one matching tag are included. If neither query nor tags is provided, all skills are returned.

Parameters

query – A case-insensitive substring to search for in skill names and descriptions. Defaults to "".
tags – An optional list of tags to filter by. A skill matches if it has any of the specified tags.

Returns

A list of matching Skill instances.

property skill_names: list[str]#

Return the names of all registered skills.

Returns: A list of skill name strings in insertion order.

validate_dependencies(plugin_registry: Any = None) → list[str][source]#

Validate that all registered skills have their dependencies met.

Parameters: plugin_registry – Optional PluginRegistry instance to check required_tools against.
Returns: List of error messages (empty if all dependencies are satisfied).

calute.extensions.skills.parse_skill_md(content: str, source_path: Path) → Skill[source]#

Parse a SKILL.md file’s content into a Skill object.

The file is expected to contain optional YAML frontmatter delimited by --- lines, followed by a markdown body. If PyYAML is installed the frontmatter is parsed with yaml.safe_load; otherwise a simple line-by-line key-value parser is used as a fallback.

When no name key is present in the frontmatter, the parent directory name of source_path is used as the skill name.

Parameters

content – The full text content of the SKILL.md file.
source_path – The filesystem path to the SKILL.md file (used to derive the skill name and resources directory).

Returns

A Skill instance populated with the parsed metadata and instruction body.

Example

>>> from pathlib import Path
>>> content = "---\nname: demo\n---\nDo something."
>>> skill = parse_skill_md(content, Path("/skills/demo/SKILL.md"))
>>> skill.name
'demo'

calute.extensions.skills

Contents

calute.extensions.skills#