> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custodian skills

Custodian skills are release-versioned operational playbooks shipped with OpenClaw. They live under `custodian-skills/` in the package and load at the bundled-skill precedence tier, but only for the agent resolved by `agents.defaults.systemAgent.agentId`.

When that setting is absent, OpenClaw falls back to a retained legacy default owner, the sole configured agent, or legacy `main` when no explicit agent roster exists. If several agents are configured without a system agent or retained legacy owner, no agent receives the library. For every other agent, Custodian skills are absent from discovery, snapshots, slash-command catalogs, sandbox sync, and the model-facing skills prompt.

Normal skill controls still apply. `skills.entries.<name>.enabled: false` disables an individual Custodian skill, and agent skill allowlists can narrow the final set. See [Skills config](/tools/skills-config).

## Workflow contract

Every shipped Custodian skill uses the same five sections in this order:

1. **Gather** reads redacted current config and probes live state.
2. **Mutate** uses validated non-interactive writes — `openclaw config set` / `openclaw config patch` from a trusted shell, or the in-session Custodian tool actions where policy allows — never a direct file edit.
3. **Repair** diagnoses with `openclaw doctor --lint`; only an explicitly approved repair uses `openclaw doctor --fix --non-interactive`. The read-only `diagnose-gateway` skill recommends that separate step but never runs it.
4. **Prove** exercises one live end-to-end outcome.
5. **Report** records what changed, what was observed, and what remains.

All five-section playbooks keep secret values out of prompts, logs, and files. Credentials use SecretRefs or credential stores. A workflow never claims success without its Prove outcome; it reports the exact blocker when live proof is unavailable.

Lint exit code `1` means findings, not a failed diagnostic command: read the report and continue the remaining checks. Ordinary `doctor`, including `--non-interactive`, can copy legacy config and migrate state without `--fix`; it is not a read-only substitute. Read-only diagnostics exclude config/service repairs and state migrations, not incidental logs or cache bookkeeping. See [Doctor](/cli/doctor#lint-mode).

## First wave

| Skill                | Outcome                                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `configure-channel`  | Configure and send a confirmed test message through a channel family such as Discord, Slack, Telegram, or WhatsApp. |
| `add-model-provider` | Configure API-key or subscription/OAuth provider access and run one live Gateway inference.                         |
| `diagnose-gateway`   | Perform read-only Gateway, config, SecretRef, channel-auth, log, and port triage.                                   |
| `cloud-image-bake`   | Bake a Cloud Worker image, prove it with a timed dispatch, and safely retire the superseded snapshot.               |

## Roadmap catalog

The following catalog documents intended later tiers. These names are roadmap entries, not bundled skills or promises of current behavior.

### Tier 2: common operations

* `configure-search`: configure and live-prove a search provider.
* `create-agent`: create an agent, verify its workspace, and prove one turn.
* `manage-plugin`: install, configure, verify, or remove an approved plugin.
* `rotate-credential`: rotate one supported credential through its owning store and prove the consumer.
* `upgrade-openclaw`: stage an upgrade, run health checks, and verify rollback readiness.

### Tier 3: advanced operations

* `fleet-rollout`: roll out one verified config or release across managed Gateways.
* `incident-response`: collect redacted evidence, contain an incident, and verify recovery.
* `migrate-gateway`: move a Gateway while preserving explicit state and identity contracts.
* `release-validation`: run release-track package, install, and live behavior proof.
* `restore-backup`: restore into an isolated target, validate state, and cut over deliberately.

## Add an operator skill

Put local additions in the configured Custodian agent's workspace, not in the release-owned package directory:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
<custodian-workspace>/skills/<skill-name>/SKILL.md
```

Workspace skills already have higher precedence than the bundled tier and are scoped to that agent's workspace. Follow the same Gather → Mutate → Repair → Prove → Report contract, keep the description short, and start a new session after changing the skill. See [Creating skills](/tools/creating-skills) for the full format.

## Related

* [Skills](/tools/skills)
* [Skills config](/tools/skills-config)
* [Cloud Workers](/gateway/cloud-workers)
* [Gateway troubleshooting](/gateway/troubleshooting)