shared

star 392

Shared AgentOps skill contracts.

boshu2 By boshu2 schedule Updated 6/16/2026
play_arrow Run Skill in Manus View GitHub

name: shared description: 'Shared AgentOps skill contracts. Triggers: "shared", "shared agentops skill contracts.", "shared skill".' practices:

  • design-by-contract
  • pragmatic-programmer
  • twelve-factor-app hexagonal_role: domain consumes: [] produces:
  • stdout context_rel: [] skill_api_version: 1 user-invocable: false context: window: isolated intent: mode: none sections: exclude:
    • HISTORY
    • INTEL
    • TASK intel_scope: none metadata: tier: library internal: true output_contract: reference documents (loaded JIT)

Shared References

This directory contains shared reference documents used by multiple skills:

  • validation-contract.md - Verification requirements for accepting spawned work
  • references/claude-code-latest-features.md - Claude Code feature contract (slash commands, agent isolation, hooks, settings)
  • references/backend-claude-teams.md - Concrete examples for Claude native teams (TeamCreate + SendMessage)
  • references/backend-codex-subagents.md - Concrete examples for Codex CLI and Codex sub-agents
  • references/backend-background-tasks.md - Fallback: Task(run_in_background=true)
  • references/backend-inline.md - Default single-agent mode (no spawn) — the baseline, not a degradation
  • references/claude-cli-verified-commands.md - Verified Claude CLI command shapes and caveats
  • references/codex-cli-verified-commands.md - Verified Codex CLI command shapes and caveats
  • references/cli-command-failures-2026-02-26.md - Dated failure log and mitigations from live runs

These are not directly invocable skills. They are loaded by other skills (council, crank, swarm, research, implement) when needed.

CLI Availability Pattern

All skills that reference external CLIs MUST degrade gracefully when those CLIs are absent.

Check Pattern

# Before using any external CLI, check availability
if command -v bd &>/dev/null; then
  # Full behavior with bd
else
  echo "Note: bd CLI not installed. Using plain text tracking."
  # Fallback: use TaskList, plain markdown, or skip
fi

Fallback Table

Capability When Missing Fallback Behavior
bd Issue tracking unavailable Use TaskList for tracking. Note "install bd for persistent issue tracking"
ao Knowledge flywheel unavailable Write learnings to .agents/learnings/ directly. Skip flywheel metrics
out-of-session substrate (ntm / ao agent) Always-on orchestration unavailable Run the loop in-session (/rpi, /evolve). A substrate (an NTM tmux swarm or managed-agents via ao agent) only adds always-on dispatch of whole operating-loop or /evolve skill runs — see agent-native and docs/3.0.md
gt Workspace management unavailable Work in current directory. Skip convoy/sling operations
gh PR/CI automation unavailable Open PRs via the web UI; skip automated PR status/merge steps
go Build-from-source unavailable Install a prebuilt ao (Homebrew / install script / release binary); no Go needed
codex CLI missing or model unavailable Fall back to runtime-native agents. Council pre-flight checks CLI presence (which codex) and model availability for --mixed mode.
cass Session search unavailable Skip transcript search. Note "install cass for session history"
jq JSON parsing unavailable Read --json output manually or use non-JSON output modes
rg (ripgrep) Fast search unavailable Fall back to grep / git grep (slower)
Model tier config .agentops/config.yaml missing Use built-in defaults (quality=opus, balanced=sonnet, budget=haiku). Tier resolution falls through to "balanced".

Full per-tool purpose, required-vs-optional, and fallback detail: docs/dependencies.md. The README "Requirements" section summarizes; this doc page is the canonical detail.

Required Multi-Agent Capabilities

Council, swarm, and crank require a runtime that provides these capabilities. If a capability is missing, the corresponding feature degrades.

Capability What it does If missing
Spawn subagent Create a parallel agent with a prompt Cannot run multi-agent. Fall back to --quick (inline single-agent).
Agent-to-agent messaging Send a message to a specific agent No debate R2. Workers run fire-and-forget.
Broadcast Message all agents at once Per-agent messaging fallback.
Graceful shutdown Request an agent to terminate Agents terminate on their own when done.
Shared task list Agents see shared work state Lead tracks manually.

Every runtime maps these capabilities to its own API. Skills describe WHAT to do, not WHICH tool to call.

After detecting your backend (see Backend Detection below), load the matching reference for concrete tool call examples:

Backend Reference
Claude feature contract skills/shared/references/claude-code-latest-features.md
Claude Native Teams skills/shared/references/backend-claude-teams.md
Codex Sub-Agents / CLI skills/shared/references/backend-codex-subagents.md
Background Tasks (fallback) skills/shared/references/backend-background-tasks.md
Inline (no spawn) skills/shared/references/backend-inline.md

Backend Detection

Use capability detection at runtime, not hardcoded tool names. The same skill must work across any agent harness that provides multi-agent primitives. If no multi-agent capability is detected, degrade to single-agent inline mode (--quick).

Selection policy (NTM > runtime-native > beads floor):

Global opt-out first: if AGENTOPS_ORCHESTRATION=off is set, skip all spawn backends and degrade to the beads floor (single-agent inline / --quick; workers' work is tracked through bd). This mirrors the AGENTOPS_HOOKS_DISABLED=1 convention. Otherwise, select in this order:

  1. NTM (top tier). If ntm is on PATH, capability-probe it with ntm --robot-capabilities. When the probe confirms multi-agent primitives, use NTM as the primary backend.
  2. Runtime-native. If NTM is unavailable: in a Claude session with TeamCreate/SendMessage, use Claude Native Teams; in a Codex session with spawn_agent, use Codex sub-agents. If both are technically available, pick the backend native to the current runtime unless the user explicitly requests mixed/cross-vendor execution. Only use background tasks when neither native backend is available.
  3. Beads floor. If no multi-agent capability is detected, degrade to single-agent inline mode (--quick).

gc is NOT a selectable tier. AgentOps no longer references Gas City; out-of-session orchestration is delegated to a swappable substrate (NTM + MCP + managed-agents — see docs/3.0.md). Any residual gc-based dispatch prose in older swarm/crank reference files is historical only and is never selected.

Output-contract parity is unchanged across all tiers: workers write results to .agents/swarm/results/*.json, and the lead verifies-then-trusts those artifacts. This invariant holds whether the backend is NTM, a runtime-native team, or the beads floor.

Operation Codex Sub-Agents Claude Native Teams OpenCode Subagents Inline Fallback
Spawn spawn_agent(message=...) TeamCreate + Task(team_name=...) task(subagent_type="general", prompt=...) Execute inline
Spawn (read-only) spawn_agent(message=...) Task(subagent_type="Explore") task(subagent_type="explore", prompt=...) Execute inline
Wait wait(ids=[...]) Completion via SendMessage Task returns result directly N/A
Retry/follow-up send_input(id=..., message=...) SendMessage(type="message", ...) task(task_id="<prior>", prompt=...) N/A
Cleanup close_agent(id=...) shutdown_request + TeamDelete() None (sub-sessions auto-terminate) N/A
Inter-agent messaging send_input SendMessage Not available N/A
Debate (R2) Supported Supported Not supported (no messaging) N/A

OpenCode limitations:

  • No inter-agent messaging — workers run as independent sub-sessions
  • No debate mode (--debate) — requires messaging between judges
  • --quick (inline) mode works identically across all backends

Backend Capabilities Matrix

Prefer native teams over background tasks. Native teams provide messaging, redirect, and graceful shutdown. Background tasks are fire-and-forget with no steering — only a speedometer and emergency brake.

Capability Codex Sub-Agents Claude Native Teams Background Tasks
Observe output wait() result SendMessage delivery TaskOutput (tail)
Send message mid-flight send_input SendMessage NO
Pause / resume NO Idle → wake via SendMessage NO
Graceful stop close_agent shutdown_request TaskStop (lossy)
Redirect to different task send_input SendMessage NO
Adjust scope mid-flight send_input SendMessage NO
File conflict prevention Manual git worktree routing Native isolation: worktree + lead-only commits None
Process isolation YES (sub-process) Shared worktree Shared worktree

When to use each:

Scenario Backend
Quick parallel tasks, coordination needed Claude Native Teams
Codex-specific execution Codex Sub-Agents
No team APIs available (last resort) Background Tasks

Skill Invocation Across Runtimes

Skills that chain to other skills (e.g., /rpi calls /research, /validate calls /council) MUST handle runtime differences:

Runtime Tool Behavior Pattern
Claude Code Skill(skill="X", args="...") Executable — skill runs as a sub-invocation Skill(skill="council", args="--quick validate recent")
Codex N/A Skills not available — inline the logic or skip Check if Skill tool exists before calling
OpenCode skill tool (read-only) Load-only — returns <skill_content> blocks into context Call skill(skill="council"), then follow the loaded instructions inline

OpenCode skill chaining rules:

  1. Call the skill tool to load the target skill's content into context
  2. Read and follow the loaded instructions directly — do NOT expect automatic execution
  3. NEVER use slashcommand syntax (e.g., /council) in OpenCode — it triggers a command lookup, not skill loading
  4. If the loaded skill references tools by Claude Code names, use OpenCode equivalents (see tool mapping below)

Cross-runtime tool mapping:

Claude Code OpenCode Notes
Task(subagent_type="...") task(subagent_type="...") Same semantics, different casing
Skill(skill="X") skill tool (read-only) Load content, then follow inline
AskUserQuestion question Same purpose, different name
TaskCreate, TaskUpdate, TaskList, TaskGet todo Task tracking (Claude uses 4 tools, OpenCode uses 1)
Read, Write, Edit, Bash, Glob, Grep Same names Identical across runtimes

Rules

  1. Never crash — missing CLI = skip or fallback, not error
  2. Always inform — tell the user what was skipped and how to enable it
  3. Preserve core function — the skill's primary purpose must still work without optional CLIs
  4. Progressive enhancement — CLIs add capabilities, their absence removes them cleanly

Reference Documents

Install via CLI
npx skills add https://github.com/boshu2/agentops --skill shared
Repository Details
star Stars 392
call_split Forks 40
navigation Branch main
article Path SKILL.md
More from Creator
boshu2
boshu2 Explore all skills →