octomind-tap — Agent Registry Guide

Community-maintained registry of agent manifests, capability definitions, dependency scripts, skill packs, and public workflows for the 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/<domain>/<spec>.toml     # Agent manifests — the primary contribution type
capabilities/<name>/
  config.toml                   # Capability metadata: triggers (+ optional domains gate)
  default.toml                  # Symlink → active provider (e.g. duckduckgo.toml)
  <provider>.toml               # Provider wiring: [deps], [roles.mcp], [[mcp.servers]]
deps/<org>/<tool>.sh            # Dependency install scripts (auto-run before sessions)
deps/<org>/<tool>.md            # Required companion doc for every dep script
deps/lib/platform.sh            # Shared platform detection (source in all dep scripts)
skills/<name>/SKILL.md          # Reusable instruction packs (AgentSkills spec)
skills/<name>/activate|validate # Optional scripts (exit 0 = activate / valid)
workflows/<name>.toml           # Public multi-step workflows — `octomind workflow <name>`
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 / lint-workflows / 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 scripts/lint-manifests.sh [agents/<domain>/<spec>.toml ...]   # lint agents
bash scripts/lint-capabilities.sh [capabilities/<name> ...]        # lint capabilities
bash scripts/lint-skills.sh [skills/<name>]                        # lint skills
bash scripts/lint-deps.sh [deps/<org>/<tool>.sh]                   # lint dep scripts + docs
bash scripts/lint-workflows.sh [workflows/<name>.toml]             # lint workflows (+ octomind --dry-run)
bash scripts/validate-capabilities.sh                              # resolution check, all agents
bash scripts/setup-symlinks.sh                                     # create/refresh default.toml links
bin/load <domain>:<spec>                                           # 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 | <capability> ...]   # rewrite pins; leaves changes uncommitted
scripts/mcp-versions.sh test [<capability> ...]             # spawn servers, MCP handshake, tools/list

pre-commit run --all-files                   # local hooks: shfmt, whitespace, check-toml, 4 lints
octomind run <domain>:<spec>                 # smoke-test an agent from repo root
octomind workflow <name> --dry-run           # validate a workflow, run nothing
bash scripts/smoke-render.sh [dir]           # install artifact CLIs, render deck/PDF/DOCX/resume/thumbnail/captions

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.
• CI: .github/workflows/lint.yml runs setup-symlinks, lint-manifests, lint-capabilities, validate-capabilities, lint-skills, lint-deps, and scripts/test-seo-providers.py on every push/PR; test-deps.yml runs each changed dep script twice (install + idempotency) on clean Ubuntu, macOS, and Windows; render-smoke.yml runs scripts/smoke-render.sh on Linux and macOS when the artifact CLIs or their deps change.

Where to Look

How Things Work

Capability-Based Agents (the only way)

Agents declare what they need, not how to get it:

# ✅ 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

# ❌ forbidden — never write these in an agent manifest
[deps]
require = [...]

[roles.mcp]
server_refs = [...]
allowed_tools = [...]

[[mcp.servers]]
name = "..."

bin/load <domain>:<spec> resolves each capability → reads capabilities/<name>/default.toml → merges [deps], [roles.mcp], and [[mcp.servers]] into the final manifest at runtime. Manifests name capabilities only; users switch providers with [capabilities] <name> = "<provider>" in their Octomind config, never in a manifest.

Capability Files (two kinds per capability)

capabilities/<name>/<provider>.toml — provider wiring, with # Capability:, # Provider:, # Title: (5–60 chars), # Description: (20–160 chars) header comments:

[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/<name>/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. A deliberate older pin carries # mcp-versions: hold <package> plus the reason; update skips it and check reports it as held.

Agent Manifest Rules

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":

<identity>          who/what (3–5 lines)
<voice>             tone (omit for technical agents)
<scope>             ✅ own / ❌ route elsewhere
<workflow>          numbered steps + sub-protocols
<rules>             tables, decision matrices, domain knowledge
<examples>          good/bad pairs (omit if N/A)
<output_format>     artifact shape, file paths, schemas
<interaction>       trigger → response patterns
<critical>          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/<name>/SKILL.md

Full authoring spec, rationale, anti-patterns: skills/tap-agent-authoring/SKILL.md.

Capability Access Tiers (least privilege)

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 <file.toml|name> — 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}}, {{<step-name>}}). 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 <name>) and delegate via command = "octomind acp <role>".

Naming Conventions

• Agent files: agents/<domain>/<spec>.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/<org>/<tool>.sh — matches require = ["<org>/<tool>"] in capability files
• Skills: skills/<name>/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 <command>)
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):

# dep: <org>/<tool>
# type: mcp|dep        # mcp = makes an MCP server runnable; dep = standalone CLI/runtime
# description: Brief description of what this installs
# check: <command-to-verify-installation>
# https://homepage-url

Companion documentation — every dep script needs deps/<org>/<tool>.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):

DEPS_LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" && pwd)"
source "$DEPS_LIB/platform.sh"

if pkg_check "<command>"; 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:

Skill Format (AgentSkills spec)

---
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 <use|forget|list>

Rule expressions — list items are OR branches; multiple expressions on one line are AND:

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/<file> 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/<name>/config.toml — triggers = [...] (required), optional domains gate
2. Create capabilities/<name>/<provider>.toml — header comments + [deps], [roles.mcp], [[mcp.servers]]; pin exact versions for npx/uvx servers
3. Add link "<name>" "<provider>.toml" and "<name>" 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/<org>/<tool>.sh + .md referenced in [deps] require
6. Reference "<name>" in agent capabilities = [...] — default.toml picks the provider; users override it in their own [capabilities] config
7. Adding capability triggers changes model/ training data — see skills/tap-model-training/SKILL.md for retraining

Placeholders

Done

Run the commands that touch what you changed — all must exit 0:

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/lint-workflows.sh        # touched workflows/… or the README workflow count
bash scripts/validate-capabilities.sh # any capability change
bash scripts/setup-symlinks.sh        # any capability add/remove (symlink integrity)
bin/load <domain>:<spec>              # touched agent — resolves without errors
scripts/mcp-versions.sh test <capability>  # touched npx/uvx server wiring
octomind workflow <name> --dry-run    # touched workflow

Agent done — lints pass (incl. markdown/cache guardrails); XML blocks in canonical order; every capability has capabilities/<name>/default.toml; all require entries exist under deps/; welcome is descriptive and includes {{CWD}}; octomind run <domain>:<spec> 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/<org>/<tool>.sh exits 0 on an already-installed machine and installs on a clean one.

Full-repo done — all six 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 <provider>.toml capabilities/<name>/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/<domain>/<spec>.toml or skills deeper than skills/<name>/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