Maintaining the global agent files
Companion to ~/.copilot/instructions/coding-agents.instructions.md (global rules and skill map); this file covers when and whether to change a global file and the duties that follow. Structure and sizing rules are in maintain-authoring-agent-instructions-and-skills; the backup/sync mechanics are in maintain-ai-hub-backup-repo.
The global files are mirrored into ~/.copilot/instructions/ and ~/.copilot/skills/, which is where they are loaded from, but their source of truth is the ai hub repo: edit them in the repo, never directly in ~/.copilot (the sync script refuses to run over direct edits). Pull before editing and push after; see "Mandatory: pull before, push after" below and maintain-ai-hub-backup-repo. They are loaded alongside repo-specific instruction and skill files (e.g. a project's own copilot-instructions.md or platform-api-* skills). They should evolve as knowledge gaps and preferences are discovered, so the next session doesn't have to rediscover them.
Scope: global only
Only maintain the global files: instructions/ and skills/ in the ai hub repo, which are mirrored into ~/.copilot/instructions/ and ~/.copilot/skills/ (including this skill and coding-agents.instructions.md).
- Never edit a repo's own instruction or skill files from this skill. If a lesson belongs to one repo, follow that repo's own maintenance rules (or tell the user) instead.
- Never make a repo file reference the global layer. Repo files are shared with teammates who don't have
~/.copilot; they must stand alone (details inmaintain-authoring-agent-instructions-and-skills, section 0). - Add here only what is relevant to all coding, regardless of repo. Example: the user says "you should always do X"; if X applies to every repo, it goes in global files; if X is about one codebase, it doesn't.
- When unsure whether something is global or repo-specific, ask the user.
Where things go
instructions/coding-agents.instructions.md: short rules that must apply to every session (always loaded, so keep it lean). Behaviours, communication preferences, universal coding preferences.- A new or existing skill under
skills/: anything procedural, situational or long. Prefer a skill over growing the always-loaded instructions. - Maintenance rules like these belong in this skill, not in the instructions.
- For how to structure, size and scope instruction files and skills (lean always-loaded instructions that orchestrate scoped skills), load
maintain-authoring-agent-instructions-and-skills. ~/.copilot/mcp-config.json: only change when asked. It is the one global file edited in place (it holds secrets and is never mirrored).
When to add an entry
- The user states a preference or rule ("always", "never", "from now on").
- The user corrects a wrong assumption that would recur in any repo.
- You spent several tool calls working out a cross-repo pattern or command that isn't documented.
- You hit a problem whose cause/fix wasn't obvious and would recur elsewhere.
Don't document one-off trivia.
How
- Extend an existing section or file over adding a new one.
- Keep entries short: rule, and for gotchas symptom / cause / fix. Include exact error text so future greps match.
- You have freedom to learn the user's coding preferences and to create new skills on your own initiative when a skill is clearly applicable (e.g. a repeated multi-step workflow). Keep new skills focused, with a trigger-rich
description. - Delete or fix entries that turn out to be wrong or obsolete.
Mandatory: tell the user, every time
These files sit outside version control from the user's point of view, so they won't know about changes unless told. Never change, create, rename or delete any global file without explicitly telling the user in chat.
At the end of the final message of the turn, add a section with this header:
## Global Agent Behaviour Change
List each file touched, what changed (added / modified / removed) and why, in a line or two each. If the turn changed nothing global, omit the section.
Mandatory: pull before, push after
Before editing any global file, run sync pull (see maintain-ai-hub-backup-repo) so this machine has the other machines' changes, then make the edit in the hub repo. After any change to the global files, run the hub's sync script with push "<what changed and why>" (sync.sh, or sync.ps1 on Windows; invocation is in maintain-ai-hub-backup-repo), which regenerates the README tables, mirrors the repo into ~/.copilot, commits and pushes. Confirm it printed Backed up. and mention the sync in the Global Agent Behaviour Change section.
Maintaining This Skill File
Update this file when the user changes the rules for what counts as global, how changes must be disclosed, or what must happen after a change. Keep entries short.