Skills
The skill tier (ADR 0050 S7): a skill is a .vulpine/skills/<name>/ folder holding SKILL.md (and references/*.md, never code) whose frontmatter names the catalog tools it composes (tools), the memory keys it learns (facts) and its voice-corpus lines (tests); the gateway lints and resolves each at bind (ready, degraded with the missing tools and why, or refused), passes the loaded ones with --skill, counts a SKILL.md read as a skill trigger, shows a Skills row per skill in the setup census, and [brain] skills = false turns it off.
Living doc, checked against the code 2026-11-14
skill.v1 — a skill: a procedure in words over catalog tools
- Status: live, on by default (ADR 0050). The operator workspace ships three skills.
- Scope: the third capability tier. A verb is the gateway’s (no brain turn). A catalog tool is one row of
catalog/pi/tool-catalog.json(one tool round). A skill is a short procedure the brain reads when a task matches and carries out with catalog tools (a few rounds). Only its name and description enter the prefill. - The plugin point: drop a skill folder in the workspace. Nothing is compiled, installed or registered elsewhere. The gateway lints it at each bind and the Admin shows the verdict.
The folder
<workspace>/.vulpine/skills/<name>/
SKILL.md required: the frontmatter below, then the procedure in Markdown
references/*.md optional: up to 16 plain-text files of at most 64 KiB, read on demand
LICENSE[.md|.txt] optional
A skill carries no code. Any other entry refuses the skill, and the lint names a scripts, bin, lib or src
folder as code. A procedure that needs code is a plugin tool registered in the catalog. A link in place of the folder
or of SKILL.md refuses the skill too. SKILL.md is at most 16 KiB of UTF-8. .DS_Store is ignored. A workspace
offers at most 32 skills.
The frontmatter
---
name: garbage-day
description: "Answers which day the household's garbage goes out ... Use it for 'which day is garbage day'."
tools: [pi_memory_recall, pi_memory_propose, pi_ask_operator, pi_calendar_today, pi_reminders]
facts: [household.garbage_day]
tests: [VA-10]
---
| key | type | rule |
|---|---|---|
name |
text | Pi’s rule: lowercase letters, digits and single inner hyphens, at most 64; equal to the folder’s name |
description |
text | required, at most 1,024 characters, no control characters; says what it does and when to use it |
tools |
list | the catalog tools the procedure calls (at most 16); its authority is these intersected with the loadout’s |
facts |
list | the memory keys it learns through the memory core tool (ADR 0031 §4), [a-z0-9_.-] |
tests |
list | the voice-corpus line ids that are its acceptance (VA-10); every committed skill names at least one |
The frontmatter is the one-line subset of YAML that Pi’s reader and the gateway’s agree on. Values are plain,
"double" or 'single', on one line. Lists are [a, b] or - a lines under the key. A plain value that holds :
must be quoted. Block scalars, maps, anchors and tags are refused. Pi’s own keys (license, compatibility,
metadata, disable-model-invocation) pass unread. allowed-tools and any other key is a warning, never a refusal.
The bind
At each session bind, after the Admin’s tool toggles and the held tools’ readiness, the gateway
(crates/voice_gateway/src/skills.rs) reads the folder and resolves each skill:
| state | when | what the session gets |
|---|---|---|
ready |
every tool in tools is on or deferred in the session (a deferred tool is reached through pi_tool_search) |
--skill <SKILL.md> |
degraded |
a tool is switched off, not set up on this host, not in this loadout, or not a catalog tool | --skill, plus one system-prompt note naming each missing tool and why |
refused |
the lint refused the folder or the frontmatter, or the loadout lists a skill that has no folder | nothing |
A skill is never a bind failure. A loadout’s [tools] skills = ["garbage-day", ...] narrows the folder to those
names. Without it every skill in the folder is offered. [] offers none. Pi’s own discovery stays off
(--no-skills), and an explicit --skill path still loads. Pi lists each skill’s name, description and file in the
system prompt, and the brain reads the file when a task matches.
When a degraded skill runs, the brain says in plain words what it lacks (“that needs the calendar tool, which is
switched off”). It does what it can without the tool and files pi_feature_request naming it.
Usage, the Admin, the switch
- A
readof.../skills/<name>/SKILL.mdcounts once as askilltrigger in the usage ledger, beside thereadtool call. The ledger keeps the name, never the path. The Admin’s Usage view shows the skill tier. - The setup census (the Admin’s Setup section,
brain_vulpine_report {topic: setup}) has oneskillsrow per skill the bound loadouts offer:ok(ready in N loadouts),degraded(needs a tool, with the next step for that tool),not_set_up(refused, with the lint’s reason) oroff. [brain] skills = true(the default) is the switch.falsepasses no--skilland no note: the folder is inert.
The skills in the repo
| skill | composes | test |
|---|---|---|
garbage-day |
pi_memory_recall, pi_memory_propose, pi_ask_operator, pi_calendar_today, pi_reminders |
VA-10 |
starred-repo |
pi_github (stars, repo_read), pi_herdr_dispatch (run), pi_ask_operator |
VB-35 |
pick-up-work |
brain_work_status, pi_herdr_dispatch (run), pi_ask_operator |
VB-50 |