SOPilot

SOPilot runs workflow-oriented Agent Skills under SOP control for the current invocation only. It keeps the selected workflow in charge of step order, checkpoints, user prompts, and artifacts while the agent can still use tools and other skills as delegated subroutines.

Plain skills stay plain. SOPilot is active only when explicitly invoked.

Workflow Skills

A workflow skill is an Agent Skill whose instructions define a multi-step process rather than a single action. It usually has ordered phases, required inputs, checkpoints, stop conditions, and artifacts that must be created or updated along the way.

For example:

---
name: incident-review
description: Guide an agent through incident review, evidence gathering, root cause analysis, and follow-up planning.
---

# Incident Review

## Parameters

- **incident_summary** (required): What happened and where to begin investigating

## Steps

### 1. Gather Context

Ask for missing incident details and collect relevant logs, links, screenshots, or files.
Stop after confirming the investigation scope.

### 2. Investigate

Trace the likely failure path, document evidence, and ask before changing systems.

### 3. Summarize

Write findings, root cause, corrective actions, and open questions.

SOPilot is useful when that workflow must stay in control across turns, even if the user provides details that look like a different task.

Agent Experience

Users invoke SOPilot naturally with a target workflow skill:

$sopilot workflow-skill-name

Replace workflow-skill-name with the installed workflow skill you want SOPilot to control.

The agent should then:

• resolve the target workflow skill
• load SOPilot's orchestration contract
• load the target skill instructions
• run the target workflow under the contract for this invocation only
• keep treating follow-up messages as workflow input until the user explicitly pauses, cancels, stops, or switches away

For example, if a planning workflow asks for input and the user replies with a bug report, SOPilot keeps that bug report inside the active planning workflow instead of switching to an unrelated debugging workflow.

Without SOPilot, the target skill behaves normally:

$workflow-skill-name

Local Setup

Install SOPilot as a local Agent Skill by placing skills/sopilot in the host agent's skills directory. For Codex local testing, that is usually:

~/.codex/skills/sopilot

After changing installed skills, force-reload skills or restart the host agent if the update is not visible.

Runtime Helper

SOPilot's bundled helper resolves the target skill and returns the files the agent must read:

python3 scripts/sopilot.py activate workflow-skill-name --json

activate is read-only for the target skill. It does not inject prompts, write metadata, or replace installed skills.

Runtime Behavior

SOPilot uses skills/sopilot/contracts/workflow-skill-orchestration.md as the runtime contract. The same continuation rules also live in skills/sopilot/SKILL.md, because the loaded SOPilot skill must carry the control-flow rules across turns.

The key rules are:

• the target workflow owns control flow while SOPilot is active
• follow-up messages at workflow prompts are workflow input, not new objectives
• workflow switches require an explicit pause, cancel, stop, or switch request
• other skills and tools are allowed only as delegated subroutines inside the current workflow step

Advanced Utilities

These commands materialize wrapped copies and are not the default SOPilot experience. Use them only when a host requires modified skill files or when explicitly experimenting with generated wrapped skills.

Wrap skills without installing:

python3 scripts/sopilot.py wrap /path/to/skills --output-dir ./wrapped-skills --json

Install wrapped copies:

python3 scripts/sopilot.py install /path/to/skills --json

Create contract-only wrapped skills:

python3 scripts/sopilot.py wrap /path/to/skills --adapter none --output-dir ./workflow-skills --json

Adapters

The runtime contract is agent-neutral. Adapter-specific behavior lives behind the script's adapter registry:

• codex: resolves common Codex skill locations and writes agents/openai.yaml for advanced wrapping/installing
• none: writes no metadata; useful for contract-only output or future adapter development

To add another agent, add a new adapter that provides its default install destination, metadata writer, and install verifier, then register it in ADAPTERS.

Development

The reusable wrapper lives in skills/sopilot/scripts/sopilot.py. The skills/sopilot/ directory packages that wrapper as a local skill for agents that support Agent Skills.

Validate the local skill package with the target host's skill validator when available. For Codex local development:

python3 /home/rubencu/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/sopilot