Module skill 

Skill discovery and SKILL.md frontmatter parsing.

Structs

Discovery

A discovery pass: the parsed skills, plus every SKILL.md that was found but yielded no skill (unreadable, unusable frontmatter, placeholder) with the reason — so ski index can say why a skill is missing instead of silently indexing without it.

Skill

Functions

discover

Walk roots and parse every SKILL.md found (skills only; see discover_all for the skip diagnostics).

discover_all

Walk roots and parse every SKILL.md found. One bad file never aborts the pass — it is recorded in skipped (and traced under SKI_DEBUG) and the rest of the library survives.

extract_phrases

Mine multi-word trigger phrases from a skill description. Scans the already unquoted description for inner quoted spans (single or double quotes, ASCII or curly), keeps those with [MIN_PHRASE_TOKENS]..=[MAX_PHRASE_TOKENS] content tokens, and returns each normalized to a space-joined string of its content tokens (the form the ranker matches against a prompt). De-duplicated, order-preserving.

parse_file

Parse a single SKILL.md. Returns None when the file yields no usable skill for any reason — unreadable file as well as missing/placeholder frontmatter — so a caller holding a possibly-stale path (e.g. the reranker’s doc-text read) degrades gracefully. Use discover_all when the skip reason matters; the Result wrapper is kept for signature compatibility.

parse_frontmatter

Extract name, description, and keywords/aliases from a leading --- ... --- YAML frontmatter block. Intentionally minimal — not the full YAML grammar (no nested maps, anchors, flow maps) — but it covers every shape real skills ship: single-line key: value, quoted values, inline lists, block scalars (description: >- + indented lines — common in community skills, and previously parsed as the literal description ">-"), multi-line plain scalars (indented continuation lines), and indented - item lists.