Octomind 0.25.0: Skills That Actually Know When to Show Up

Every session with an AI assistant starts the same way. You're in a Rust project, you know the AI can help, but it doesn't know Rust's ownership rules, cargo workspaces, or clippy conventions — not until you manually feed it a prompt or load a skill. That first minute is always wasted on context bootstrapping.

We fixed this in 0.25.0.

This release overhauls how skills work. Instead of manual loading, skills now declare when they should activate using rules you write in plain text: file(Cargo.toml), content(rust), bin(cargo). The engine evaluates these in-process on every message. No script spawning, no network calls, no perceptible lag. The skill just appears when it's needed.

This is the biggest change since we introduced the skill system itself. And it changes how you think about AI sessions — from "what do I need to tell the AI?" to "the AI already knows where it is."

The Problem We Were Solving

In 0.24.0, skills were opt-in. You'd run /skill <name> to activate one. That worked for demos. In practice, you'd be three messages into debugging a borrow checker error before realizing the AI was answering in generic Python terms.

The learning system we shipped in 0.24.0 helped — it extracted lessons across sessions and injected them automatically. But lessons are retrospective. They capture what you already did. Skills are prospective: they give the AI the knowledge it needs before it starts answering.

What we needed was a bridge between the two. Something that looked at the current context — files on disk, the working directory, what you typed — and loaded the right skills without you asking.

Declarative Activation Rules

Here's what a skill looks like now:

---
name: programming-rust
title: 'Rust Development'
description: 'Rust conventions, idiomatic patterns, and cargo tooling.'
license: Apache-2.0
domains: developer
allowed-tools: shell text_editor
rules:
  - file(Cargo.toml)
  - content(rust)
  - content(rust) file(Cargo.toml)
---

The rules: field is new. Each line is an OR-group — if any group matches, the skill activates. Space-separated checks within a line are AND — all must match.

The check types are:

  • file(Cargo.toml) — file or glob exists in the working directory
  • content(rust) — word-boundary match in your message
  • grep(pattern, *.rs) — search file contents respecting .gitignore
  • env(RUST_LOG) — environment variable is set
  • match(\bdeploy\b) — regex match in your message
  • bin(cargo) — executable is on PATH
  • session(octomind) — session name contains the pattern
  • workdir(rust) — working directory path contains the pattern

These rules are evaluated in-process on every user message. No subprocesses, no I/O beyond a stat or a quick grep through an already-warmed cache. The overhead is negligible.

The domains: field scopes auto-activation to specific agent roles. A skill with domains: developer only auto-activates when you're using a developer agent. A writing agent won't trigger it. This prevents skill spam — you don't get Rust conventions injected when you're drafting a blog post.

What This Feels Like in Practice

You cd into a Rust project and start a session. Before you type anything, the skill engine has already seen Cargo.toml, checked that cargo is on PATH, and loaded programming-rust. Your first message is answered with Rust-specific knowledge already in context.

Or you're in a mixed project — a Next.js app with a Rust backend. You switch to the src-tauri directory. The engine notices the directory change, evaluates rules against the new workdir, and activates the Tauri skill. The AI now knows about tauri.conf.json, IPC patterns, and the Rust-JS bridge.

You can still toggle skills manually. /skill lists all skills, /skill 2 paginates, /skill *rust* filters by pattern, or /skill programming-rust toggles one on or off.

Environment Preloading

Sometimes you want skills active from the first message — before any context evaluation happens. The OCTOMIND_SKILLS environment variable does this:

OCTOMIND_SKILLS=programming-rust,git-workflow octomind run developer:general

These skills load during session startup, injecting their content before the first prompt. On resume, we detect which skills are already in the session and skip re-injecting them. This is useful for CI environments or when you know exactly what you need.

Per-Project Configuration via .env

Octomind reads .env files from the working directory automatically. This means you can define project-specific skills, API keys, and other environment variables without touching your shell:

# .env in your project root
OCTOMIND_SKILLS=programming-rust,content-voice
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Any environment variable Octomind uses can go here. The .env file is loaded at session start, so your project gets the right skills and credentials without manual setup.

npx Skills Support

Octomind now supports the npx skills ecosystem — skills distributed as npm packages that install into standard directories. Drop a skill with a SKILL.md file into either location and Octomind discovers it automatically:

  • Project-level: .agents/skills/ in your working directory
  • Global: ~/.config/agents/skills/ (xdg-basedir, matching the npx skills CLI)

This means any skill published to npm that follows the npx skills convention works in Octomind without a tap. Install it with npx skills install <package> and it's available in your next session.

Taps still take priority. If a skill exists in both a tap and a universal directory, the tap version wins. Taps remain the automated, versioned way to distribute skills — npx skills are the open ecosystem fallback.

Validation: Skills That Check Their Own Homework

Activation is only half the problem. The other half is: did the AI actually use the skill correctly?

Skills can now include a validate script. At the end of each assistant turn, every active skill's validator runs against the AI's output. The script gets the full assistant message on stdin. Exit 0 means the output passes. Anything on stderr is surfaced as feedback.

For programming-rust, the validator might run cargo check on generated code. For a skill about API design, it might grep for REST anti-patterns. The validator doesn't block execution — it appends hints that the AI sees on the next turn.

This is configured per-skill and globally:

[skills]
auto_activation = true
auto_validation = false   # opt-in per skill
validation_timeout = 60
max_retries = 3

Other Changes in 0.25.0

Skills got the headline, but there's more:

Plan persistence. Plans now survive session restarts. If you're mid-plan and your connection drops, resuming the session restores the active plan from the session log. The PLAN_SNAPSHOT and PLAN_CLEARED events in the log let us reconstruct state exactly.

Tag-based agent resolution. octomind run developer:general now fetches the tap manifest, resolves inputs and environment variables, runs dependency scripts, and merges the agent's config into your base config — all in one command. The tag is the identity. No more manual config stitching.

OAuth RFC 9728 discovery. MCP servers that support OAuth can now be auto-discovered via .well-known/oauth-protected-resource endpoints. We fetch the protected resource metadata, extract the authorization server, and complete RFC 8414 discovery. Less manual OAuth config, more "it just works."

Reliability fixes. We fixed deadlocks in MCP server status checks, data loss on partial line reads from server stdout, orphaned tool calls after compression, and infinite compression loops with escalation. The chat spinner no longer lags user prompts. UTF-8 boundary panics are gone.

/save removed. Sessions now auto-persist. The /save command is gone — no need to manually save when state is continuously written to disk. Under the hood, we now use reference-counted MCP server management — when a skill activates, its required capabilities (MCP servers) spin up; when it deactivates, they shut down if nothing else needs them.

Config additions. HTTP request timeout (request_timeout_seconds) is now configurable for provider calls. The [rules] section adds bin, session, and workdir checks for more precise skill activation.

And everything else. Rust toolchain bumped to 1.95.0, octolib upgraded to 0.16.0, security patches applied, session logging streamlined, and various internal refactors around compression handling and state persistence. The kind of maintenance that doesn't change how you use Octomind but keeps it stable.

Breaking Changes

This release has breaking changes around skills and sessions:

  • /save is removed. Sessions auto-persist state continuously.
  • Skills now require declarative rules: for auto-activation.
  • Skill management is toggle-based: /skill <name> enables if inactive, disables if active.

If you have custom skills without rules: or domains: fields, they'll become manual-only until you add them.

What's Next

We're already thinking about skill composition — what happens when multiple skills activate and their advice conflicts? And skill versioning, so a tap can ship updates without breaking your workflow.

But the immediate change is this: your AI assistant now knows what it's looking at before you tell it. That's the difference between a tool you drive and a collaborator who shows up prepared.

Explore available skills and domains at octomind.run/tap — all skills there now include declarative activation rules.

Download 0.25.0 from GitHub or run cargo install octomind --force.

Octomind is a session-based AI development assistant in Rust. Read more about how skills work in our deep dive on agent skills and auto-activation.