docs: document skills support

2 files changed, 38 insertions, 0 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a79898b..bb8fb42 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -73,6 +73,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   at runtime so there is still no icon file to install. Send is now a square
   button beside the entry box with its label under the icon, and New/Attach
   sit at the right end of the picker row.
+- Skills. Instruction files read from `~/.agents/skills/*/SKILL.md` can be
+  loaded into the model's context on demand: the model calls a `load_skill`
+  tool, or you type `/skill-name` or mention a skill's name. Loaded skills
+  stay for the whole session in chat mode, drop after the reply in one-shot
+  mode, and show as removable chips. The backend tool loop now dispatches
+  between `web_search` and `load_skill`; `max_searches` caps total tool
+  rounds per turn.
 
 ### Fixed
 
diff --git a/README.md b/README.md
index 24a5d7f..77ce895 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,11 @@ persistent process and toggles like a scratchpad from a Hyprland keybind.
   offered a `web_search` tool and calls it when a question needs current
   information; the queries and their sources show as a collapsible block
   above the reply. See [Web search](#web-search).
+- **Skills.** Instruction files read from `~/.agents/skills/*/SKILL.md`,
+  loaded into the model's context on demand. The model can call a
+  `load_skill` tool when a task matches one; you can type `/skill-name` or
+  mention a skill's name. Loaded skills show as removable chips, stay for
+  the whole session in chat mode, and drop after the reply in one-shot mode.
 - **Tray icon** for show/hide/quit, hosted by waybar's tray module.
 
 Not in this version: RAG or embedding search over history, multi-user
@@ -150,6 +155,12 @@ search_results = 5
 search_snippet_chars = 300
 search_timeout = 10
 max_searches = 2
+
+# Skills. Instruction files in ~/.agents/skills/*/SKILL.md, loaded into the
+# model's context on demand. On by default; a directory that does not exist
+# stays off.
+skills_enabled = true
+skills_dir = "~/.agents/skills"
 ```
 
 `presets.ini` is read for two things the API does not report: which models
@@ -464,6 +475,26 @@ None of that stops a poisoned snippet from influencing what the model says.
 If a top result asserts something false, a 9B may repeat it. That is why the
 sources stay visible rather than being hidden behind the answer.
 
+### Skills
+
+Instruction files read from the skills directory, one `SKILL.md` per skill
+inside `<name>/`. Each file starts with a YAML frontmatter block carrying the
+`name` and `description`, followed by the instructions. Skills live outside
+the app (in `~/.agents/skills` by default) so they can be edited, diffed and
+kept in version control.
+
+A skill is loaded into the model's context on demand, three ways:
+
+- The model calls a `load_skill` tool when a task matches a skill's
+  description.
+- You type `/skill-name` on its own line.
+- You mention a skill's name anywhere in the message.
+
+Loaded skills show as removable chips above the input. They stay loaded for
+the whole session in chat mode and drop after the reply in one-shot mode.
+`max_searches` caps the total tool rounds per turn here too, so skills load
+and searches share the same per-turn budget.
+
 ### External providers
 
 llamachat can talk to OpenAI-compatible cloud providers alongside the local