v1.0 to v1.1

- description: "Explains how octomind assembles a session at runtime: tap resolution of category:variant tags, manifest placeholders, capability activation and the deterministic embedding auto-activator, domain gating, LRU eviction of the tool surface, skill discovery and the three activation methods, local .agents/tools scripts, and sandbox mode. Activate when a user asks why a tool or skill did or did not appear, how a tag resolves, how capability auto-activation decides, why a capability was evicted or refused, or where skills and taps live on disk."

- - match((?i)\.agents/(tools|skills)\b)

- version: "1.0"

- This skill explains how a session's tool surface comes to exist: how a tag resolves through taps into a manifest, how capabilities turn into running MCP servers, how the auto-activator decides without an LLM in the loop, and how skills, local tools, and the sandbox fit in.

- It covers how resolution works, not how to author registry files — writing manifests, capabilities, deps, and skills belongs to the `tap-*` authoring skills.

- Every exposed tool costs prompt tokens on every turn, and a wide tool zoo makes the model pick wrong tools. So the surface is deliberately small and grows on demand: capabilities load when intent matches, and the least-recently-used one is evicted when the active set is full.

- Two independent layers stack. Static comes from the role's own manifest at boot; dynamic is what a capability adds at runtime. The distinction decides what eviction may tear down: a server the role statically owns is never killed, only the overlay tools a capability added on top of it.

- A tap is a Git repo or local directory holding `agents/<category>/<variant>.toml`, `capabilities/<name>/`, `skills/<name>/`, and `deps/<org>/<tool>.sh`. Manage them with `octomind tap [TAP] [PATH]` and `octomind untap`. The built-in `muvon/tap` is always present as last-priority fallback and can be neither added nor removed.

- Priority: user-added taps in the order added, then the built-in tap. When several provide the same tag, the first-listed wins and a debug line is logged — the same first-wins rule applies to skills and capabilities.

- Running a tag containing a colon triggers the full pipeline: fetch the manifest from taps (cached), expand `capabilities = [...]`, resolve `{{INPUT:KEY}}` and `{{ENV:KEY}}` placeholders, run `[deps] require` scripts before MCP init, inject the tag as the role name, merge into config, start the session. A missing credential prompts at the placeholder step, not at startup. Manifest caching is governed by `[registry].cache_ttl_hours`, with stale-serve plus background refresh.

- Inside a session, the `tap` tool runs a tap role as a subagent: `discover`, `run`, `list`, `stop`. Each run returns an id like `tap-lawyer-sg-9b2c1d`, reusable to stop or resume it.

- ### Capability anatomy

- A capability directory holds two kinds of file. `config.toml` carries capability-level metadata: a required `triggers = [...]` array driving auto-activation and `discover`, plus an optional `domains = [...]`. Missing `config.toml` or missing triggers means the capability fails to resolve. The `<provider>.toml` files carry the MCP wiring — `[[mcp.servers]]`, `server_refs`, `allowed_tools`, `[deps]` — with the provider chosen by the `[capabilities]` config map, defaulting to `default`.

- Triggers live in `config.toml`, never in a provider file.

- ### The capability tool

- Hosted by the builtin `runtime` server alongside `mcp`, `agent`, and `skill`. Actions: `list` (installed capabilities in the current domain, active ones marked), `discover` (semantic search over triggers by `intent`, dropping anything at or below a 0.2 cosine floor, returning up to five), `enable`, and `disable`. Enable and disable are idempotent.

- Activation registers each `[[mcp.servers]]` block, computing a per-server tool filter from `allowed_tools` — namespace prefixes are stripped to bare names and patterns scoped to other servers are dropped. A server already in the role's static config is not re-registered; the capability extends the role's effective filter instead. A capability with no servers but a non-empty `[deps]` is a toolchain capability, and running the dep installers is the activation.

- Runs before every API request when `auto_capabilities` is true, embedding the user message and matching it against hand-authored triggers — no LLM in the routing loop.

-

- The decision: strip XML blocks so pasted content cannot drive matches, bail if the cleaned intent has fewer than 8 non-whitespace characters, drop out-of-domain and already-active capabilities before embedding, embed the intent once, then score each capability as the mean of the top-3 cosines against its triggers.

- | `AUTO_ACTIVATE_THRESHOLD` | `0.45` | Minimum mean-of-top-3 cosine |

- | `AUTO_ACTIVATE_MARGIN` | `0.08` | Required gap between top-1 and top-2 |

- The margin gate is why two near-tied capabilities cause abstention rather than a coin flip. Silent no-ops: master toggle off, message not a fresh user message, intent too short, embedding model still downloading, no eligible capability, or no score clearing the gate.

-

- Triggers rather than descriptions, because descriptions use abstract domain language while user messages are concrete and verbal. Triggers put the capability centroid where users actually write.

- The session domain is the category part of the active role — `developer` for `developer:general`. An empty `domains` list means universal; a non-empty one restricts the capability to those domains. The gate applies at every entry point with no bypass: `list` and `discover` silently omit out-of-domain capabilities, auto-activation filters them before embedding, and `enable` hard-fails with an error naming the role you would need. `OCTOMIND_CAPABILITIES` boot-loading goes through the same gated path. With no domain set at all, only universal capabilities survive.

- The active set has a soft cap of four. Activating beyond it disables the least-recently-used capability first. Eviction is the only auto-disable mechanism — no time decay, no domain-shift eviction, because false-disable hurts more than carrying an idle capability.

-

- Recency means real successful tool usage, not activation order; failed calls do not refresh the timestamp, so a flapping server stays evictable.

- Shared servers are safe. Each capability records exactly which bare tool names it registered per server, and the kill decision is `!static_owned && refcount == 0`. Another active capability referencing the server, or the role statically owning it, means only this capability's tools are stripped while the process keeps running. So a chunky capability can be split into focused sub-capabilities pointing at the same binary without one tearing down the others.

- Discovered from three locations, first-wins by name: taps (`<tap>/skills/<name>/SKILL.md`), the project dir `<workdir>/.agents/skills/`, and the global dir `~/.config/agents/skills/`. Tap skills shadow universal ones.

- Three activation methods: `OCTOMIND_SKILLS` preloads at session start; declarative `rules:` auto-activate, which requires both a non-empty `rules:` list and a `domains:` entry matching the current role, on fresh user messages only; and manual `/skill <name>` or the `skill` MCP tool.

- The parser reads exactly `name`, `description`, `compatibility`, `license`, `allowed-tools`, `capabilities`, `domains`, and `rules`. Other keys are silently ignored, and a skill missing `name` or `description` is skipped entirely. Files under `scripts/`, `references/`, and `assets/` are listed with absolute paths in a `## Skill Resources` section on activation, so the model can open them on demand.

- A shebang script at `<workdir>/.agents/tools/<name>` becomes an MCP tool under server `local` — auto-discovered, role-agnostic, no config. The filename is the tool name and must match `[A-Za-z0-9_-]+` with no extension; on Unix it must be executable. The leading comment block declares the schema with `@description` and repeatable `@param NAME TYPE DESC`, parsed with `#`, `//`, or `--` prefixes and stopping at the first non-comment line or after 80 lines. Parameters arrive as `OCTOMIND_PARAM_<NAME>` environment variables. Skills inject instructions; local tools expose executable actions.

- `sandbox = true` in config, or `--sandbox` per run, restricts all filesystem writes to the launch directory at OS level — Landlock on Linux 5.13+, Seatbelt on macOS. It binds child processes too, including shell and MCP servers.

- Work the chain in order: is the capability in the role's `capabilities` list or expected to auto-activate; does its `config.toml` have triggers; is the session domain in its `domains`; did the intent clear 0.45 with a 0.08 margin; was it evicted by the four-capability cap. Each step has a distinct fix, and guessing at the wrong one wastes the turn.

- What changed: messages under 8 non-whitespace characters are suppressed deliberately, because short acknowledgments produce noisy embeddings that clear the threshold by coincidence.

- That is the margin gate abstaining on a near tie, not a failure. Supply the disambiguating signal — name the engine, or call `capability(action="discover", intent=...)` and enable explicitly.

- - [ ] Symptom traced to a specific stage: tap resolution, capability activation, domain gate, or eviction?

- - [ ] Skill directory name equals its frontmatter `name`?