skills¶
Skills system — markdown skill files, deterministic routing, prompt injection.
A skill is a markdown file with a small frontmatter header::
---
name: speechwriting
description: Draft speeches and public statements
when_to_use: speech, statement, keynote address, public remarks
priority: 10
---
# instructions for the agent ...
The router scores each skill's when_to_use triggers against the user
question (whole phrase = 3 points, individual words of length >= 4 = 1
point each). The highest-scoring skill above zero wins; ties break by
priority. No LLM is involved, so activation is cheap, deterministic,
and testable.
The matched skill's body is appended to the system prompt for that turn only (see agent.py), and a StatusEvent announces the activation so the web UI and CLI both show which skill is active.
Skill
dataclass
¶
A markdown skill — instructions injected into the system prompt.
Loaded from a markdown file whose frontmatter carries the trigger
metadata; _phrases and _acronyms are derived from
when_to_use on construction (see :func:load_skills).
__post_init__()
¶
Derive trigger phrases and acronym list from when_to_use.
Runs after dataclass construction so Skills built either by
:func:load_skills or directly in tests behave identically.
format_skill_prompt(skill)
¶
Render the skill as a system-prompt block for the current turn.
load_skills(skills_dir=None)
¶
Load all skill markdown files from a directory (cached).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
skills_dir
|
Path | str | None
|
Directory containing *.md skill files. Defaults to config.SKILLS_DIR. |
None
|
Returns:
| Type | Description |
|---|---|
list[Skill]
|
List of Skill objects, sorted by priority (descending) then name. |
route_skill(question, skills=None)
¶
Pick the best matching skill for a question, or None.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
question
|
str
|
The user's raw question. |
required |
skills
|
list[Skill] | None
|
Skill list; defaults to loading from SKILLS_DIR. |
None
|
Returns:
| Type | Description |
|---|---|
Skill | None
|
The highest-scoring skill, or None if nothing matches. |