Back to Tap View Source

tap-deps-authoring

Skill

Complete guide for writing dep scripts in the octomind-tap registry: required header comments, platform.sh boilerplate, type: mcp vs type: dep, npx/uvx MCP pattern, platform variables and functions, companion .md format, and validation. Activate when creating or editing deps/<org>/<tool>.sh files.

Apache-2.0 Requires: octomind-tap repo. Run scripts/lint-deps.sh for validation.

Instructions

Overview

A dep script is a deps/<org>/<tool>.sh bash script that installs a tool or MCP server runtime. Octomind runs every [deps] require entry of a manifest's capabilities before MCP initialisation, and a capability's deps again when it is activated at runtime. Every script must be idempotent and handle macOS and the major Linux package managers.

Runtime contract: Octomind invokes bash <script> (Git Bash on Windows), so the executable bit is not required. stdin is closed, stdout is discarded, stderr is captured and shown only when the script fails; exit 0 means ready, non-zero aborts the session start or the activation with that stderr.

Each dep script must have a matching deps/<org>/<tool>.md companion doc.

Rules

Required Header Comments

Every dep script starts with these header comments, exactly on lines 1–6 in this order (lint-deps.sh checks them by line number):

bash
#!/usr/bin/env bash
# dep: <org>/<tool>
# type: mcp|dep
# description: Brief description of what this installs
# check: <command-to-verify-installation>
# https://homepage-url
  • # dep: — must equal the file path (deps/<org>/<tool>.sh → <org>/<tool>) and the require entry in the capability file
  • # type: mcp — script ensures an MCP server runtime is runnable (e.g. npx, uvx, docker)
  • # type: dep — script installs a standalone CLI tool used directly (e.g. cargo, kubectl, octofs)
  • # description: — 10–160 chars
  • # check: — the command that proves the tool is installed
  • line 6 — homepage URL starting with # https://

Type Classification

type: mcp — the dep exists to make an MCP server launchable. Most MCP servers run via npx -y <package> or uvx <package>. The dep script just ensures the runtime is present:

bash
#!/usr/bin/env bash
# dep: tavily-ai/tavily
# type: mcp
# description: Tavily MCP Server — AI-powered web search
# check: npx
# https://github.com/tavily-ai/tavily-mcp

set -euo pipefail

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

if pkg_check npx; then exit 0; fi
install_dep nodejs/node

type: dep — the dep installs a real CLI tool that agents use directly (not via MCP):

bash
#!/usr/bin/env bash
# dep: hashicorp/terraform
# type: dep
# description: Terraform infrastructure-as-code CLI
# check: terraform
# https://developer.hashicorp.com/terraform

set -euo pipefail

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

if pkg_check terraform; then exit 0; fi

info "terraform not found — installing..."

case "$OS" in
  macos)
    brew_install terraform
    ;;
  linux)
    case "$PKG_MANAGER" in
      apt)    apt_install terraform ;;
      dnf)    dnf_install terraform ;;
      pacman) pkg_install terraform ;;
      zypper) pkg_install terraform ;;
      apk)    pkg_install terraform ;;
      *)
        curl -fsSL https://releases.hashicorp.com/terraform/install.sh | sh
        ;;
    esac
    ;;
esac

pkg_check terraform || die "terraform not found after install"
info "terraform installed successfully."

Full Script Structure

bash
#!/usr/bin/env bash
# dep: <org>/<tool>
# type: mcp|dep
# description: Brief description
# check: <command>
# https://homepage

set -euo pipefail

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

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

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

case "$OS" in
  macos)
    brew_install <formula>
    ;;
  linux)
    case "$PKG_MANAGER" in
      apt)    apt_install <pkg> ;;
      dnf)    dnf_install <pkg> ;;
      pacman) pkg_install <pkg> ;;
      zypper) pkg_install <pkg> ;;
      apk)    pkg_install <pkg> ;;
      *)
        # Universal fallback
        curl -fsSL https://example.com/install.sh | sh
        ;;
    esac
    ;;
esac

pkg_check "<command>" || die "<tool> not found after install"
info "<tool> installed successfully."

Platform Variables (from deps/lib/platform.sh)

VariableValues
$OSmacos, linux, or windows (Git Bash/MSYS)
$ARCHx86_64 or arm64
$PKG_MANAGERbrew, apt, dnf, pacman, zypper, apk, unknown
$IS_MACOS1 or 0
$IS_LINUX / $IS_WINDOWS1 or 0
$IS_ARM641 or 0
$IS_X86_641 or 0

Platform Functions (from deps/lib/platform.sh)

FunctionPurpose
pkg_check <cmd>Returns 0 if command exists — use for fast-path and post-install verify
pkg_install <pkg>Install via the detected package manager (same name everywhere); dies when none is found
brew_install <formula>macOS only, no-op elsewhere
apt_install <pkg>Debian/Ubuntu only, no-op elsewhere
dnf_install <pkg>Fedora/RHEL only, no-op elsewhere
as_root <cmd...>Run as root directly or via sudo; dies when neither is available
install_dep <org/tool>Run another dep script as a prerequisite; sources PATH after
info <msg>Print informational message to stderr
warn <msg>Print warning to stderr
die <msg>Print error to stderr and exit 1

Never re-implement platform detection — always source deps/lib/platform.sh (it also sets set -euo pipefail).

Companion Documentation

Every .sh must have a matching .md at the same path (deps/<org>/<tool>.md).

For MCP servers (type: mcp) — copy templates/dep-mcp.md, must include:

  • ## MCP Server — package name, transport, launch command
  • ## Authentication — required env vars and how to obtain them
  • ## Available Tools — list of tools the MCP server exposes
  • ## Configuration Example — example [[mcp.servers]] TOML block

For plain deps (type: dep) — copy templates/dep-tool.md, must include:

  • ## Key Commands — most important CLI commands
  • ## Common Usage — typical usage patterns with examples

Validation

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

Checks: header lines 2–6 present in order, # dep: matches the file path, description length, # type: set, companion .md exists with an H1 equal to <org>/<tool> and the required ## sections for its type. It does not check platform coverage or the executable bit — test the script yourself on an installed and a clean machine.

Examples

Example 1: MCP server via npx (minimal)

bash
#!/usr/bin/env bash
# dep: modelcontextprotocol/filesystem
# type: mcp
# description: MCP filesystem server — requires Node.js/npx
# check: npx
# https://github.com/modelcontextprotocol/servers

set -euo pipefail

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

if pkg_check npx; then exit 0; fi
install_dep nodejs/node

Example 2: MCP server via uvx (Python)

bash
#!/usr/bin/env bash
# dep: myorg/mcp-server
# type: mcp
# description: My Python MCP server — requires uvx
# check: uvx
# https://github.com/myorg/mcp-server

set -euo pipefail

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

if pkg_check uvx; then exit 0; fi
install_dep astral-sh/uv

Example 3: GitHub release binary install

bash
#!/usr/bin/env bash
# dep: muvon/octofs
# type: dep
# description: Installs the octofs CLI from GitHub releases
# check: octofs
# https://github.com/muvon/octofs

set -euo pipefail

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

if pkg_check octofs; then exit 0; fi

case "$OS" in
  macos)
    brew_install muvon/tap/octofs
    ;;
  linux)
    INSTALL_DIR="$HOME/.local/bin"
    mkdir -p "$INSTALL_DIR"
    VERSION=$(curl -fsSL "https://api.github.com/repos/muvon/octofs/releases" \
      | grep '"tag_name":' | head -1 | sed -E 's/.*"([^"]+)".*/\1/')
    case "$ARCH" in
      x86_64) TARGET="x86_64-unknown-linux-musl" ;;
      arm64)  TARGET="aarch64-unknown-linux-musl" ;;
    esac
    curl -fsSL "https://github.com/muvon/octofs/releases/download/$VERSION/octofs-$VERSION-$TARGET.tar.gz" \
      | tar xz -C "$INSTALL_DIR"
    chmod +x "$INSTALL_DIR/octofs"
    export PATH="$INSTALL_DIR:$PATH"
    ;;
esac

pkg_check octofs || die "octofs not found after install"

Example 4: Common mistake — re-implementing platform detection

bash
# WRONG — never do this
if [[ "$(uname)" == "Darwin" ]]; then
  brew install something
fi

# RIGHT — source platform.sh and use its functions
DEPS_LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" && pwd)"
source "$DEPS_LIB/platform.sh"
brew_install something

Checklist

  • File at deps/<org>/<tool>.sh (org matches GitHub org or tool namespace)
  • Header comments on lines 2–6 in order: # dep:, # type:, # description:, # check:, URL
  • Sources deps/lib/platform.sh — never re-implements platform detection
  • Fast-path pkg_check exit at top; idempotent on an installed machine
  • Handles macos + all Linux package managers + universal fallback; nothing written to stdout that matters
  • Post-install pkg_check verify with die on failure
  • Companion deps/<org>/<tool>.md exists, its H1 is <org>/<tool>, and it has the sections for its type
  • bash scripts/lint-deps.sh deps/<org>/<tool>.sh passes clean

References

  • templates/dep.sh — canonical dep script template (copy to start)
  • templates/dep-mcp.md — companion doc template for MCP servers
  • templates/dep-tool.md — companion doc template for plain deps
  • deps/lib/platform.sh — platform detection library (source in all dep scripts)
  • bash scripts/lint-deps.sh — validates dep scripts
View on GitHub