From 3231253fe049b94196457957330701d2a9e3b933 Mon Sep 17 00:00:00 2001
From: Amolith <amolith@secluded.site>
Date: Sat, 7 Feb 2026 19:52:38 -0700
Subject: [PATCH] docs: add researching-with-rumilo to skill list

---
 README.md                               | 22 ++++++++--
 skills/researching-with-rumilo/SKILL.md | 57 +++++++++++++++++++++++++
 2 files changed, 75 insertions(+), 4 deletions(-)
 create mode 100644 skills/researching-with-rumilo/SKILL.md

diff --git a/README.md b/README.md
index 848afb23ed8530500b54d2bd8be45393c94b901d..37d708344c6873447965d312f5b57976f6ab5168 100644
--- a/README.md
+++ b/README.md
@@ -62,6 +62,10 @@ token count, plus overall metadata usage. I've used and tested them most with
   from simple rebases to the drop-and-repick integration branch pattern. Assumes
   `upstream` remote for forks and `rerere` enabled. Supports worktrees including
   `wt`-managed repos.
+- [researching-with-rumilo](skills/researching-with-rumilo/SKILL.md): Dispatch AI
+  research subagents via [rumilo] for web search and repository exploration.
+  Research topics, look up library usage, or explore external codebases without
+  filling the main context window.
 - [resuming-work-through-lunatask](skills/resuming-work-through-lunatask/SKILL.md):
   Resume deferred work from [Lunatask] handoff notes via [lune].
 - [reviewing-code](skills/reviewing-code/SKILL.md): Review code for correctness,
@@ -89,6 +93,7 @@ token count, plus overall metadata usage. I've used and tested them most with
 [git-format]: https://git.secluded.site/git-format
 [lune]: https://git.secluded.site/lune
 [Lunatask]: https://lunatask.app/
+[rumilo]: https://git.secluded.site/rumilo
 [synu]: https://git.secluded.site/synu
 [wt]: https://git.secluded.site/wt
 [gum]: https://github.com/charmbracelet/gum
@@ -328,6 +333,15 @@ Token breakdown:
   Total:        5906 tokens
   ⚠️  Body exceeds recommended 5000 token budget!
 
+=== researching-with-rumilo ===
+
+Token breakdown:
+  Name:           25 tokens
+  Description:   159 tokens
+  Body:         1319 tokens (49 lines)
+  ───────────────────────────────────────────────
+  Total:        1503 tokens
+
 === resuming-work-through-lunatask ===
 
 Token breakdown:
@@ -406,10 +420,10 @@ Token breakdown:
 SUMMARY
 ============================================================
 
-Skills: 19
-Metadata: 2752 tokens
-Combined bodies: 49998 tokens
-Overall: 167525 tokens
+Skills: 20
+Metadata: 2936 tokens
+Combined bodies: 51317 tokens
+Overall: 169028 tokens
 Validation errors: 0
 
 Largest skills (by total tokens):
diff --git a/skills/researching-with-rumilo/SKILL.md b/skills/researching-with-rumilo/SKILL.md
new file mode 100644
index 0000000000000000000000000000000000000000..df474d2940da98b89a2c437a5e0f6be81aa36bfa
--- /dev/null
+++ b/skills/researching-with-rumilo/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: researching-with-rumilo
+description: Dispatches AI research subagents via rumilo to search the web or explore git repositories. Use when the user asks to research a topic, look up library usage, explore a codebase, read documentation from the web, or when you need information from an external repository or website to complete a task.
+license: AGPL-3.0-or-later
+metadata:
+  author: Amolith <amolith@secluded.site>
+---
+
+`rumilo` spawns disposable AI subagents for two kinds of research: **web search** and **repo exploration**. Each mode runs in isolation and returns a synthesised answer on stdout.
+
+## Modes
+
+### Web mode
+
+Search the internet or ask questions about a specific page.
+
+```bash
+# Open-ended search (no URL)
+rumilo web "what is the current stable version of Zig"
+
+# Question about a specific page (URL pre-fetched into context)
+rumilo web "how does the slog package handle log levels" -u "https://pkg.go.dev/log/slog"
+```
+
+- Without `-u`, the agent searches the web on its own.
+- With `-u`, the URL is fetched first and injected into the agent's context alongside the query, so it can answer questions _about_ that page.
+
+### Repo mode
+
+Clone a git repository into a temp directory, spawn an agent inside it, and let it explore the source to answer questions.
+
+```bash
+# Public repo
+rumilo repo -u "https://github.com/owner/repo" "How does the routing system work?"
+
+# Private repo (works with any clonable URI — SSH, HTTPS with auth, etc.)
+rumilo repo -u "git@git.sr.ht:~user/repo" "What does the Config struct look like?"
+```
+
+The `-u` flag is **required** in repo mode — it needs something to clone.
+
+## Flags
+
+| Flag                       | Modes | Effect                                                            |
+| -------------------------- | ----- | ----------------------------------------------------------------- |
+| `-u <url>`                 | both  | Seed URL (web) or clone URI (repo)                                |
+| `--model <provider:model>` | both  | Override the configured default model                             |
+| `--ref <ref>`              | repo  | Checkout a branch, tag, or commit after cloning (requires --full) |
+| `--full`                   | repo  | Full clone instead of shallow (depth 1)                           |
+| `--no-cleanup`             | both  | Keep the temp workspace after exit                                |
+| `--verbose`                | both  | Print tool calls and results to stderr                            |
+
+## Choosing a mode
+
+- Need to find or learn about a library? **Web** to locate it, then **repo** to explore its source.
+- Need to understand how a dependency works in detail? **Repo** with the dependency's clone URL.
+- Need current docs, release notes, or general knowledge? **Web**, optionally with the URL of a relevant page.