# Maintain Global Agent Config

> Rules for evolving William's GLOBAL agent files (instructions/ and skills/, sourced from the ai hub repo and mirrored into ~/.copilot): when to add or change a rule or skill, what scope belongs there, and the mandatory pull, disclosure and push steps. Use when: the user says 'you should always...', 'never...', 'from now on', corrects a wrong assumption or preference that applies to all repos, a knowledge gap or recurring pattern is discovered that is relevant to all coding regardless of repo, or you are about to create/edit/delete any file under ~/.copilot/instructions or ~/.copilot/skills, regardless of which tool or skill makes the edit. This is a policy layer (when/whether to change, disclosure, sync); it does not cover file-format mechanics, which belong to any built-in customization tooling.

- Skill: `will12193/maintain-global-agent-config` (Agent Skill)
- Install (CLI): `npx get-skill add will12193/maintain-global-agent-config`
- Raw SKILL.md: https://api.skillmd.com/api/skills/will12193/maintain-global-agent-config/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-global-agent-config

---


# 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 in `maintain-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.

