Skill

Pass

Audit score 90

shared

boshu2/agentops

Shared reference contracts and CLI patterns for AgentOps multi-agent skills.

What is shared?

A library skill (not directly invocable) that provides shared reference documents, validation contracts, and backend detection patterns used by other AgentOps skills like council, crank, and swarm. Load these references when spawning subagents or degrading gracefully when external CLIs are unavailable.

Provides validation contracts and reference documents for multi-agent spawning across Claude Code, Claude Teams, Codex, and inline fallback modes
Defines CLI availability checks and graceful degradation patterns for external tools (bd, ao, ntm, gt, gh, go, codex, cass, jq, rg)
Documents backend detection logic: NTM > runtime-native > beads floor (single-agent inline)
Specifies output-contract parity across all execution tiers (workers write to .agents/swarm/results/*.json)
Lists verified CLI command shapes and dated failure logs from live runs
Maps required multi-agent capabilities (spawn, messaging, broadcast, shutdown, shared task list) to concrete tool examples per backend

How to install shared

npx skills add https://github.com/boshu2/agentops --skill shared

Claude Code

Cursor

Windsurf

Cline

How to use shared

1.Install via npx skills add https://github.com/boshu2/agentops --skill shared
2.Other skills automatically load references from this skill when needed (JIT loading)
3.Check CLI availability using the provided pattern (e.g., command -v bd &>/dev/null) before using external tools
4.Detect backend at runtime using capability probes (ntm --robot-capabilities, TeamCreate/SendMessage presence, spawn_agent availability)
5.Select backend in order: NTM > runtime-native > beads floor (inline single-agent)
6.Load the matching reference file (backend-claude-teams.md, backend-codex-subagents.md, etc.) for concrete tool call examples

Use cases

Good for

Council skill loads backend-specific references to spawn debate workers across different runtimes
Crank skill checks for bd CLI availability and falls back to TaskList-based tracking when bd is absent
Swarm skill detects NTM presence and capability-probes it; falls back to Claude Teams or inline mode if unavailable
Research skill references claude-code-latest-features.md to use slash commands and agent isolation hooks
Implement skill consults backend-codex-subagents.md for concrete Codex spawn_agent call patterns

Who it's for

Skill developers building multi-agent orchestration (council, crank, swarm, research, implement)
AgentOps framework maintainers defining contracts across runtimes
Teams deploying agents across mixed backends (Claude, Codex, NTM) who need consistent degradation behavior

shared FAQ

Is this skill directly invocable?

No. This is a library skill marked user-invocable: false. It is loaded by other skills (council, crank, swarm, research, implement) when they need reference documents or validation contracts.

What should I do if an external CLI (bd, ao, ntm, codex) is missing?

Check availability using command -v <tool> &>/dev/null before using it. If absent, fall back to the specified behavior: bd → TaskList, ao → write to .agents/learnings/ directly, ntm/codex → inline single-agent mode, etc.

How do I choose between Claude Teams, Codex, and inline mode?

Detect at runtime in order: (1) Check if ntm is on PATH and probe capabilities; (2) Check if runtime-native multi-agent is available (TeamCreate/SendMessage for Claude, spawn_agent for Codex); (3) Fall back to inline single-agent. Never hardcode tool names.

What is the 'beads floor'?

Single-agent inline mode (--quick) with no spawn capability. It is the fallback when no multi-agent backend is detected. Workers' work is tracked via bd or plain markdown.

Do output contracts differ across backends?

No. All tiers (NTM, runtime-native, inline) maintain the same output-contract parity: workers write results to .agents/swarm/results/*.json, and the lead verifies-then-trusts those artifacts.

Full instructions (SKILL.md)

Source of truth, from boshu2/agentops.

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:

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

Call the skill tool to load the target skill's content into context
Read and follow the loaded instructions directly — do NOT expect automatic execution
NEVER use slashcommand syntax (e.g., /council) in OpenCode — it triggers a command lookup, not skill loading
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

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