---
name: uninstall-agent
description: Removes a locally-installed Claude Code subagent from `~/.claude/agents/` (user) or `.claude/agents/` (project). Deletes the `.md` file and the `.maxv-source-<name>.json` sidecar. Leaves the FTS5 catalog intact (the agent stays discoverable for future install). Twin of `install-agent`.
when_to_use: |
  Trigger phrases: "remova o subagente <name>", "uninstall agent <name>",
  "/maxvision-orchestration:uninstall-agent <name>".
  Also called by `orchestrate` when user explicitly asks to clean up after a one-shot task.
disable-model-invocation: true
allowed-tools: Read Bash(test *) Bash(jq *) Bash(rm *) Bash(date *) Bash(cat *) Bash(test -f *)
---

# Uninstall agent

Argument: `$ARGUMENTS` — `<agent-name> [--scope=user|project] [--keep-sidecar]`.

> **Hard rule:** confirm before deletion. Never auto-run.

## Workflow

### 1. Parse arguments

```bash
set -euo pipefail
AGENT_NAME=""
SCOPE="user"
KEEP_SIDECAR=0
for arg in $ARGUMENTS; do
  case "$arg" in
    --scope=*) SCOPE="${arg#--scope=}" ;;
    --keep-sidecar) KEEP_SIDECAR=1 ;;
    --*) printf '%s\n' "{\"error\":\"unknown flag: $arg\"}"; exit 2 ;;
    *) AGENT_NAME="$arg" ;;
  esac
done
test -n "$AGENT_NAME" || { printf '%s\n' '{"error":"agent name required"}'; exit 2; }
```

### 2. Resolve target

```bash
set -euo pipefail
if [ "$SCOPE" = "user" ]; then
  DEST_DIR=~/.claude/agents
else
  DEST_DIR=.claude/agents
fi
DEST_FILE="$DEST_DIR/$AGENT_NAME.md"
SIDECAR="$DEST_DIR/.maxv-source-$AGENT_NAME.json"

test -f "$DEST_FILE" || {
  printf '%s\n' "{\"error\":\"not installed\",\"path\":\"$DEST_FILE\"}"
  exit 3
}
```

### 3. Show plan + confirmation

```
About to remove agent: <AGENT_NAME>
  File:    <DEST_FILE>     (will be deleted)
  Sidecar: <SIDECAR>        (will be deleted unless --keep-sidecar)
  Catalog: FTS5 entry preserved — re-installable via install-agent.

Proceed? [sim/skip]
```

Wait for `sim`. On `skip`, exit 0.

### 4. Read sidecar metadata for log

```bash
set -euo pipefail
if [ -f "$SIDECAR" ]; then
  COMMIT_SHA=$(jq -r '.commit_sha // "unknown"' "$SIDECAR")
  SOURCE_ID=$(jq -r '.source_id // "unknown"' "$SIDECAR")
else
  COMMIT_SHA="unknown"
  SOURCE_ID="unknown"
fi
```

### 5. Remove

```bash
set -euo pipefail
rm -f "$DEST_FILE"
test "$KEEP_SIDECAR" -eq 1 || rm -f "$SIDECAR"
```

### 6. Update version-check cache (drop entry)

```bash
set -euo pipefail
CACHE=~/.claude/cache/maxv-orchestration/version-check.json
if [ -f "$CACHE" ]; then
  TMP=$(mktemp)
  jq --arg key "agent:$AGENT_NAME" 'del(.[$key])' "$CACHE" > "$TMP" && mv "$TMP" "$CACHE"
fi
```

### 7. Report

```
✓ Removed agent: <AGENT_NAME>
  File:    <DEST_FILE>            (deleted)
  Sidecar: <SIDECAR>               (deleted | kept)
  Catalog: still discoverable via discover-agent
  Take effect: next Claude Code session (current session retains the registration).
```

Append to log:
```
2026-05-04T22:35:00Z  uninstall-agent  python-pro  scope=user  was=<source>@<sha>  ok
```

### 8. Output JSON

```json
{
  "status": "uninstalled",
  "agent_name": "<name>",
  "removed_file": "<DEST_FILE>",
  "removed_sidecar": <true|false>,
  "catalog_preserved": true,
  "next_session_unregistered": true
}
```

## Guardrails

- **Single confirmation.** No batch removal across multiple agents — this skill takes one agent at a time. Caller (orchestrate) loops if needed.
- **Never delete files outside `~/.claude/agents/` or `<project>/.claude/agents/`.**
- **Never delete an agent that lacks a `.maxv-source.json` sidecar UNLESS `--force-orphan` is passed.** Files without sidecar are likely user-authored or installed by another tool. Refuse and ask.
- **Agent name validation:** must match `^[a-zA-Z][a-zA-Z0-9_-]*$`.
- **No catalog mutation.** FTS5 index.db is read-only from this skill's perspective.

## Error codes

| Exit | Meaning |
| ---: | --- |
| 0 | success or skipped |
| 2 | bad args |
| 3 | not installed at expected path |
| 4 | refused (orphan file, no sidecar) |