git:20260713.5014c42 to git:20260713.f1c298c

13 added, 3 removed. Audit A to A.

# octomind-tap — Agent Registry Guide

Community-maintained registry of agent manifests, capability definitions, dependency scripts, and skill packs for the [Octomind](https://github.com/muvon/octomind) AI assistant. Agents declare **capabilities** (not MCP servers directly) — the `bin/load` resolver merges them at runtime. Contributions are global and public; the `octomind/` domain contains meta-agents that operate on the tap itself.

## Project Structure

```

agents/<domain>/<spec>.toml # Agent manifests — the primary contribution type

capabilities/<name>/ # Capability definitions

default.toml # Symlink → active provider (e.g. octofs.toml)

<provider>.toml # Actual capability file with [deps], [roles.mcp], [[mcp.servers]]

deps/<org>/<tool>.sh # Dependency install scripts (auto-run before sessions)

deps/lib/platform.sh # Shared platform detection helpers (source in all dep scripts)

skills/<name>/SKILL.md # Reusable instruction packs (AgentSkills spec)

skills/<name>/activate # Optional: auto-activation script (exit 0 = activate)

skills/<name>/validate # Optional: validation script (exit 0 = valid, stderr = error)

+ workflows/<name>.toml # Public multi-step workflows — run via `octomind workflow <name>`

+ model/ # Embedding model fine-tune powering capability auto-activation

bin/load # Python resolver: merges capabilities → final manifest (stdout)

scripts/

lint-manifests.sh # Validate all agent TOML files

+ lint-capabilities.sh # Validate all capability TOML files

lint-skills.sh # Validate all SKILL.md files

- validate-capabilities.sh # Check capability files are well-formed

+ lint-deps.sh # Validate dep scripts (headers + companion docs)

+ validate-capabilities.sh # Check capability resolution for all agents

setup-symlinks.sh # Create/refresh default.toml symlinks for all capabilities

templates/

agent.toml # Canonical agent template (copy to start a new agent)

skill.md # Canonical skill template (copy to start a new skill)

dep.sh # Canonical dep script template (copy to start a new dep)

ARCHITECTURE.md # Canonical design doc — read before making any changes

CONTRIBUTING.md # Contribution guidelines

```

## Where to Look

| Task | Start here |

|------|------------|

| Add a new agent | Copy `templates/agent.toml` → `agents/<domain>/<spec>.toml` |

| Understand capability system | `ARCHITECTURE.md` — full design + capability table |

| See all available capabilities | `ARCHITECTURE.md` capability table + `capabilities/` directory |

| Add a new capability | `capabilities/<name>/<provider>.toml` + update `scripts/setup-symlinks.sh` |

| Add a new dep script | Copy `templates/dep.sh` → `deps/<org>/<tool>.sh` + `templates/dep-mcp.md` or `templates/dep-tool.md` → `deps/<org>/<tool>.md` |

| Lint dep scripts | `scripts/lint-deps.sh` |

| Add a new skill | Copy `templates/skill.md` → `skills/<name>/SKILL.md` |

| Lint agents | `scripts/lint-manifests.sh` |

| Lint skills | `scripts/lint-skills.sh` |

| Resolve a manifest (debug) | `bin/load <domain>:<spec>` — prints merged TOML to stdout |

| Refresh capability symlinks | `scripts/setup-symlinks.sh` |

| Platform detection in dep scripts | `deps/lib/platform.sh` — source this, never re-implement |

- | Build a multi-step pipeline | External `octomind workflow <file.toml>` — see the `octomind-workflow` skill / `octomind:workflow` agent |

+ | Build a multi-step pipeline | `workflows/<name>.toml` — run via `octomind workflow <name>`; author with the `octomind-workflow` skill / `octomind:workflow` agent |

| Meta-agents (tap/skill/instructions) | `agents/octomind/` — these operate on the tap itself |

## 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 <domain>:<spec>` resolves each capability → reads `capabilities/<name>/default.toml` → merges `[deps]`, `[roles.mcp]`, and `[[mcp.servers]]` into the final manifest at runtime.

### Capability File Format

```toml

# capabilities/<name>/<provider>.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 = []

```

**Built-in servers** (`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.

### Agent Manifest Rules

| Field | Rule |

|-------|------|

| `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 (see below). Stable run-to-run for prompt caching. |

| `welcome` | Required; use `{{CWD}}` and `{{DATE}}` here only — these break caching if used in `system` |

| `temperature` | Required; 0.1–0.3 for technical, 0.4–0.6 for general |

| `top_p` | Required; 0.9 for most cases |

| `top_k` | Required; 0 to disable, 10–40 for more deterministic output |

### System Prompt Structure (2026 standard — XML-tagged blocks)

System prompts must use XML-tagged blocks in a fixed U-shape order. Identity goes first (primacy), critical rules go 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; reserve all-caps for one or two genuine safety hard-stops

```

**Tone calibration (Claude 4.5+ over-emphasis):** Claude 4.5/4.6/4.7 are far more responsive to the system prompt than 3.x. Aggressive language written to defeat under-triggering on older models now over-triggers. Substance stays; theatre goes.

- `CRITICAL: YOU MUST use tool X when …` → `Use tool X when …`

- `🚨 HARD RULES` + stacked `NEVER`/`ALWAYS` bullets → plain `Don't …` / `Do …` lines

- `MANDATORY: Run validation` → `Run validation after edits.`

- `DEFAULT TO using web search` → `Use web search when it would enhance your understanding.`

Reserve all-caps for one or two genuine safety hard-stops (e.g. `Never force-push to main`). Stacking ten of them dilutes the signal. Full recipe + verbatim Anthropic guidance + 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 `##` or `#` markdown headers — XML tags replace them (only `### Subsection` allowed inside an XML block when there are 2+ subsections)

- No `{{CWD}}` or `{{DATE}}` anywhere in `system` — they break prompt caching (system must be stable run-to-run); place them in `welcome` only

- Target: 200–1000 words total. Beyond ~1500 words, context rot degrades recall.

See `skills/tap-agent-authoring/SKILL.md` for the full authoring spec, rationale, and anti-patterns. For prompt-engineering theory across all surfaces (agents, skills, layer prompts) see `skills/prompt-engineering/SKILL.md`.

### Multi-Step Pipelines (external)

Agents are `capabilities` + one `[[roles]]` — they do **not** define multi-step pipelines. The old in-manifest `workflow = "..."` field and `[[workflows]]` block were removed from Octomind.

- Multi-step AI orchestration is now an external CLI: `octomind workflow <file.toml>` — a portable TOML that chains `octomind run` invocations (sequential / parallel / loop / conditional steps), piping output between them by name. It references installed roles and tap-agent tags; no manifest edits needed. Author one with the `octomind-workflow` skill, or use the `octomind:workflow` agent.

+ Multi-step AI orchestration is now an external CLI: `octomind workflow <file.toml>` — a portable TOML that chains `octomind run` invocations (sequential / parallel / loop / conditional steps), piping output between them by name. It references installed roles and tap-agent tags; no manifest edits needed. The tap ships ready-made workflows in `workflows/<name>.toml` (see `workflows/README.md`) — run them by name: `octomind workflow <name>`. Author one with the `octomind-workflow` skill, or use the `octomind:workflow` agent.

`[[layers]]` still exist in Octomind config (not in tap manifests): they back the `[[commands]]` slash-command system (`/run <name>`) and delegate to a role via `command = "octomind acp <role>"`.

### Naming Conventions

- **Agent files**: `agents/<domain>/<spec>.toml` — domain groups related agents (e.g. `developer`, `lawyer`, `devops`)

- **Capabilities**: lowercase with hyphens; use prefix grouping for related variants: `programming-rust`, `programming-python`, `legal-us`, `legal-uk`

- **Dep scripts**: `deps/<org>/<tool>.sh` — matches `require = ["<org>/<tool>"]` in capability files

- **Skills**: `skills/<name>/SKILL.md` — directory name must match `name:` field in frontmatter; 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 them

2. Exit 0 immediately if the tool is already installed (`pkg_check <command>`)

3. Install for every supported platform: macOS (brew or official installer) + Linux (apt/dnf/pacman/zypper/apk + universal 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: <org>/<tool>

# type: mcp|dep

# description: Brief description of what this installs

# check: <command-to-verify-installation>

# https://homepage-url

```

**Type classification:**

- `mcp` — script exists to make an MCP server runnable (ensures npx/uvx/docker)

- `dep` — script installs a standalone CLI tool or runtime used directly

**Companion documentation** — every dep script must have a matching `.md` file:

- `deps/<org>/<tool>.md` alongside `deps/<org>/<tool>.sh`

- MCP servers (`type: mcp`): must include `## MCP Server`, `## Authentication`, `## Available Tools`, `## Configuration Example`

- Plain deps (`type: dep`): must include `## Key Commands`, `## Common Usage`

- Templates: `templates/dep-mcp.md` and `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 "<command>"; then exit 0; fi

```

**Variables available after sourcing `platform.sh`:**

| Variable | Values |

|----------|--------|

| `$OS` | `macos` \| `linux` |

| `$ARCH` | `x86_64` \| `arm64` |

| `$IS_MACOS` | `1` or `0` |

| `$IS_LINUX` | `1` or `0` |

| `$IS_ARM64` | `1` or `0` |

| `$IS_X86_64` | `1` or `0` |

**Functions available after sourcing `platform.sh`:**

| Function | Purpose |

|----------|---------|

| `pkg_check <cmd>` | Returns 0 if command exists — use for fast-path exit and post-install verify |

| `pkg_install <pkg>` | Install via detected package manager (same name on all PMs) |

| `brew_install <formula>` | macOS only, no-op on Linux |

| `apt_install <pkg>` | Debian/Ubuntu only, no-op elsewhere |

| `dnf_install <pkg>` | Fedora/RHEL only, no-op elsewhere |

| `install_dep <org/tool>` | Run another dep script as a prerequisite; sources PATH env after |

| `info <msg>` | Print informational message to stderr |

| `warn <msg>` | Print warning to stderr |

| `die <msg>` | Print error to stderr and exit 1 |

**Platform coverage requirement** — every dep script must handle:

```bash

case "$OS" in

macos)

# brew preferred; fall back to official installer if brew absent

;;

linux)

case "$PKG_MANAGER" in

apt) ... ;;

dnf) ... ;;

pacman) ... ;;

zypper) ... ;;

apk) ... ;;

*) # universal fallback: curl/wget official installer ;;

esac

;;

esac

```

### Skill Format (AgentSkills spec)

```markdown

---

name: skill-name

title: "Skill Title (5–60 chars)"

description: "What this skill does and when to use it."

license: Apache-2.0

compatibility: "Requires: tool1, tool2. macOS/Linux."

capabilities: versioning memory-read

domains: developer devops

---

# Skill Title

## Overview

...

## Mental model (optional but recommended for skills with >3 rules)

...

## Rules / Instructions

...

## Examples

...

## Checklist

...

## Composition / References

...

```

Required frontmatter: `name`, `title`, `description`. Directory name must match `name`.

Optional fields:

- `capabilities` — capabilities to auto-load when skill activates (space-delimited or array)

- `domains` — agent categories for auto-activation scoping (omit for manual-only)

- `allowed-tools` — space-delimited pre-approved tools

**Section order matters (U-shape):** Overview at top (primacy), Checklist near the end (recency — final gate before action). The middle holds bulk knowledge with `## H2` anchors that survive lost-in-the-middle.

**Hard rules enforced by `lint-skills.sh`:**

- No `**bold**` in body outside code — markdown headers and lists provide structure

- Target: under ~2000 words. Beyond that, context rot hits skill recall.

See `skills/tap-skill-authoring/SKILL.md` for the full authoring spec.

### Skill Scripts (Optional)

Skills can include `activate` and `validate` scripts alongside SKILL.md:

- **`activate`** — executable script that decides if the skill should be active. Receives event type (`user`|`assistant`|`turn`) as argv[1], content on stdin. Runs in project workdir. exit 0 = activate, non-zero = don't. Already-active skills are skipped.

- **`validate`** — executable script that validates LLM output. Runs at end of assistant turn. exit 0 = valid, non-zero = invalid (stderr fed back to LLM). Retries capped by `[skills] max_retries`.

Both must be executable (`chmod +x`). The lint script checks this.

### Environment Variable

Preload skills at session start without activate scripts:

```bash

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

```

### Adding a New Capability (full checklist)

1. Create `capabilities/<name>/<provider>.toml` with `[deps]`, `[roles.mcp]`, `[[mcp.servers]]`

2. Add `link "<name>" "<provider>.toml"` line to `scripts/setup-symlinks.sh`

3. Add `"<name>"` to the `DECLARED` array in `scripts/setup-symlinks.sh`

4. Run `bash scripts/setup-symlinks.sh` to create the symlink

5. Reference `"<name>"` in agent `capabilities = [...]`

## Validation & Quality

### Checks to Run

```bash

# Lint all agent manifests

bash scripts/lint-manifests.sh

# Lint a specific agent

bash scripts/lint-manifests.sh agents/<domain>/<spec>.toml

+ # Lint all capability files

+ bash scripts/lint-capabilities.sh

+ # Validate capability resolution for all agents

+ bash scripts/validate-capabilities.sh

# Lint all skills

bash scripts/lint-skills.sh

# Lint a specific skill

bash scripts/lint-skills.sh skills/<name>

# Lint all dep scripts (headers + companion docs)

bash scripts/lint-deps.sh

# Lint a specific dep script

bash scripts/lint-deps.sh deps/<org>/<tool>.sh

# Verify capability symlinks are intact

bash scripts/setup-symlinks.sh

# Debug: inspect the resolved manifest for an agent

bin/load <domain>:<spec>

```

### Quality Criteria — Agent is "Done" When

- [ ] All lints pass (`lint-manifests.sh`) — including the markdown/cache guardrails

- [ ] System prompt uses XML-tagged blocks in canonical order (`<identity>` → … → `<critical>`)

- [ ] No `**bold**` or `##` headers inside `system` (XML tags are the structure)

- [ ] No `{{CWD}}` or `{{DATE}}` inside `system` — those go in `welcome` only (caching)

- [ ] Every capability in `capabilities = [...]` has a `capabilities/<name>/default.toml`

- [ ] `bin/load <domain>:<spec>` resolves without errors

- [ ] All required dep scripts exist under `deps/` for every `require` entry in used capabilities

- [ ] All dep scripts pass linting (`lint-deps.sh`) — includes `# type:` header and companion `.md`

- [ ] System prompt is domain-focused and covers what the agent does, what it won't do, and key decision rules

- [ ] `welcome` message is descriptive and includes `{{CWD}}`

### Quality Criteria — Skill is "Done" When

- [ ] `lint-skills.sh` passes — including `**bold**` markdown guardrail

- [ ] `name` in frontmatter matches directory name exactly

- [ ] Body follows the canonical section order (Overview → Mental model → Rules → Examples → Checklist → Composition / References)

- [ ] Checklist sits near the end (recency position) — not buried mid-body

- [ ] Instructions are actionable (tell the AI what to DO, not just describe the domain)

- [ ] **Domain-isolated** — `domains:` is a single value where possible; body does NOT reference agents from other domains (`content:article`, `developer:typescript`, `marketing:seo`, etc.); `compatibility:` describes environment only, not skill pairings. Cross-domain composition is the orchestrating agent's job.

## Gotchas

- `bin/load` uses a regex-based TOML parser (no external deps) — it handles the subset needed but does not parse full TOML. Keep capability files simple; don't use multi-line arrays or complex TOML features.

- `setup-symlinks.sh` uses `ln -sf` (force) — safe to re-run, but the `DECLARED` array must be updated manually when adding capabilities or the script will emit a `WARN` for undeclared dirs.

- `capabilities/core/default.toml` and `capabilities/agent/default.toml` are real files, not symlinks — they have no provider variants. Do not add `link` entries for them in `setup-symlinks.sh`.

- `{{ENV:VAR_NAME}}` in capability files injects environment variables at runtime (e.g. `TAVILY_API_KEY`). Document required env vars in the capability file header comment.

- The `octomind/` agent domain is special — these agents operate on the tap itself. Run `octomind run octomind:tap` in this repo root to use the tap-creation assistant.

## Never

- Write `[deps]`, `[roles.mcp]`, or `[[mcp.servers]]` in an agent manifest — these belong exclusively in capability files

- Set `name = "..."` inside `[[roles]]` — it is injected at runtime from the file path tag

- Add a `server_ref` in a capability file without a matching `[[mcp.servers]]` block (unless it's a built-in: `core`, `octofs`, `agent`, `octocode`)

- 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` — exactly two path components required

- Nest skills deeper than `skills/<name>/SKILL.md` — exactly one directory level required