Community-maintained collection of agent manifests for Octomind — a session-based AI development assistant.

Each manifest is a single TOML file that defines a role (system prompt, model, tools) and optional MCP servers. Octomind fetches and merges it into your config at runtime — no installation, no global state.

# Run a registry agent directly
octomind run developer:rust

# Pin to a specific version
octomind run developer:rust@1.0

# With a sub-variant
octomind run developer:rust-nightly

domain:spec[-sub-spec][@version]

Examples:

developer:rust                 → agents/developer/rust.toml
developer:rust-nightly         → agents/developer/rust-nightly.toml
developer:rust@1.0             → agents/developer/rust.toml  (version hint, future use)
devops:k8s-helm                → agents/devops/k8s-helm.toml
data:python-ml                 → agents/data/python-ml.toml

Note on versioning: Version (@x.y) is parsed and passed through but the registry currently resolves to the same file path. Versioned paths (e.g. agents/developer/rust@1.0.toml) are reserved for future use. For now, use the unversioned tag and rely on the 24-hour cache TTL.

agents/
  developer/
    rust.toml
    typescript.toml
    general.toml
  devops/
    kubernetes.toml
  octomind/
    tap.toml          ← octomind:tap  — tap management agent
    skill.toml        ← octomind:skill — skill development agent
  security/
    owasp.toml
  ...
skills/
  git-workflow/
    SKILL.md          ← git commit conventions and workflow best practices
  code-review/
    SKILL.md          ← code review checklist and guidelines
  ...                 ← community skills (one directory per skill)
capabilities/
  core/
    default.toml      ← plan tool (built-in, no symlink needed)
  agent/
    default.toml      ← agent delegation (built-in, no symlink needed)
  filesystem/
    octofs.toml       ← provider: octofs MCP
    default.toml      → octofs.toml  (symlink, set by setup-symlinks.sh)
  codesearch/
    octocode.toml     ← provider: octocode MCP
    default.toml      → octocode.toml
  memory/
    octobrain.toml    ← provider: octobrain MCP
    default.toml      → octobrain.toml
  websearch/
    tavily.toml       ← provider: Tavily search MCP
    brave.toml        ← provider: Brave search MCP  (alternative)
    default.toml      → tavily.toml  (switch with: ln -sf brave.toml ...)
  versioning/
    git.toml          ← provider: git via shell
    default.toml      → git.toml
deps/
  lib/
    platform.sh       ← shared OS/arch/pkg-manager detection (sourced by all dep scripts)
  muvon/
    octocode.sh
  astral-sh/
    uv.sh
  nodejs/
    node.sh
  ...
templates/
  agent.toml          ← canonical agent manifest template
  skill.md            ← canonical SKILL.md template
bin/
  load              ← resolves capabilities and outputs a merged manifest to stdout
scripts/
  setup-symlinks.sh ← creates/forces default.toml symlinks; warns on missing providers
  lint-manifests.sh ← validates all agent TOML files
  lint-skills.sh    ← validates all skills/*/SKILL.md files per AgentSkills spec
  validate-capabilities.sh ← runs bin/load on every agent to catch resolution errors

Each agent file lives at agents/<domain>/<spec>.toml and is fetched via:

https://raw.githubusercontent.com/muvon/octomind-agents/main/agents/<domain>/<spec>.toml

Agents declare capabilities instead of hardcoding MCP servers. This decouples what an agent needs from how it is provided.

1. An agent declares capabilities = ["filesystem", "codesearch", "websearch"] at the top of its manifest.
2. At runtime, bin/load <domain>:<spec> resolves each capability to capabilities/<name>/default.toml.
3. default.toml is a symlink pointing to the active provider (e.g. octofs.toml, tavily.toml).
4. bin/load merges all [deps], server_refs, allowed_tools, and [[mcp.servers]] blocks into the final manifest output.

# Switch websearch from Tavily to Brave
ln -sf brave.toml capabilities/websearch/default.toml

# Or run the setup script to reset all defaults
bash scripts/setup-symlinks.sh

bash scripts/setup-symlinks.sh   # create/force all default.toml symlinks
chmod +x bin/load

# Validate all agents resolve correctly
bash scripts/validate-capabilities.sh

# agents/developer/rust.toml

capabilities = ["core", "filesystem", "codesearch", "versioning"]

[[roles]]
system = "..."
welcome = "🦀 Rust agent ready."
temperature = 0.2
top_p = 0.9
top_k = 0

# No [roles.mcp] needed — bin/load injects it from capabilities
# Add custom MCP servers here only for things NOT covered by capabilities:
# [[mcp.servers]]
# name = "my-special-server"
# ...

bin/load merges everything and outputs a complete, ready-to-use manifest to stdout.

A manifest is a TOML file with one required [[roles]] entry. Agents use either capabilities = [...] (preferred) or explicit [roles.mcp] + [[mcp.servers]] blocks.

# agents/developer/rust.toml

[[roles]]
# name is injected automatically from the tag — do not set it
system = """
You are an expert Rust developer assistant.
Working directory: {{CWD}}

You write idiomatic, safe, performant Rust...
"""
welcome = "🦀 Rust developer agent ready. Working in {{CWD}}"
temperature = 0.2
top_p = 0.9
top_k = 0

# Optional: override the global model for this role
# model = "anthropic/claude-sonnet-4-5"

[roles.mcp]
server_refs = ["core", "octofs", "agent"]
allowed_tools = ["core:*", "octofs:*", "agent_*"]

# Optional: add extra MCP servers (e.g. language-specific tooling via Docker)
# [[mcp.servers]]
# name = "rust-analyzer-mcp"
# type = "stdio"
# command = "docker"
# args = ["run", "--rm", "-i", "--volume", "{{CWD}}:/workspace", "ghcr.io/muvon/rust-analyzer-mcp:latest"]
# timeout_seconds = 60
# tools = []

Important: server_refs and [[mcp.servers]] serve different purposes:

To use a custom MCP server:

1. Define it in [[mcp.servers]] with name, type, command, args
2. Reference it in server_refs to make it available to the agent
3. (Optional) Restrict tools in allowed_tools

# Example: Adding a custom MCP server

[roles.mcp]
server_refs = ["core", "octofs", "my-custom-server"]
allowed_tools = ["core:*", "octofs:*", "my_custom-tool"]

[[mcp.servers]]
name = "my-custom-server"
type = "stdio"
command = "npx"
args = ["-y", "my-mcp-server"]
timeout_seconds = 60
tools = []

Built-in servers (always available, no [[mcp.servers]] needed):

• core — plan, mcp, agent tools
• octofs — view, text_editor, batch_edit, extract_lines, shell, workdir, ast_grep
• agent — agent_* tools for delegating to layers
• octocode — semantic_search, remember, memorize, view_signatures, graphrag (requires muvon/octocode dep)

Run octomind vars to see all available placeholders:

octomind vars              # List all placeholders
octomind vars --preview    # Show preview values
octomind vars --expand     # Show full values

Special placeholders:

Use for secrets that belong to the user globally — API tokens, personal access tokens, license keys. The user is prompted once on first use; the value is saved to ~/.local/share/octomind/inputs.toml and reused on every subsequent run across all projects.

system = """
GitHub token: {{INPUT:GITHUB_TOKEN}}
"""

Use for project-scoped or deployment-specific values — base URLs, feature flags, environment names, project IDs. The resolution order is:

1. If KEY is already set in the environment (and non-empty) → use it directly, no prompt.
2. If not set → prompt the user, then append KEY=VALUE to ./.env in the current working directory.

On the next run Octomind loads .env automatically, so the user is never prompted again for that project. The value also becomes available to MCP tools and shell commands in the session immediately.

system = """
API base URL: {{ENV:API_BASE_URL}}
Environment: {{ENV:DEPLOY_ENV}}
"""

When to use which:

When Octomind loads a manifest it additively merges it into the user's base config:

• [[roles]] — appended; duplicates (by name) are skipped
• [[mcp.servers]] — appended; duplicates (by name) are skipped
• Everything else — override semantics (manifest wins)

This means your personal config is never destructively modified.

Taps are Git repositories containing agent manifests. Octomind uses a Homebrew-style tap system:

• Default tap (muvon/tap) is always active — cloned automatically on first use and updated on every octomind run.
• User taps are checked before the default tap (first match wins).

# Add a GitHub tap (clones https://github.com/myorg/octomind-agents)
octomind tap myorg/agents

# Add a local tap (no clone — uses directory directly)
octomind tap myorg/agents /path/to/local/repo

# List all active taps
octomind tap

# Remove a tap
octomind untap myorg/agents

Tap repos are cloned to ~/.local/share/octomind/taps/<user>/octomind-<repo>/ and auto-updated via git pull on every run.

Manifests can declare external tools that must be present before the session starts. Octomind runs the corresponding scripts automatically on first use.

[deps]
require = ["astral-sh/uv", "nodejs/node"]

Each entry maps to deps/<org>/<tool>.sh inside the tap. Scripts run before MCP servers are initialised. If any script exits non-zero the session is aborted with a clear error.

Each script is self-sufficient — if it needs another tool (e.g. cargo), it invokes that dep script directly. No ordering required in the manifest.

Every dep script must follow two rules:

1. Self-sufficient — if it needs another tool to run (e.g. cargo), it sources that dep script itself. The caller never needs to set anything up beforehand.
2. Idempotent — exits 0 immediately if the tool is already installed. Safe to run twice, ten times, on every session start.

All dep scripts should source deps/lib/platform.sh for portable OS/arch/package-manager detection:

#!/usr/bin/env bash
source "$(dirname "${BASH_SOURCE[0]}")/../lib/platform.sh"
# (adjust relative path depth to match your location under deps/)

After sourcing, these are available:

Helper functions: pkg_install <pkg>, pkg_check <cmd>, info <msg>, die <msg>.

#!/usr/bin/env bash
# dep: <org>/<tool>
# description: One-line description
# check: <command-to-verify-install>

set -euo pipefail

# Resolve deps/lib/ relative to this script's location
DEPS_LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" && pwd)"
source "$DEPS_LIB/platform.sh"

# Fast path — already installed
if pkg_check <tool>; then
	exit 0
fi

# If this script depends on another dep, use install_dep:
# install_dep rust/cargo
# This runs the dep script and sources common env files (~/.cargo/env, ~/.local/bin).

info "<tool> not found — installing..."

case "$OS" in
	macos) brew_install <formula> ;;
	linux) pkg_install <package>  ;;
esac

Note: @modelcontextprotocol/* is the npm namespace for MCP reference implementations, not an org. For generic Node.js MCP servers, just use nodejs/node dep.

1. Create deps/<org>/<tool>.sh — use the template above.
2. chmod +x deps/<org>/<tool>.sh
3. Reference it in your manifest: [deps] require = ["<org>/<tool>"]
4. Test it on a clean machine (or a Docker container) before opening a PR.

1. Pick a tag following the naming convention: domain:spec or domain:spec-sub-spec.
2. Create the file at agents/<domain>/<spec>.toml (or agents/<domain>/<spec>-<sub>.toml).
3. Use the template below as a starting point.
4. Test locally before opening a PR:

# Add this repo as a local tap (one-time setup)
octomind tap muvon/tap /path/to/octomind-tap

# Run your agent
octomind run developer:your-new-agent

# Remove the local override when done
octomind untap muvon/tap

5. Open a PR with a short description of what the agent does and which tools/models it targets.

# agents/<domain>/<spec>.toml
# Agent: <domain>:<spec>
# Description: One-line description of what this agent does.

[[roles]]
# name is NOT set here — Octomind injects it automatically from the tag at runtime.
system = """
<Your system prompt here.>

Working directory: {{CWD}}

# Use {{INPUT:KEY}} for user-global secrets (API tokens, credentials).
# Prompted once, stored in ~/.local/share/octomind/inputs.toml.
# Example: GitHub token: {{INPUT:GITHUB_TOKEN}}

# Use {{ENV:KEY}} for project-scoped values (base URLs, env names, flags).
# Reads from environment if set; otherwise prompts and saves to ./.env.
# Example: API base: {{ENV:API_BASE_URL}}
"""
welcome = "<Emoji> <Short greeting>. Working in {{CWD}}"
temperature = 0.3
top_p = 0.9
top_k = 0

[roles.mcp]
server_refs = ["core", "octofs", "agent"]
allowed_tools = ["core:*", "octofs:*", "agent_*"]

# Optional: declare tools that must be installed before the session starts.
# Octomind runs deps/<org>/<tool>.sh from the tap automatically.
# [deps]
# require = ["astral-sh/uv", "nodejs/node"]

• Never set name — it is injected from the tag at runtime. Do not include it in the manifest.
• Keep system prompts focused — describe the persona, constraints, and preferred patterns. Avoid walls of text.
• Prefer {{CWD}} over hardcoded paths — manifests are used across machines.
• Use {{INPUT:KEY}} for user-global secrets — API tokens, credentials. Prompted once, stored in ~/.local/share/octomind/inputs.toml, reused across all projects.
• Use {{ENV:KEY}} for project-scoped values — base URLs, environment names, feature flags. Reads from the environment if set; otherwise prompts and saves to ./.env in the working directory. Never use {{ENV:KEY}} for secrets — the value lands in a plain-text file.
• Declare deps for non-Docker tooling — if your agent needs a CLI tool that isn't wrapped in Docker, add a dep script and reference it via [deps] require = [...]. See Dependency Scripts.
• Docker for zero-install tooling — if your agent needs a language server or CLI tool, wrap it in a Docker MCP server so users don't need to install anything.
• One role per file — a manifest should define exactly one [[roles]] entry (the primary agent role). Additional helper roles are discouraged.
• Test with file:// source before submitting — see the local testing instructions above.

New domains are welcome — just be consistent and descriptive.

Skills are reusable instruction packs that inject domain knowledge into any Octomind session on demand. Unlike agents (which define a full role), skills are context injections — focused, composable knowledge that any agent can activate.

Skills live in skills/<name>/SKILL.md and follow the AgentSkills specification.

skill(action="list")                          # discover available skills
skill(action="list", pattern="git")           # filter by name or description
skill(action="use", name="git-workflow")      # inject skill into context
skill(action="forget", name="git-workflow")   # remove skill from context

---
name: skill-name
description: "What this skill does and when to use it."
license: Apache-2.0
compatibility: "Requires git. Works with any git-based project."
---

# Skill Title

## Overview
...

## Instructions
...

## Examples
...

# Copy the template
cp templates/skill.md skills/<name>/SKILL.md

# Edit and fill in frontmatter + body
# Then validate:
bash scripts/lint-skills.sh skills/<name>

# Or use the skill development agent:
octomind run octomind:skill

Apache 2.0 — see LICENSE.