القائمة
Shared AgentOps skill contracts. Triggers: "shared", "shared agentops skill contracts.", "shared skill".
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| 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) |
This directory contains shared reference documents used by multiple skills:
validation-contract.md - Verification requirements for accepting spawned workreferences/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-agentsreferences/backend-background-tasks.md - Fallback: Task(run_in_background=true)references/backend-inline.md - Default single-agent mode (no spawn) — the baseline, not a degradationreferences/claude-cli-verified-commands.md - Verified Claude CLI command shapes and caveatsreferences/codex-cli-verified-commands.md - Verified Codex CLI command shapes and caveatsreferences/cli-command-failures-2026-02-26.md - Dated failure log and mitigations from live runsThese are not directly invocable skills. They are loaded by other skills (council, crank, swarm, research, implement) when needed.
WARN|FAIL|REFUTED -> AUTO-REDO: consult the pawl, repair the reference, selection, or fallback mismatch, then rerun the same validator. Why: an ordinary contract mismatch is recovery evidence, not a human andon.BREAKER -> HOLD -> ONE-HELPER; HELPER-UNSTUCK -> AUTO-REDO. Hold dispatch and use one bounded local-shell helper to inspect the missing capability or contradictory contract. Why: one recovery pass can distinguish stale documentation from a genuine unavailable boundary.HELPER-ESCALATE -> HUMAN; REFUSAL-LANE|EXPLICIT-JUDGMENT|EXHAUSTED-BUDGET -> HUMAN. Why: runtime selection, authority expansion, unresolved refusal, or exhausted recovery belongs to the operator.All skills that reference external CLIs MUST degrade gracefully when those CLIs are absent.
# Before using any external CLI, check availability
if command -v br &>/dev/null; then
# Full behavior with br
else
echo "Note: br CLI not installed. Using plain text tracking."
# Fallback: use TaskList, plain markdown, or skip
fi
| Capability | When Missing | Fallback Behavior |
|---|---|---|
br | Issue tracking unavailable | Use TaskList for tracking. Note "install br 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.
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 |
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 (operator choice > runtime-native > inline floor):
Global opt-out first: if AGENTOPS_ORCHESTRATION=off is set, skip all spawn backends and degrade to the inline floor (single-agent inline / --quick; persistent work may still be tracked through br). This mirrors the AGENTOPS_HOOKS_DISABLED=1 convention. Otherwise, select in this order:
ntm --robot-capabilities and use it only when the probe confirms the required primitives. Agent Mail and managed agents are likewise opt-in components of that substrate.--quick) and report the missing capability.Gas City is a separate, coexisting substrate. Generic backend detection never auto-selects it. When the operator explicitly chooses city-shaped work, enter through
using-gc; its membrane and bd/Dolt substrate contracts remain separate from this runtime-native backend table.
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:
--debate) — requires messaging between judges--quick (inline) mode works identically across all backendsPrefer 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 |
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:
skill tool to load the target skill's content into context/council) in OpenCode — it triggers a command lookup, not skill loadingCross-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 |
Artifact directory: no runtime artifact is created by shared; canonical reference outputs live under skills/shared/, with backend-specific documents under skills/shared/references/.
Filename convention: SKILL.md owns backend-neutral policy, validation-contract.md owns spawned-work acceptance, and references/<topic>.md owns one bounded backend or cross-skill contract.
Serialization/schema format: Markdown contracts with repository-relative links; command examples must match the named runtime and preserve the backend-neutral capability semantics in this file.
Validator command: run bash skills/shared/scripts/validate.sh, then bash scripts/audit-codex-parity.sh --skill shared after source or Codex projection changes.
Downstream handoff: pass the exact reference path loaded, detected capabilities, operator-selected execution shape, chosen fallback, skipped capabilities, and validator results to the consuming skill.
Show AgentOps project status.
Show AgentOps work status. Triggers: "status", "show agentops work status.", "status skill".
Provide repo coding standards.
Provide repo coding standards. Triggers: "standards", "provide repo coding standards.", "standards skill".
Shared AgentOps skill contracts.
Run repository security scans for vulnerabilities, dependency risk, secrets, and release gates. Triggers: security review, release security, scan this repository.