# Agent Backup

> Mirror your AI assistant's live config (skills, persona, settings, custom plugins) to a private git remote. Run on a schedule via cron — secrets and runtime state are excluded by an allowlist .gitignore. Use when asked for a manual backup, or when a backup cron fires.

- Skill: `quietdaemon/agent-backup` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add quietdaemon/agent-backup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/quietdaemon/agent-backup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: quietdaemon (https://skillmd.com/u/quietdaemon)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/quietdaemon/agent-backup

---


# Agent Config Backup

Snapshot your assistant's live config to a private git remote so a fresh box can
be rebuilt in minutes if this one dies. The whole trick is an **allowlist**
`.gitignore`: you commit *only* the things you've explicitly named, so a stray
secret can never sneak into the backup.

## When to use

- A scheduled backup cron fires (e.g. nightly).
- The user says "back up now" / "force a backup" / "push the config".
- After installing a new skill, persona, or plugin and the change should be
  preserved before the next scheduled window.

## What's included vs. excluded

Tune these to your setup. The pattern that matters: **default-deny, then allow.**

**Included** (committed + pushed):

- `skills/` — your custom skills (SKILL.md + helper scripts)
- the persona/system file (e.g. `<SOUL_OR_SYSTEM_PROMPT_FILE>`)
- the main config file (model, providers, toolset toggles)
- `scripts/` — helper scripts
- any custom plugin source you maintain

**Excluded** (must never leave the box):

- the secrets file (`.env` or equivalent) — **all credentials**
- chat history / memory databases
- re-cloneable caches and git mirrors
- generated artifacts (images, downloads) and runtime logs

### Allowlist `.gitignore` (the safe pattern)

```gitignore
# Default deny everything…
/*
# …then re-allow only what you intend to back up:
!skills/
!scripts/
!config.yaml
!<SOUL_OR_SYSTEM_PROMPT_FILE>
# Belt-and-suspenders: never commit secrets even if re-included above
**/.env
**/*secret*
```

## How to invoke

Run the helper script via your shell/terminal tool (not a sandboxed code tool
that lacks git/network access):

```bash
bash <AGENT_HOME>/scripts/backup.sh
```

It prints one JSON line summarizing the run:

```json
{"ok": true, "changed": true, "commit": "a1b2c3d", "files_changed": 4, "pushed": true}
```

Clean run with nothing to do:

```json
{"ok": true, "changed": false, "commit": null, "files_changed": 0, "pushed": false}
```

Failure:

```json
{"ok": false, "error": "...", "stage": "commit|push"}
```

See [`backup.sh`](backup.sh) for a ready-to-adapt implementation.

## Cron

Schedule it however your platform does cron (a system crontab line, or your
agent's built-in scheduler). A `--no-agent`-style script run costs no LLM
tokens — the script does the work, its stdout is the result.

## Pitfalls

- **Use an allowlist `.gitignore`, not a denylist.** A denylist fails open — the
  day you add a new secret file you forgot to exclude, it ships. An allowlist
  fails closed.
- **Never name a file `.gitignore` inside a skill subfolder** if you keep a
  template of these rules in another repo — git will treat it as nested,
  scope-limited rules. Store the template under a different name (e.g.
  `gitignore.template`) and only the real root copy stays active.
- **Never `--amend` or force-push.** Always a fresh commit, so history stays
  linear and auditable.
- **On a partial failure** (e.g. one optional file can't be staged), still push
  the rest — a mostly-current backup beats none.
- **Surface auth errors immediately** — a push auth failure usually means the
  deploy key rotated or was revoked.
- **Never echo the secrets file or any credential**, even in error output.