# octomind-tap — Agent Registry Guide Community-maintained registry of agent manifests, capability definitions, dependency scripts, skill packs, and public workflows for the [Octomind](https://github.com/muvon/octomind) AI assistant. Agents declare **capabilities** (never MCP servers directly) — the `bin/load` resolver merges provider wiring at runtime. Contributions are global and public; the `octomind/` domain holds meta-agents that operate on the tap itself. No build step — correctness is defined by the lint scripts. ## Project Structure ``` agents//.toml # Agent manifests — the primary contribution type capabilities// config.toml # Capability metadata: triggers (+ optional domains gate) default.toml # Symlink → active provider (e.g. duckduckgo.toml) .toml # Provider wiring: [deps], [roles.mcp], [[mcp.servers]] deps//.sh # Dependency install scripts (auto-run before sessions) deps//.md # Required companion doc for every dep script deps/lib/platform.sh # Shared platform detection (source in all dep scripts) skills//SKILL.md # Reusable instruction packs (AgentSkills spec) skills//activate|validate # Optional scripts (exit 0 = activate / valid) workflows/.toml # Public multi-step workflows — `octomind workflow ` model/ # Embedding fine-tune powering capability auto-activation bin/load # Python resolver: merges capabilities → manifest on stdout scripts/ # lint-manifests / lint-capabilities / lint-skills / # lint-deps / validate-capabilities / setup-symlinks / # mcp-versions (MCP version pin management) templates/ # Canonical templates — symlink into scaffolds/tap/root/ scaffolds/tap/ # `octomind tap init` source: scaffold.toml + root/ tree ARCHITECTURE.md # Canonical design doc — read before any change CONTRIBUTING.md # Human contribution guide (partially pre-capability; this file wins) ``` ## Commands ```bash bash scripts/lint-manifests.sh [agents//.toml ...] # lint agents bash scripts/lint-capabilities.sh [capabilities/ ...] # lint capabilities bash scripts/lint-skills.sh [skills/] # lint skills bash scripts/lint-deps.sh [deps//.sh] # lint dep scripts + docs bash scripts/validate-capabilities.sh # resolution check, all agents bash scripts/setup-symlinks.sh # create/refresh default.toml links bin/load : # debug: print resolved manifest scripts/mcp-versions.sh check [--strict] # pin drift vs npm/PyPI latest (strict → exit 1) scripts/mcp-versions.sh update [--all | ...] # rewrite pins; leaves changes uncommitted scripts/mcp-versions.sh test [ ...] # spawn servers, MCP handshake, tools/list pre-commit run --all-files # local hooks: shfmt, whitespace, check-toml, 3 lints octomind run : # smoke-test an agent from repo root octomind workflow --dry-run # validate a workflow, run nothing cd model && uv sync && bin/train # embedding model full pipeline (--skip-export to skip ONNX) ``` - All lint scripts and `mcp-versions.sh` need Python 3.11+ (or `pip install tomli`). - `pre-commit` runs `shfmt -w -s -i 2 -ci` on shell scripts — run it before committing dep scripts; `lint-deps.sh` is **not** in pre-commit, run it manually. - `[UNCONFIRMED]` ARCHITECTURE.md says the five lint scripts run in `.github/workflows/lint.yml` on every push/PR; no `.github/` exists in this checkout. ## Where to Look | Task | Start here | |------|------------| | Add a new agent | Copy `templates/agent.toml` → `agents//.toml`; spec: `skills/tap-agent-authoring/SKILL.md` | | Add a new capability | Copy `templates/capability.toml` + `templates/capability-config.toml` → `capabilities//`; spec: `skills/tap-capability-authoring/SKILL.md` | | Add a new skill | Copy `templates/skill.md` → `skills//SKILL.md`; spec: `skills/tap-skill-authoring/SKILL.md` | | Add a new dep script | Copy `templates/dep.sh` + `templates/dep-mcp.md` or `templates/dep-tool.md` → `deps//`; spec: `skills/tap-deps-authoring/SKILL.md` | | Add a new workflow | Copy `templates/workflow.toml` → `workflows/.toml`; spec: `skills/octomind-workflow/SKILL.md` + `workflows/README.md` | | Understand the capability system | `ARCHITECTURE.md` — design, capability table, access tiers | | Prompt engineering theory | `skills/prompt-engineering/SKILL.md` (+ `reference/claude-4-emphasis-and-tools.md`) | | Train the embedding model | `model/README.md`; spec: `skills/tap-model-training/SKILL.md` | | Resolve a manifest (debug) | `bin/load :` — merged TOML on stdout | | Platform helpers in dep scripts | `deps/lib/platform.sh` — source it, never re-implement | | Meta-agents (tap/workflow/config) | `agents/octomind/` — they operate on the tap itself | | Change what `octomind tap init` generates | `scaffolds/tap/` — edit `root/`, keep `scaffold.toml` and `scaffolds/tap/README.md` in sync | ## How Things Work ### Capability-Based Agents (the only way) Agents declare **what they need**, not how to get it: ```toml # ✅ correct — capability-based capabilities = ["core", "filesystem-read", "filesystem-write", "shell", "codesearch-semantic", "codesearch-structural", "codesearch-graph", "programming-rust"] [[roles]] system = "..." welcome = "..." temperature = 0.3 top_p = 0.9 top_k = 0 ``` ```toml # ❌ forbidden — never write these in an agent manifest [deps] require = [...] [roles.mcp] server_refs = [...] allowed_tools = [...] [[mcp.servers]] name = "..." ``` `bin/load :` resolves each capability → reads `capabilities//default.toml` (or `:` for an explicit provider) → merges `[deps]`, `[roles.mcp]`, and `[[mcp.servers]]` into the final manifest at runtime. ### Capability Files (two kinds per capability) `capabilities//.toml` — provider wiring, with `# Capability:`, `# Provider:`, `# Title:` (5–60 chars), `# Description:` (20–160 chars) header comments: ```toml [deps] require = ["muvon/octofs"] # dep scripts to run before session [roles.mcp] server_refs = ["octofs"] # MCP server names to activate allowed_tools = ["octofs:*"] # tools to expose (wildcards OK) [[mcp.servers]] # REQUIRED if server_ref is non-builtin name = "octofs" type = "stdio" command = "octofs" args = ["mcp"] timeout_seconds = 300 tools = [] # env = { API_KEY = "{{ENV:API_KEY}}" } # exact env var names read by the child ``` `capabilities//config.toml` — routing metadata: non-empty `triggers = [...]` (user phrasings for deterministic auto-activation; also training data for the `model/` embedding) and an optional `domains = ["developer"]` hard gate. No Title/Description required. **Built-in server refs** (`core`, `octofs`, `agent`, `octocode`) do NOT need `[[mcp.servers]]` blocks. Every other server ref MUST have a matching `[[mcp.servers]]` block in its capability file. **Version pins** — every registry-launched server (npx/uvx, including inside `sh -c`) must pin an exact package version (`pkg@X.Y.Z` / `pkg==X.Y.Z`) so a registry publish can never change what users run. `lint-capabilities.sh` enforces pin presence offline; `scripts/mcp-versions.sh` handles drift, updates, and live smoke-tests. ### Agent Manifest Rules | Field | Rule | |-------|------| | Header comments | `# Agent: :`, `# Title:` (5–60 chars), `# Description:` (20–160 chars) — required, linted | | `capabilities = [...]` | Required at top level; drives everything | | `[[roles]]` | Exactly one entry | | `name` | Must NOT be set — injected at runtime from the tag | | `system` | Required; XML-tagged blocks in canonical order (below); stable run-to-run for prompt caching | | `welcome` | Required; `{{CWD}}` and `{{DATE}}` allowed here only — they break caching if used in `system` | | `temperature` / `top_p` / `top_k` | Required; 0.1–0.3 technical / 0.4–0.6 general; `top_p` 0.9; `top_k` 0 to disable, 10–40 for determinism | | `model` | Optional override, e.g. `"openrouter:anthropic/claude-sonnet-4"` | ### System Prompt Structure (2026 standard — XML-tagged blocks) Fixed U-shape order. Identity first (primacy), critical rules last (recency); the middle relies on tag anchors to survive "lost in the middle": ``` who/what (3–5 lines) tone (omit for technical agents) ✅ own / ❌ route elsewhere numbered steps + sub-protocols tables, decision matrices, domain knowledge good/bad pairs (omit if N/A) artifact shape, file paths, schemas trigger → response patterns brief Don't/Do list in plain language ``` **Tone calibration (Claude 4.5+ over-emphasis):** aggressive language written for 3.x now over-triggers. Substance stays; theatre goes. - `CRITICAL: YOU MUST use tool X when …` → `Use tool X when …` - `🚨 HARD RULES` + stacked `NEVER`/`ALWAYS` → plain `Don't …` / `Do …` - `MANDATORY: Run validation` → `Run validation after edits.` Reserve all-caps for one or two genuine safety hard-stops (e.g. `Never force-push to main`). Full recipe + parallel-tool-calls block: `skills/prompt-engineering/reference/claude-4-emphasis-and-tools.md`. **Hard rules enforced by `lint-manifests.sh`:** - No `**bold**` outside code — XML tags provide structure - No `##`/`#` markdown headers — XML tags replace them (only `### Subsection` allowed inside a block with 2+ subsections) - No `{{CWD}}` or `{{DATE}}` in `system` — place in `welcome` only (caching) - Target 200–1000 words; beyond ~1500, context rot degrades recall - No tap-relative paths (`skills/…`, `capabilities/…`, `deps/…`) in `system` or `welcome` — agents run in the project workdir, not the tap checkout; name the skill instead (`octomind` domain exempt) - Every `` `name` skill `` mentioned must exist at `skills//SKILL.md` Full authoring spec, rationale, anti-patterns: `skills/tap-agent-authoring/SKILL.md`. ### Capability Access Tiers (least privilege) | Tier | Capability | Tools | Who declares it | |------|-----------|-------|-----------------| | self-management | `core` | `plan` | **every** agent | | do the work | domain caps | `shell`, `filesystem-*`, `codesearch-*`, `legal-*`, … | per agent | | intra-domain team | `agent` | `agent_*` | sub-orchestrators | | orchestration | `orchestration` | `tap`, `schedule` | orchestrators only (e.g. `assistant:concierge`, `developer:general`) | | runtime config | `runtime` | `mcp`, `agent`-register, `skill`, `capability` | high-trust only | A narrow specialist declares `core` + domain capabilities and never `orchestration`/`runtime` — enforced structurally: the unwanted server never enters the tool surface. `orchestration`/`runtime` may still auto-activate on intent via their `config.toml` triggers; that is temporary, never a standing grant. ### Multi-Step Pipelines (external) Agents are `capabilities` + one `[[roles]]` — they do **not** define pipelines. The old in-manifest `workflow = "..."` field and `[[workflows]]` block were removed from Octomind. Orchestration is an external CLI: `octomind workflow ` — portable TOML chaining `octomind run` invocations (sequential / parallel / loop / conditional steps, plus graph routing via `entry`, `max_transitions`, `[[edges]]`), piping output between steps by name (`{{input}}`, `{{}}`). Rules that bite: - Workflows fetched from a tap may use **public tap roles only** (`category:variant` tags) — no local config roles; this keeps them portable. - Driving input arrives on stdin; validate with `--dry-run` before running. - Author with `templates/workflow.toml`, the `octomind-workflow` skill, or the `octomind:workflow` agent; catalogue: `workflows/README.md`. `[[layers]]` still exist in Octomind config (not tap manifests): they back `[[commands]]` slash commands (`/run `) and delegate via `command = "octomind acp "`. ### Naming Conventions - **Agent files**: `agents//.toml` — exactly two path components; domain groups related agents - **Capabilities**: lowercase-hyphens; prefix grouping for variants: `programming-rust`, `legal-us`, `messaging-slack` - **Dep scripts**: `deps//.sh` — matches `require = ["/"]` in capability files - **Skills**: `skills//SKILL.md` — exactly one directory level; directory name must match frontmatter `name`; lowercase-hyphens only ### Dep Script Pattern Every dep script must: 1. Source `deps/lib/platform.sh` — all helpers and variables come from here, never re-implement 2. Exit 0 immediately if already installed (`pkg_check `) 3. Install on every supported platform: macOS (brew, official-installer fallback) + Linux (apt/dnf/pacman/zypper/apk + universal curl/wget fallback) 4. Verify the tool is in PATH after install; add `~/.local/bin` or `~/.cargo/bin` if needed **Required header comments** (parsed by tooling): ```bash # dep: / # type: mcp|dep # mcp = makes an MCP server runnable; dep = standalone CLI/runtime # description: Brief description of what this installs # check: # https://homepage-url ``` **Companion documentation** — every dep script needs `deps//.md`: - `type: mcp` → sections `## MCP Server`, `## Authentication`, `## Available Tools`, `## Configuration Example` - `type: dep` → sections `## Key Commands`, `## Common Usage` - Templates: `templates/dep-mcp.md`, `templates/dep-tool.md` **Boilerplate** (copy from `templates/dep.sh`): ```bash DEPS_LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" && pwd)" source "$DEPS_LIB/platform.sh" if pkg_check ""; then exit 0; fi ``` **Variables after sourcing `platform.sh`:** `$OS` (`macos`|`linux`) · `$ARCH` (`x86_64`|`arm64`) · `$PKG_MANAGER` (`brew`|`apt`|`dnf`|`pacman`|`zypper`|`apk`|`unknown`) · `$IS_MACOS` / `$IS_LINUX` / `$IS_ARM64` / `$IS_X86_64` (1 or 0) **Functions after sourcing `platform.sh`:** | Function | Purpose | |----------|---------| | `pkg_check ` | 0 if command exists — fast-path exit and post-install verify | | `pkg_install ` | Install via detected package manager (same name on all PMs) | | `brew_install` / `apt_install` / `dnf_install` | Platform-scoped, no-op elsewhere | | `install_dep ` | Run another dep script as prerequisite; sources PATH env after | | `info` / `warn` / `die` | stderr messaging; `die` exits 1 | ### Skill Format (AgentSkills spec) ```markdown --- name: skill-name # required; matches directory name; ≤64 chars, lowercase-hyphens title: "Skill Title" # required; 5–60 chars description: "What and when." # required; 20–1024 chars license: Apache-2.0 compatibility: "Requires: tool1. macOS/Linux." # ≤500 chars; environment only — never skill pairings capabilities: versioning memory-read # auto-load capabilities on activation domains: developer devops # auto-activation scoping; omit for manual-only rules: # auto-activation expressions; omit for manual-only - file(Cargo.toml) - content(rust) content(async) --- ``` Optional dirs alongside SKILL.md: `scripts/`, `references/`, `assets/`, plus `activate` and `validate` executables. **Activation — three methods:** - Env preload: `OCTOMIND_SKILLS=programming-rust,git-workflow octomind run developer:general` (permanent, no rules evaluated) - Auto-activation: skills whose `domains` match the agent's domain get their `rules` evaluated on conversation events; already-active skills are skipped - Manual: `skill(action="use"|"forget"|"list", name=...)` or `/skill ` **Rule expressions** — list items are OR branches; multiple expressions on one line are AND: | Expression | Matches when | |------------|-------------| | `file()` | File matching glob exists in workdir (`*`, `**`) | | `content()` | User message contains the word (whole-word, case-insensitive) | | `match()` | User message matches the pattern | | `grep(, )` | A file matching the glob contains a matching line | | `env()` / `env(=)` | Env var set / equals value | | `bin()` | Command available in `$PATH` | | `workdir()` | CWD path contains the pattern (substring) | | `session()` | Session name contains the word (e.g. `developer:rust`) | **Scripts:** `activate` receives event type (`user`|`assistant`|`turn`) as argv[1], content on stdin, runs in project workdir; exit 0 = activate. `validate` same interface at end of assistant turn; non-zero = invalid, stderr is fed back to the LLM (retries capped by `[skills] max_retries`). Both must be executable. **Body — U-shape section order:** Overview (top) → Mental model → Rules → Examples → Checklist (near the end — final gate) → Composition / References. Under ~2000 words; beyond that, context rot hits skill recall. **Hard rules enforced by `lint-skills.sh`:** valid frontmatter; required fields and length limits; `name` matches directory; non-empty body; every `reference/` cited exists; `validate` executable; no `**bold**` in body outside code. **Domain isolation:** `domains:` single-valued where possible; body does NOT reference agents from other domains (`content:article`, `developer:typescript`, …); `compatibility:` describes environment only. Cross-domain composition is the orchestrating agent's job. ### Adding a New Capability (full checklist) 1. Create `capabilities//config.toml` — `triggers = [...]` (required), optional `domains` gate 2. Create `capabilities//.toml` — header comments + `[deps]`, `[roles.mcp]`, `[[mcp.servers]]`; pin exact versions for npx/uvx servers 3. Add `link "" ".toml"` **and** `""` to the `DECLARED` array in `scripts/setup-symlinks.sh` 4. Run `bash scripts/setup-symlinks.sh` (exits 1 on MISSING, warns on undeclared dirs) 5. Create any `deps//.sh` + `.md` referenced in `[deps] require` 6. Reference `""` (default provider) or `":"` in agent `capabilities = [...]` 7. Adding capability triggers changes `model/` training data — see `skills/tap-model-training/SKILL.md` for retraining ### Placeholders | Placeholder | Scope | Use | |-------------|-------|-----| | `{{CWD}}` | Session | Current working directory — `welcome` only in agents (breaks caching in `system`) | | `{{DATE}}` | Session | Current date — same caching rule | | `{{ENV:KEY}}` | Project env | Injects environment variable (e.g. API keys) in capability files; document required vars in the capability header comment | | `{{INPUT:KEY}}` | User-global secret | API tokens, credentials (e.g. in `[[mcp.servers]] env`) | ## Done Run the commands that touch what you changed — all must exit 0: ```bash bash scripts/lint-manifests.sh # touched agents/…toml bash scripts/lint-capabilities.sh # touched capabilities/… bash scripts/lint-skills.sh # touched skills/… bash scripts/lint-deps.sh # touched deps/… bash scripts/validate-capabilities.sh # any capability change bash scripts/setup-symlinks.sh # any capability add/remove (symlink integrity) bin/load : # touched agent — resolves without errors scripts/mcp-versions.sh test # touched npx/uvx server wiring octomind workflow --dry-run # touched workflow ``` **Agent done** — lints pass (incl. markdown/cache guardrails); XML blocks in canonical order; every capability has `capabilities//default.toml`; all `require` entries exist under `deps/`; `welcome` is descriptive and includes `{{CWD}}`; `octomind run :` starts clean. **Skill done** — lints pass; `name` matches directory; canonical section order with Checklist near the end; instructions actionable (what to DO); domain-isolated. **Capability done** — lints pass; `default.toml` symlink resolves; pins present; `mcp-versions.sh test` speaks MCP. **Dep done** — `lint-deps.sh` passes (headers, `# type:`, companion `.md`, platform coverage); `bash deps//.sh` exits 0 on an already-installed machine and installs on a clean one. **Full-repo done** — all five lint scripts + `pre-commit run --all-files` exit 0. ## Gotchas - `bin/load` uses a regex-based TOML-subset parser (no external deps) — keep capability files simple: no multi-line arrays or complex TOML features. - `setup-symlinks.sh` uses `ln -sf` (force) — safe to re-run; the `DECLARED` array must be updated manually or the script emits `WARN` for undeclared dirs. - `capabilities/core/`, `capabilities/agent/`, and `capabilities/orchestration/` have **real** `default.toml` files — no provider variants, no `link` entries for them. - Default providers live in `setup-symlinks.sh` — e.g. `websearch` currently defaults to `duckduckgo.toml` (not tavily; ARCHITECTURE.md's example is stale). Switch a provider with `ln -sf .toml capabilities//default.toml`; reset all with `setup-symlinks.sh`. - `templates/` and `deps/lib/platform.sh` are symlinks into `scaffolds/tap/root/` — single source of truth so generated taps never drift; edit at the scaffold source. - The `octomind/` agent domain is special — its agents operate on the tap itself. Run `octomind run octomind:tap` in this repo root for the tap-authoring assistant (`octomind:workflow`, `octomind:config`, `octomind:assistant` alongside). - `mcp-versions.sh test` may report missing-key errors for servers needing credentials — judge by whether the process starts and speaks MCP at all. - CONTRIBUTING.md quick-start examples still write `[roles.mcp]`/`[deps]` directly (pre-capability style) — this file and ARCHITECTURE.md are authoritative when they conflict. ## Never - Write `[deps]`, `[roles.mcp]`, or `[[mcp.servers]]` in an agent manifest — they belong exclusively in capability files - Set `name = "..."` inside `[[roles]]` — injected at runtime from the file path tag - Add a `server_ref` without a matching `[[mcp.servers]]` block (built-ins exempt: `core`, `octofs`, `agent`, `octocode`) - Launch an npx/uvx server without an exact version pin - Add `orchestration` or `runtime` to a leaf/domain-specialist agent — orchestrator- and high-trust-tier only - Create a capability directory without adding it to both the `link` calls and the `DECLARED` array in `setup-symlinks.sh` - Nest agents deeper than `agents//.toml` or skills deeper than `skills//SKILL.md` - Reference tap-relative paths or cross-domain agent tags in `system`/`welcome`/skill bodies — agents run in the user's project, not the tap checkout ## References - `ARCHITECTURE.md` — canonical design; read before any structural change - `CONTRIBUTING.md` — human-facing contribution guide (partially stale; this file wins) - `workflows/README.md` — workflow catalogue, resolution rules, TOML structure - `model/README.md` — embedding fine-tune pipeline (dataset → train → eval gates → ONNX → HuggingFace) - `scaffolds/tap/README.md` — `octomind tap init` token table and renderer rules - `skills/tap-agent-authoring/SKILL.md` · `tap-capability-authoring` · `tap-skill-authoring` · `tap-deps-authoring` · `tap-model-training` — per-type authoring specs - `skills/prompt-engineering/SKILL.md` — prompt theory across agents, skills, layer prompts - `skills/octomind-workflow/SKILL.md` — workflow authoring spec