# Maintain AI Hub Backup Repo

> Maintain the user's AI hub repo (GitHub will12193/ai), the source of truth for the global skills and instructions that are mirrored into ~/.copilot on every machine. Use when: the user asks to add, change, rename or remove any Copilot skill, instruction, or MCP config; is about to edit anything under ~/.copilot/skills or ~/.copilot/instructions (pull first, edit in the repo); mentions the 'ai hub', 'ai repo', 'sync.sh', 'sync.ps1', or backing up or syncing Copilot config between machines.

- Skill: `will12193/maintain-ai-hub-backup-repo` (Agent Skill)
- Install (CLI): `npx get-skill add will12193/maintain-ai-hub-backup-repo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/will12193/maintain-ai-hub-backup-repo/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: will12193 (https://skillmd.com/u/will12193)
- Updated: 2026-11-19
- Page: https://skillmd.com/skills/will12193/maintain-ai-hub-backup-repo

---


# Maintain the AI hub repo

Companion to `~/.copilot/instructions/coding-agents.instructions.md` (global rules and skill map) and to `maintain-global-agent-config` (what may change and the disclosure duty); this file covers the hub repo and its sync scripts only.

The hub repo (GitHub: will12193/ai; `~/dev/ai` on macOS and inside WSL on the Windows home machine, `C:\Users\willc\Documents\dev\ai` on the Windows side of it, see `windows-home-machine`) is the **source of truth** for `skills/` and `instructions/`. The sync script mirrors them into `~/.copilot` so every machine has the same set. Two equivalent scripts exist: `sync.sh` (bash, rsync, python3) and `sync.ps1` (Windows PowerShell 5.1, no extra tools). "The sync script" below means whichever matches the machine.

## Golden rule

**Edit `skills/` and `instructions/` in the repo, never in `~/.copilot`.** `~/.copilot` is a mirror: the next sync would overwrite direct edits, so the script refuses to run while `~/.copilot` differs from the last commit and lists the differences. If a tool wrote there anyway, copy the wanted files into the repo and re-run.

Any change to global files must also follow `maintain-global-agent-config` (disclose it under a "Global Agent Behaviour Change" header at the end of the message).

| Path | Source of truth |
|---|---|
| `skills/`, `instructions/` | the repo (mirrored into `~/.copilot/skills/` and `~/.copilot/instructions/`) |
| `mcp-config.redacted.json` | generated in the repo from `~/.copilot/mcp-config.json` (secrets redacted; that file exists only in `~/.copilot`) |
| `README.md` tables between the `GENERATED` markers | generated by the sync script from each file's frontmatter |
| Rest of `README.md`, `sync.sh`, `sync.ps1`, `.gitignore`, `.gitattributes` | edited directly in the repo, never mirrored |

## Workflow for any requested change

Commands: `<repo>/sync.sh pull|push ["msg"]`, or on Windows `powershell -NoProfile -ExecutionPolicy Bypass -File C:\Users\willc\Documents\dev\ai\sync.ps1 pull|push ["msg"]`.

1. **Pull first.** Run `sync pull` before editing anything. It does `git pull --ff-only` and mirrors the repo into `~/.copilot`, so this machine has what the others pushed. Run it at the start of any task that may touch skills or instructions.
2. **Edit in the repo** (skills, instructions, the hand-written README, the scripts, `.gitignore`). Write frontmatter `description`s so the part before `Use when:` reads as a one-line human summary; the README is generated from it. MCP config is the one thing edited in `~/.copilot` (then pushed to regenerate the redacted copy).
3. **Push.** Run `sync push "<what changed and why>"` (`push` is the default if only a message is given). The message is the commit message; make it say the intent (e.g. `"Add health-check skill for context read-outs"`), not just "update". Without a message it falls back to `Backup <date>`. The script checks the remote has nothing newer, regenerates the README tables, scans for secrets, mirrors the repo into `~/.copilot`, commits and pushes. Do not run a separate commit/push for synced content.
4. Verify: the output says `Backed up.` (or `No changes to back up.`), and `git -C <repo> status -s` is clean.
5. Run edits and the sync as **separate steps**, never in the same tool batch, or an edit can land after the script's `git add`.

## Sync failures

- `~/.copilot differs from the last commit` → something edited `~/.copilot` directly (or a skill exists there that the repo lacks). The list shows what differs: `sync.sh` prints `diff -rq` output (`Only in <~/.copilot path>` is an extra file there, `Only in <commit path>` is missing from `~/.copilot`, `differ` is modified); `sync.ps1` prints `+` only in `~/.copilot`, `~` modified, `-` missing from `~/.copilot`. Copy anything worth keeping into the repo, then re-run; the mirror overwrites the rest.
- `The remote has commits that are not in this checkout` (push) → another machine pushed since your last pull. `git stash`, `sync pull`, `git stash pop`, re-run push.
- `Repo has uncommitted edits in skills/ or instructions/` (pull) → pull refuses with edits pending. Run `sync push` first, or stash.
- `Possible secret found` → stop, tell the user which file, do not push.
- Push fails with `Permission denied (publickey)` on Windows → ssh-agent has no key; see `windows-home-machine`.

## Platform notes

- A WSL environment is its own machine as far as the hub is concerned: it has its own clone and its own `~/.copilot`, and uses `sync.sh` (needs only `git`, `rsync`, `python3`). A Windows machine with WSL therefore has two clones, each mirroring into its own `~/.copilot`; the remote check in `push` stops one overwriting the other. After changing `sync.sh` itself, run `git pull --ff-only` by hand in the other clones before `sync pull`, because the old script runs first.
- The first `pull` on a machine whose `~/.copilot/skills` and `instructions` are empty skips the "differs from the last commit" check (nothing to lose); earlier versions failed there on a fresh machine.
- `sync.ps1` compares and writes text with LF endings (Windows files may be CRLF; the repo stores LF, enforced by `.gitattributes`). Without that every file would show as changed.
- `sync.ps1` does not redact `mcp-config.json`: it leaves `mcp-config.redacted.json` untouched and prints a note if the source exists. Port the redaction before relying on it. `sync.sh` redacts whenever the file exists.
- Pull and push mirror with delete semantics, so a skill removed in the repo disappears from every machine's `~/.copilot` on its next pull. That is intended: all machines hold the same set.

## README requirements

`README.md` is for humans. The Instructions and Skills tables are generated; keep the hand-written parts accurate: what the repo is, how pull/push work, the MCP note, and what is deliberately not backed up.

## Don'ts

- Don't back up session history, databases, logs, or the unredacted `mcp-config.json`.
- Don't commit secrets; keep the sync's secret scan in place.
- Don't edit `~/.copilot/skills` or `~/.copilot/instructions` directly, and don't hand-edit the generated README tables.

## Maintaining This Skill File

Update this file (not `maintain-global-agent-config`) when the repo layout, `sync.sh`/`sync.ps1` behaviour, README generation or restore steps change, or when a sync fails for a reason worth recording (symptom, cause, fix). Keep entries short.

