Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 read of .../skills/<name>/SKILL.md counts once as a skill trigger in the usage ledger, beside the read tool 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 one skills row 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) or off.
  • [brain] skills = true (the default) is the switch. false passes no --skill and 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

Was this page helpful?