git:20260831.dfdf9c4 to git:20260918.d2bccbd

- 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.

- 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/lib/platform.sh # Shared platform detection helpers (source in all dep scripts)

- 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

- 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)

- scaffolds/tap/ # `octomind tap init` source: scaffold.toml contract + root/ tree

- # (templates/ and deps/lib/platform.sh are symlinks into it)

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

- CONTRIBUTING.md # Contribution guidelines

- | 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 | `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 |

- | Change what `octomind tap init` generates | `scaffolds/tap/` — edit `root/`, keep `scaffold.toml` in sync |

- `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

- **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.

- | `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 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."

- <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.

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

- - `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`.

- - 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`.

- 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. 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>"`.

- - **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`

- - **Skills**: `skills/<name>/SKILL.md` — directory name must match `name:` field in frontmatter; lowercase, hyphens only

- 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)

- # type: mcp|dep

- **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`

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

-

- | Variable | Values |

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

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

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

- | `$PKG_MANAGER` | `brew` \| `apt` \| `dnf` \| `pacman` \| `zypper` \| `apk` \| `unknown` |

- | `$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`:**

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

- | `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

- ```

- name: skill-name

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

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

- 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

- ```

- 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.

- - `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.

- - 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`)

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