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

When that setting is absent, Apus 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.

Workflow contract

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

1. Gather reads redacted current config and checks live state.
2. Mutate uses validated non-interactive writes, never a direct file edit. Those writes are apus config set / apus config patch from a trusted shell, or the in-session Custodian tool actions where policy allows.
3. Repair diagnoses with apus doctor --lint. Only an explicitly approved repair uses apus 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.

First wave

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-apus: 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:

<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. Start a new session after changing the skill. See Creating skills for the full format.

Related

• Skills
• Skills config
• Cloud Workers
• Gateway troubleshooting