Module skills 

Skill discovery and loading.

A “skill” is a markdown file with a YAML frontmatter block, or a directory containing skill files. Two formats are supported:

Format 1: Single-file skill (SKILL.md)

skills/
  my-skill/
    SKILL.md            # required, with frontmatter
    helper.py           # optional support files
    templates/...       # optional subdirs

Format 2: Multi-file skills (like Claude Code plugins)

skills/
  om/
    debug.md            # each .md file is a separate skill
    feature.md
    plan.md
    ...

Skills are surfaced to the model in two stages:

1. At startup every skill’s name + description is injected into the system prompt so the model knows what’s available.
2. The skill tool loads the full skill body (and lists the skill’s files) when the model decides to use one. This keeps baseline token cost low even with many skills installed.

Structs

Skill

A loaded skill ready to be advertised to the model.

Functions

discover_skills

Walk the given roots and load skills from all supported formats:

format_catalogue

Render the skills catalogue body for insertion into a prompt section. Returns None if there are no skills, so callers can skip injection entirely rather than bolting on an empty section.

list_skill_files

List files inside a skill directory (recursive), relative to the skill root. Used by the skill tool so the model knows what supporting files it can read next.

load_skill

Load a skill from a directory with SKILL.md (backward compatible).

load_skill_from_file

Load a skill from a specific .md file. Public so tests and the skill tool can reload a specific skill.