Skills
Folders with a SKILL.md inside. Drop one in the skills directory and the model knows how to use it.
What it is
A skill is a folder. Inside it, a SKILL.md file with YAML frontmatter (name, description, optional binary/env requirements) and markdown instructions. Optionally, a scripts/, references/, or assets/ directory next to it.
On startup, Froots scans three locations — the bundled skills/ directory, your workspace skills/ directory, and ~/.motive-x/pi/agent/skills/ — and discovers everything it finds. Each enabled, eligible skill contributes its name and description to a <skills> section in the system prompt.
What ships
Sixty-two skills ship with the app, plus three hardcoded system skills that are always present:
The three hardcoded system skills are safe-file-deletion (cannot be disabled — enforces a confirm step on destructive file ops), browser-automation (gated on the agent-browser binary), and openui (generative UI scaffolding).
A sampler from the catalog
A slice of what’s in the bundled skills/ directory, grouped by what people tend to reach for:
| Skill | What it does |
|---|---|
github | Read, comment, and ship PRs via the gh CLI |
obsidian | Read and edit your Obsidian vault as if it were your second brain |
notion | Pull pages, append blocks, search databases |
slack | Read channels, post messages, react to threads |
signal / telegram / imsg | Send and read messages on each platform |
apple-notes / bear-notes / things-mac | Native Apple-stack note and task capture |
| Skill | What it does |
|---|---|
browser-automation | Playwright-driven open / click / fill / screenshot |
summarize | Condense long documents or transcripts |
openai-whisper / openai-whisper-api | Transcribe audio locally or via API |
nano-banana-pro / openai-image-gen | Generate images |
blender | Drive Blender from the agent for 3D work |
image-to-3d / web-export-3d | Turn images into 3D scenes and export them |
| Skill | What it does |
|---|---|
1password | Look up secrets without leaking them into prompts |
spotify-player / sonoscli | Control music and speakers |
openhue / wyze | Smart-home lights and cameras |
weather | Current conditions and forecasts |
food-order / local-places / goplaces | Real-world search and ordering |
skill-creator | Scaffold and package new skills from inside the agent |
skill-creator to scaffold the folder, fill in the frontmatter, and drop instructions into SKILL.md for you.Eligibility and activation
When Froots discovers a skill, it runs an eligibility check based on the frontmatter — OS match, required binaries on PATH, required environment variables. Ineligible skills auto-disable; eligible ones are toggleable in the Skills tab.
| Step | Where in code |
|---|---|
| Discovery | SkillManager::discover() walks three skill directories |
| Eligibility | evaluate_eligibility() checks OS, binaries, env vars |
| State | skills-state.json tracks disabled list per assistant |
| Prompt build | generate_system_prompt() lists every enabled+eligible skill |
Toggling a skill off removes it from Pi’s live skills directory, so its SKILL.md is no longer included in the prompt on the next run. The model stops being told it knows that capability.
How the model picks one
There are no keyword triggers. No regex matches, no “activate when user mentions X.” Activation is purely semantic: the model sees the list of enabled skills with their one-line descriptions, and decides which apply to your request.
The skill-creator guidance is explicit about this: descriptions should name both *what* the skill does and *when* to use it, because that’s the only signal the model gets. A skill description like “Search the web and cite sources” works; “Web stuff” does not.
Three flavors
The system actually exposes three related concepts under one tab:
- Skill. A
SKILL.md-based prompt fragment. The 62 bundled ones are all this kind. - Extension. A TypeScript runtime plugin (e.g.
browser.ts,widget-generator.ts) that registers actual tool implementations. - Prompt. A markdown file dropped in
~/.motive-x/pi/agent/prompts/that becomes a reusable custom prompt fragment.
Most users only interact with the first kind. The other two exist for power users who want to ship runtime code or build their own reusable prompts.
Authoring
Two paths. The fast one: create a folder under ~/.motive-x/pi/agent/skills/{name}/, drop a SKILL.md in it, restart the app. The skill is discovered on next launch.
The structured one: use init_skill.py to scaffold a templated SKILL.md plus the optional subdirectories, and package_skill.py to bundle it into a distributable .skill (zip) file you can share.