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"].
- 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.
- Edit in the repo (skills, instructions, the hand-written README, the scripts,
.gitignore). Write frontmatter descriptions 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).
- 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.
- Verify: the output says
Backed up. (or No changes to back up.), and git -C <repo> status -s is clean.
- 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.
1---2name: maintain-ai-hub-backup-repo3description: "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."4metadata:5 source: https://skillmd.com/skills/will12193/maintain-ai-hub-backup-repo6---78# Maintain the AI hub repo910Companion 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.1112The 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.1314## Golden rule1516**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.1718Any 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).1920| Path | Source of truth |21|---|---|22| `skills/`, `instructions/` | the repo (mirrored into `~/.copilot/skills/` and `~/.copilot/instructions/`) |23| `mcp-config.redacted.json` | generated in the repo from `~/.copilot/mcp-config.json` (secrets redacted; that file exists only in `~/.copilot`) |24| `README.md` tables between the `GENERATED` markers | generated by the sync script from each file's frontmatter |25| Rest of `README.md`, `sync.sh`, `sync.ps1`, `.gitignore`, `.gitattributes` | edited directly in the repo, never mirrored |2627## Workflow for any requested change2829Commands: `<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"]`.30311. **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.322. **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).333. **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.344. Verify: the output says `Backed up.` (or `No changes to back up.`), and `git -C <repo> status -s` is clean.355. 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`.3637## Sync failures3839- `~/.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.40- `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.41- `Repo has uncommitted edits in skills/ or instructions/` (pull) → pull refuses with edits pending. Run `sync push` first, or stash.42- `Possible secret found` → stop, tell the user which file, do not push.43- Push fails with `Permission denied (publickey)` on Windows → ssh-agent has no key; see `windows-home-machine`.4445## Platform notes4647- 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.48- 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.49- `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.50- `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.51- 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.5253## README requirements5455`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.5657## Don'ts5859- Don't back up session history, databases, logs, or the unredacted `mcp-config.json`.60- Don't commit secrets; keep the sync's secret scan in place.61- Don't edit `~/.copilot/skills` or `~/.copilot/instructions` directly, and don't hand-edit the generated README tables.6263## Maintaining This Skill File6465Update 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.