Skills · rousseau-agent docs

Skill format

A skill is a Markdown file with an optional YAML front-matter header. Format is deliberately close to the agentskills.io convention so files are portable to other tools.

Example — ~/.local/share/rousseau/skills/git-rebase.md:

---
name: git-rebase
description: Guide the user through an interactive rebase safely.
triggers:
  - rebase
  - git rebase
  - squash
  - autosquash
---
When helping with a git rebase, first verify the current HEAD is
pushed to a remote branch. Prefer `git rebase -i --autosquash`
when the user has fixup commits. Never force-push to `main`.

Frontmatter fields

Field	Type	Effect
`name`	string	Matches `^[a-z][a-z0-9-]*$`. Displayed by `rousseau skills list`.
`description`	string	One-line summary.
`triggers`	`[]string`	Case-insensitive substrings. If any appears in the user message, the skill activates. Empty means the skill never auto-activates.

Everything after the closing --- is the skill body, verbatim.

Discovery

The loader scans agent.skills_dir for *.md files (non-recursive). A missing directory is not an error — Load returns nil. Subdirectories are ignored.

agent:
  skills_dir: ~/.local/share/rousseau/skills

Activation

For every user turn, SkillsProvider.SystemAppendix(session) inspects the most recent user message and matches each skill's triggers (case-insensitively). Every match is concatenated (in load order) and spliced into the system prompt for that turn.

Skills with empty triggers never auto-activate but can be included programmatically by callers embedding the library.

CLI

# List discovered skills.
rousseau skills list

# Show the content of a single skill.
rousseau skills show git-rebase

Design constraints

No code execution. Skills are strings. They cannot run scripts or shell commands. If you want automation, wire a new tool via Registry.Register instead.
No versioning. rousseau does not track skill versions. Manage that in git — the skills_dir is expected to be a working copy of a repository.
Deterministic. The same session + user message produces the same appendix. There is no LLM in the loop.

Writing effective skills

Keep the body short (100–500 words). Every activation is prepended to the system prompt for that turn.
Prefer imperative sentences ("When the user asks about X, do Y") over exposition.
Use triggers for high-precision phrases; wide triggers ("code", "help") activate on nearly every turn and drown out other skills.
Test in the TUI (rousseau chat) before rolling into a chat-transport daemon — the log line agent.skills_activated lists which skills fired.