feat: add freebsd-cost-optimization skill (Sam & Claude)

skills/freebsd/freebsd-cost-optimization.md

@@ -0,0 +1,34 @@
+---
+name: freebsd-cost-optimization
+description: How to use Colibri's fast/smart/max cost modes to minimize DeepSeek API spending on FreeBSD deployments
+---
+
+# FreeBSD Cost Optimization
+
+## Cost modes
+
+Colibri supports three cost modes that control context window usage:
+
+- **fast** — tighter context budget, compaction triggers earlier. Use for
+  high-volume, low-importance tasks (log scanning, status checks).
+- **smart** (default) — balanced budget. Most agent sessions should run here.
+- **max** — preserves full context, compaction only when absolutely necessary.
+  Use for complex multi-step tasks where losing history would cause rework.
+
+## When to escalate
+
+The daemon auto-escalates fast→smart→max when compaction alone cannot keep the
+session within budget. This is intent, not a policy engine — the thresholds are
+fixed in `colibri-daemon/src/cost.rs`:
+
+- fast: budget 4K tokens, compact at 80%
+- smart: budget 16K tokens, compact at 75%
+- max: budget 64K tokens, compact at 90%
+
+## Operator tips
+
+- Set `COLIBRI_COST_MODE=fast` in `/etc/rc.conf` for disposable worker agents.
+- Use `colibri set-cost-mode smart` via the CLI for interactive sessions.
+- Monitor cache-hit rate via `colibri status` — if it drops below 50%,
+  consider escalating to the next mode.
+- On FreeBSD live USB, the default is `smart` to balance cost and capability.