# Update

> Update is an Agent Skill for devops & security published in the Q00/ouroboros repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Check for updates and upgrade Ouroboros to the latest version

- Skill name: `update`
- Category: [DevOps & Security](https://www.openparable.com/skill/devops-security/1)
- Source: https://github.com/Q00/ouroboros/blob/HEAD/skills/update/SKILL.md
- Repository: Q00/ouroboros (4,903 GitHub stars when collected)

## SKILL.md

# /ouroboros:update

Check for updates and upgrade Ouroboros (PyPI package + runtime integration).

## Usage

```
ooo update
/ouroboros:update
```

**Trigger keywords:** "ooo update", "update ouroboros", "upgrade ouroboros"

## Instructions

When the user invokes this skill:

1. **Check current version**:

   First, try reading the version from the CLI binary (works for all install methods):
   ```bash
   ouroboros --version 2>/dev/null
   ```

   If that fails, try the plugin version:
   ```bash
   cat .claude-plugin/plugin.json 2>/dev/null | python3 -c "import sys,json; print(json.load(sys.stdin).get('version','unknown'))" 2>/dev/null
   ```

   If both fail, the package is not installed — skip to step 3.

2. **Check latest version on PyPI**:

   First, determine if the current installed version is a pre-release (contains `a`, `b`, `rc`, or `dev`).

   If the current version **is a pre-release**, scan all PyPI releases to find the latest (including betas):
   ```bash
   python3 -c "
   import json, ssl, urllib.request
   from packaging.version import Version
   ctx = ssl.create_default_context()
   data = json.loads(urllib.request.urlopen('https://pypi.org/pypi/ouroboros-ai/json', timeout=5, context=ctx).read())
   versions = [Version(v) for v in data.get('releases', {}) if data['releases'][v]]
   print(str(max(versions)) if versions else data['info']['version'])
   "
   ```

   If the current version **is stable**, use the standard latest:
   ```bash
   python3 -c "
   import json, ssl, urllib.request
   ctx = ssl.create_default_context()
   data = json.loads(urllib.request.urlopen('https://pypi.org/pypi/ouroboros-ai/json', timeout=5, context=ctx).read())
   print(data['info']['version'])
   "
   ```

3. **Compare and report**:

   If already on the latest version:
   ```
   Ouroboros is up to date (v0.X.Y)
   ```

   If a newer version is available, show:
   ```
   Update available: v0.X.Y → v0.X.Z

   Changes: https://github.com/Q00/ouroboros/releases/tag/v0.X.Z
   ```

   Then ask the user with AskUserQuestion:
   - **"Update now"** — Proceed with update
   - **"Skip"** — Do nothing

4. **Run update** (if user chose to update):

   a. **Update PyPI package** — detect the original install method and preserve `[mcp,claude]` extras:

   Check which installer was used:
   ```bash
   uv tool list 2>/dev/null | grep -q ouroboros && echo "uv"
   pipx list 2>/dev/null | grep -q ouroboros && echo "pipx"
   ```

   > This skill runs inside Claude Code, so always use `ouroboros-ai[mcp,claude]`
   > (includes `mcp` for the MCP server plus `claude-agent-sdk` and `anthropic`
   > required for MCP tools).

   - If installed via **uv tool** (most common with install.sh):
     ```bash
     # For pre-release targets:
     uv tool install --upgrade --prerelease=allow 'ouroboros-ai[mcp,claude]'
     # For stable targets:
     uv tool install --upgrade 'ouroboros-ai[mcp,claude]'
     ```

   - If installed via **pipx**:
     > `pipx upgrade` cannot add extras to an existing venv — use `install --force` to reinstall with extras.
     ```bash
     # For pre-release targets:
     pipx install --force --pip-args='--pre' 'ouroboros-ai[mcp,claude]'
     # For stable targets:
     pipx install --force 'ouroboros-ai[mcp,claude]'
     ```

   - If installed via **pip** (fallback):
     ```bash
     # For pre-release targets:
     python3 -m pip install --upgrade --pre 'ouroboros-ai[mcp,claude]'
     # For stable targets:
     python3 -m pip install --upgrade 'ouroboros-ai[mcp,claude]'
     ```

   > **Note**: The `[mcp,claude]` extras are critical. Omitting `[mcp]` makes the MCP
   > server fail to boot (ImportError at startup); omitting `[claude]` causes MCP
   > tools to fail silently at call time.

   b. **Update runtime integration**:

   For Claude Code:
   ```bash
   claude plugin marketplace update ouroboros 2>/dev/null || true
   claude plugin install ouroboros@ouroboros
   ```

   For Codex CLI (re-install skills/rules to ~/.codex/):
   ```bash
   ouroboros setup --runtime codex --non-interactive
   ```

   c. **Refresh MCP server config** (fixes stale args from older versions):

   Run the same setup command used in step b to ensure MCP config is current:

   For Claude Code:
   ```bash
   ouroboros setup --runtime claude --non-interactive
   ```

   For Codex CLI (already handled by step b above — skip this step).

   This ensures `~/.claude/mcp.json` has the latest MCP command and args
   (e.g., `ouroboros-ai[mcp,claude]` extras). Skips if already up to date.

   d. **Verify and update CLAUDE.md version marker**:
   ```bash
   NEW_VERSION=$(ouroboros --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+[a-z0-9.]*')
   echo "Installed: v$NEW_VERSION"

   if [ -n "$NEW_VERSION" ] && grep -q "ooo:VERSION" CLAUDE.md 2>/dev/null; then
     OLD_VERSION=$(grep "ooo:VERSION" CLAUDE.md | sed 's/.*ooo:VERSION:\(.*\) -->/\1/' | tr -d ' ')
     if [ "$OLD_VERSION" != "$NEW_VERSION" ]; then
       sed -i.bak "s/<!-- ooo:VERSION:.*-->/<!-- ooo:VERSION:$NEW_VERSION -->/" CLAUDE.md && rm -f CLAUDE.md.bak
       echo "CLAUDE.md version marker updated: v$OLD_VERSION → v$NEW_VERSION"
     else
       echo "CLAUDE.md version marker already up to date (v$NEW_VERSION)"
     fi
   fi
   ```

   > **Note**: This only updates the version marker. If the block content itself
   > changed between versions, the user should run `ooo setup` to regenerate it.

5. **Post-update guidance**:
   ```
   Updated to v0.X.Z

   Restart your Claude Code session to apply the update.
   (Close this session and start a new one with `claude`)

   If CLAUDE.md block content changed, regenerate it:
     ooo setup

   Run `ooo help` to see what's new.
   ```

## Notes

- The update check uses PyPI as the source of truth for the latest version.
- Plugin update (Claude Code) pulls the latest from the marketplace.
- No data is lost during updates — event stores and session data are preserved.
- **Always use the same installer** that was used for the original installation (uv tool > pipx > pip).

## RFC #1392 State Breadcrumb Footer

Your final response MUST end with exactly one breadcrumb footer line:

```
◆ <current state> → next: <recommended action>
```

Derive `<current state>` from live session state via `ouroboros_session_status` when that MCP projection is available; otherwise derive it from this skill's actual outcome. Never use a linear `Step N of M` footer because Ouroboros is an evolutionary loop. When the next action is genuinely a choice, list 2-3 honest options in the `next:` clause. The breadcrumb line must be the last line of the response.

---

Source: https://www.openparable.com/skill/devops-security/update (OpenParable). Cite the canonical URL above.